ulk

AI Development Toolkit pour Claude Code.

Pourquoi "ulk" ?

Bruce, de son vrai nom Ulk, est un Vallhund suédois — une race de chien viking millénaire, trapue et intrépide, surnommée "le chien des Vikings".

Comme son ancêtre qui accompagnait les drakkars à travers les mers nordiques, Ulk accompagne les développeurs à travers les océans de code. Petit mais costaud, il ne recule devant aucun défi.

Le nom "ulk" signifie "loup" en vieux norrois.

Installation

# Homebrew (recommandé)
brew install izo/tap/ulk
ulk install

Ou depuis le dépôt cloné :

./install.sh                          # Installation de base (Figma + Swift + Flutter + 5 skills Obsidian/kepano)

# Skills additionnelles (opt-in)
./install.sh --with-figma-mcp                # + configurer le serveur MCP Figma
./install.sh --with-addy-skills              # + skills addyosmani
./install.sh --with-a11y-skills              # + skills accessibilité (RAWeb/RAAM)
./install.sh --with-nothing-design           # + Nothing design system (dominikmartn)
./install.sh --with-hue-skill                # + Hue design language generator (dominikmartn, MIT)
./install.sh --with-logo-generator-skill     # + logo generator (SVG+PNG, Gemini API)
./install.sh --with-cwb-app-icon             # + AppIcon natif iOS/macOS (SnapAI, OpenAI key)
./install.sh --with-caveman-skill            # + /caveman-compress (compression CLAUDE.md, -46%)
./install.sh --with-caveman-output-skill     # + /caveman output mode (-79% tokens rapports agents)
./install.sh --with-session-defaults         # + /session-defaults — env vars token economy (CLAUDE_CODE_DISABLE_1M_CONTEXT + CLAUDE_AUTOCOMPACT_PCT_OVERRIDE)
./install.sh --with-web-design-skill         # + /web-design-guidelines (vercel-labs, MIT — review UI a11y/focus/semantics)
./install.sh --with-kami-skill               # + kami (documents pro IA — One-Pager, Letter, Slides…)
./install.sh --with-visual-explainer-skill   # + /visual-explainer — sortie terminal → HTML (Mermaid, diff-review, slides, project-recap)
./install.sh --with-ai-adoption-skill        # + /ai-adoption — part de code IA détectée depuis git (méthodo loupe, 0 token)
./install.sh --with-ehmo-web-skill           # + web-platform-guidelines (WCAG 2.2 + MDN, 70+ règles)
# Sélection Camille Roux 2026 v3 (opt-in)
./install.sh --with-token-efficient-skill    # + drop-in CLAUDE.md -63% tokens output (drona23)
./install.sh --with-claude-seo-skill         # + audit SEO + GEO universel (AgriciDaniel)
./install.sh --with-claude-health-skill      # + audit config Claude Code 6 couches (tw93)
./install.sh --with-understand-anything-skill # + knowledge graph interactif codebase (Lum1104)
./install.sh --without-obsidian-skills       # opt-out 5 skills kepano (bundlées par défaut)

# Hooks et modes
./install.sh --with-vps                      # + agents VPS
./install.sh --with-teams                    # + Agent Teams (expérimental)
./install.sh --with-memory-loop              # + hooks Knowledge Vault Loop
./install.sh --with-xavier-hook              # + SessionStart Xavier (carte contexte, 0 tokens)
./install.sh --with-cli-telemetry            # + suivi usage CLI → ./tools/cli-report.sh
./install.sh --with-accountability           # + audit trail mutations → .ulk-reports/accountability.jsonl
./install.sh --with-context-mode             # + Context Mode (économie -$8 à -$24/mois output tokens)
./install.sh --with-statusline               # + statusline ulk (cwd · modèle · ctx% · P0 · git hash)
./install.sh --with-managed-agents           # + Managed Agents Anthropic (sessions cloud, 5 agents portés)
./install.sh --with-faru                     # + mode faru (kanban git-natif agent-first)
./install.sh --with-sentinel                 # + hook Sentinel (cascade pre-push/pre-deploy)
./install.sh --with-code-graph               # + Code Review Graph MCP (gain -8.2× audits monorepo)

# Bundles CLIs (opt-in)
./install.sh --with-container-clis           # docker · kubectl · helm · k9s · lazydocker
./install.sh --with-monitoring-clis          # vegeta · hyperfine · gping · mtr
./install.sh --with-ai-clis                  # ollama · apfel · aider · llm
./install.sh --with-doc-clis                 # mdbook · vale · markdownlint-cli2
./install.sh --with-data-clis                # jq · yq · csvkit · duckdb · visidata
./install.sh --with-design-clis              # imagemagick · ffmpeg · svgo · sharp-cli
./install.sh --with-devops-clis              # terraform · ansible · pulumi · act
./install.sh --with-mobile-clis              # xcrun · bundler · fastlane · expo · eas-cli

# Diagnostic
./install.sh --install-deps                  # Installer les CLIs manquants (sélecteur interactif)
./install.sh --check                         # Diagnostic CLI + Skills
./install.sh --verify                        # Vérifier l'installation
./install.sh --dry-run                       # Simuler sans modifier

# Optionnel (macOS 26+ Apple Silicon)
brew install Arthur-Ficial/tap/apfel         # LLM local Apple Intelligence

Mise à jour : git pull && ./install.sh — Désinstallation : ./install.sh --uninstall

CLI Go (v6)

Binaire Go unique distribué via Homebrew. install.sh reste un wrapper de compatibilité.

ulk install [--with-*]        # TUI wizard au premier run — 72 modules typés
ulk update [--check]          # diff SHA256 checksums, rollback auto sur erreur
ulk rollback                  # restaure le backup précédent (~/.ulk/backups/)
ulk status [--json]           # modules ✓/○ + version
ulk verify                    # chemins + prérequis + LLM locaux
ulk check [--impact] [--json] # CLIs + skills installés
ulk doctor [--fix]            # diagnostic + auto-fix (state, schema, prérequis)
ulk clean [--dry-run]         # supprimer les fichiers orphelins (agents/skills renommés)
ulk migrate                   # migration state.json v0→v1
ulk self-update [--check]     # mise à jour binaire avec vérification SHA256
ulk install-deps              # installer les CLIs manquants (sélecteur interactif)
ulk dashboard [--serve]       # TUI dashboard — CLIs, Skills, Agents, mises à jour
ulk export --target all       # exporter le contexte ulk pour Codex CLI / Gemini CLI / Mistral Vibe
ulk ma <agent> "<prompt>"     # Managed Agents Anthropic — session cloud SSE
ulk completion bash|zsh|fish  # autocomplétion shell

État persistant dans ~/.ulk/state.json (écriture atomique, SchemaVersion 1). Backup/rollback automatique dans ~/.ulk/backups/. 72 modules typés (Skill, Hook, Config, MCP, External, Bundle, Rules).

Présentation des écrans : docs/installateur-go-ecrans.md

Par où commencer

Commande	Ce que ça fait
/ulk:bruce	Point d'entrée principal — détecte l'état du projet et orchestre tout
/ulk:godspeed	Diagnostic rapide : stack, état, prochaine action suggérée
/ulk:shuri	Pipeline doc : spec → todo Kanban → sync
/ulk:sargeras	Audit omniscient 10 axes avec score et verdict
/ulk:2b3	Checkpoint fin de session : lint → docs → commit
/ulk:strange	Reverse doc (code → docs) · mode=prompt : reverse-engineering de prompt (output IA → prompt probable)
/ulk:georges	Réalisateur de vidéos IA — tutoriels, démos, showcases via claude-code-video-toolkit (Remotion + TTS + FLUX)

Pas besoin de mémoriser les slash commands. Bruce et les autres orchestrateurs s'invoquent aussi en langage naturel : "bruce", "ulk", "status", "next", "go", "checkpoint", "wrap up". Claude Code détecte l'intent et route vers le bon agent. Les /ulk:* restent disponibles pour les usages scriptés.

Mobile Natif

Pipeline complet web-vers-mobile en 3 agents :

happy (49)  →  docs/api/  →  steve (27) + fluke (48)
   API architect      OpenAPI 3.1      iOS/macOS    Android/Flutter

• Happy audite le projet web, conçoit l'API REST/GraphQL complète (auth, push, offline sync)
• Steve lit docs/api/ et génère un starter kit SwiftUI compilable (+ 7 Swift skills bundlés)
• Fluke lit docs/api/ et génère un starter kit Kotlin/Compose ou Flutter (+ 2 Flutter skills bundlés)

Apple Intelligence (optionnel)

Sur macOS 26+, ulk delegue les micro-taches (extraction, classification, resume) a Apfel — Apple Intelligence en local, gratuit, 0 tokens Claude.

brew install Arthur-Ficial/tap/apfel   # installer
./install.sh --check                   # verifier la detection

2 agents l'utilisent actuellement (godspeed, 2b3) — fallback Claude si absent. Protocole unifié : framework/agents/_shared/local-llm-protocol.md. Roadmap : task-runner (commit msg), ci-guard (classification erreur CI), shuri (frontmatter YAML).

Multiplateforme : ollama gemma3:1b couvre les mêmes micro-tâches sur Linux/Windows (128K ctx, diffs longs) :

brew install ollama && ollama pull gemma3:1b   # multiplateforme

Community Skills (bundlés)

Collection	Skills	Source
Figma (7)	figma-use, figma-implement-design, figma-code-connect, figma-generate-library, figma-generate-design, figma-create-design-system-rules, figma-create-new-file	Figma Inc.
Swift (7)	SwiftUI Pro, SwiftData Pro, Concurrency, Testing, A11y, Architecture, Security	twostraws + communauté
Flutter (2)	Flutter Tester, OWASP Mobile Security	Harishwarrior
Obsidian / kepano (5)	obsidian-markdown, obsidian-bases, obsidian-cli, json-canvas, defuddle	Steph Ango (kepano), MIT
context-audit (1)	/context-audit — health score 0-100 : MCP servers, CLAUDE.md bloat, skills, settings	Vesely/skills
symbols (1)	/symbols list|view|refs — navigation LSP TS/JS, -40 à -74% tokens sur fichiers > 150L	ulk, MIT
architecture-diagram (1)	diagrammes HTML+SVG self-contained, 100% local	Cocoon-AI, MIT

Bundlés par défaut : Figma, Swift, Flutter, Obsidian/kepano, context-audit, symbols, architecture-diagram.
Config MCP Figma : ./install.sh --with-figma-mcp · Opt-out kepano : --without-obsidian-skills
Opt-in : --with-nothing-design · --with-a11y-skills · --with-hue-skill · --with-logo-generator-skill · --with-cwb-app-icon · --with-caveman-output-skill · --with-session-defaults · --with-kami-skill.

Plugins Marketplace

Skills installées via le marketplace Claude Code intégré (pas via install.sh) :

• ui-ux-pro-max-skill (nextlevelbuilder, 72.8k★) — lookup design contextuel : 161 palettes industry-specific, 57 font pairings, 99 UX guidelines, 25 chart types × 15 stacks. Complémentaire à /hue (génération vs lookup). Install : /plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
• pomodoro (jakedahn) — timer + mémoire SQLite (sessions, analytics, patterns). Install : /plugin marketplace add jakedahn/pomodoro

Multi-LLM (v6) — Codex CLI · Gemini CLI · Mistral Vibe

ulk est désormais portable vers trois CLI IA alternatives via ulk export. Les fichiers de contexte et sous-agents sont versionnés dans le repo.

Fichier	Plateforme	Contenu
AGENTS.md	OpenAI Codex CLI + Mistral Vibe	93 agents groupés, 17 KB (limite 32 KiB Codex)
GEMINI.md	Google Gemini CLI	Contexte + 6 sous-agents dans .gemini/agents/
.vibe/agents/	Mistral Vibe	6 configs TOML (mistral-medium-3-5 / small-3-1 / nemo)
.gemini/agents/	Gemini CLI	6 agents Markdown (bruce · godspeed · sargeras · 2b3 · task-runner · verify)

ulk export --target codex    # → AGENTS.md
ulk export --target gemini   # → GEMINI.md + .gemini/agents/
ulk export --target mistral  # → .vibe/agents/
ulk export --target all      # → tous les formats
ulk export --target all --output /path/to/project  # → autre répertoire

Protocole : framework/agents/_shared/multi-provider-protocol.md

Managed Agents (Anthropic beta)

Sessions Claude Code cloud — pas besoin de machine locale. Activation : ./install.sh --with-managed-agents.

5 agents portés : ed209 · sargeras · 2b3 · ci-guard · lovecraft-memory-capture. Invocation : ulk ma <agent> "<prompt>".

Accountability (Audit Trail)

./install.sh --with-accountability active un PostToolUse hook qui trace deux journaux complémentaires dans <projet>/.ulk-reports/ (gitignored) :

Journal	Contenu	Tools tracés
accountability.jsonl	Mutations agents (taille du diff, head de commande)	Edit · Write · MultiEdit · NotebookEdit · Bash
read-coverage.jsonl	Lectures de fichiers (taille fichier, offset, limit) — calcule le ratio doc loadable / doc effectivement lue	Read

./framework/tools/accountability-report.sh                  # synthèse mutations
./framework/tools/accountability-report.sh --read-coverage  # rapport read coverage (ratio par fichier + global)
./framework/tools/accountability-report.sh --since 2026-05-01 --json

Le journal read-coverage.jsonl est inspiré de nav-stats (alekspetrov/navigator) — voir spike docs/research/spike-navigator-skills.md (ULK-280). Il complète Gandalf (34) et /context-audit côté détection de token waste : un fichier > 200 lignes lu en entier pour une info ponctuelle devient un candidat à /symbols (LSP). Un fichier relu plusieurs fois (ratio > 200%) devient un candidat à loads_files: ou à une entrée mémoire _memory/.

Spec complète : framework/accountability/protocol.md.

Prérequis

• Claude Code 2.1+ — claude.ai/code (Desktop, Web, ou CLI ; native binary recommandé depuis 2.1.113)
• git — cloner et mettre à jour ulk
• Node.js 18+ — pour les générateurs (cheatheet/)
• macOS, Linux, ou Windows — install.sh (bash/Git Bash) ; PowerShell tool natif sur Windows depuis CC 2.1.84
• curl — pour l'installation distante (déjà présent sur macOS/Linux)

Compatibilité Claude Code 2.1

ulk tire parti des features récentes de Claude Code :

Feature CC	Version	Usage ulk
Skills hot-reload	2.1.0	Agents et skills disponibles immédiatement après ajout, sans redémarrage
Auto-memory natif	2.1.32+	Coexiste avec lovecraft (47) et le memory loop opt-in (--with-memory-loop)
Hooks SessionEnd/PreCompact	2.1.85, 2.1.105	Alternative aux routines cron pour 2b3 (checkpoint automatique)
/loop natif	2.1.71	Recommandé en remplacement progressif des cron-based routines (Routine 53)
/branch (ex /fork)	2.1.71	Forks de conversation pour explorer plusieurs pistes
isolation: "worktree"	2.1.49	Audits propres (Sargeras, ED-209) — voir docs/todo.md ULK-207
Subagent forké	2.1.117	CLAUDE_CODE_FORK_SUBAGENT=1 réduit la pollution contexte des orchestrateurs
Opus 4.8 / Sonnet 4.6 / Haiku 4.5	2.1.111+	Alias opus/sonnet/haiku dans frontmatter — résolution auto vers la dernière version
effort: frontmatter	2.1.111+	Override le niveau d'effort par sous-agent (xhigh opus, low haiku) — protège la qualité même si la session est sur un effort plus bas
opusplan model alias	2.1.x	Opus en plan mode, Sonnet en exécution — non recommandé pour ulk (Bruce orchestre hors plan mode)

Agents (93)

Liste complète par catégorie : framework/agents/registry.md

Catégories : orchestrators/ · docs/ · audit/ · session/ · mobile/ · sync/ · routines/ · frontend/ · analyze/ · deploy/ · test/ · vps/

Derniers ajouts (56-70) : Killbill (cost killer + killswitch) · Xavier (vérif contexte) · Stark (designer en chef) · Alex (musitech) · Agathe (DA garante du goût) · Mathieu (Senior Product Strategist) · Frodo (audit générationnel) · Jean-Claude (support virtuel issues) · Benjamin (devil's advocate & DD lens) · Verify (65) (spec ↔ code conformance, câblé dans 2b3/bruce/task-runner) · Harper (66) (adversarial review — N reviewers en compétition, carrot + stick) · Minitel (67) (UX Writer — microcopy, voice & tone, modes write/audit/voice/localize) · doc-reset (68) (audit + réparation documentaire, mode --fix) · feedback-loop (69) (méta-analyse patterns d'échec inter-sessions via accountability.jsonl) · skills-radar (70) (veille community skills hebdomadaire).

Distribution modèle & effort

Tier	Effort	# agents	Usage
opus	xhigh	20	Orchestration multi-agents, audits exhaustifs, génération specs/archi (bruce, blackemperor, sargeras, ed209, tony…)
sonnet	défaut (high)	70	Tâches focalisées, audits ciblés, automation (2b3, shuri, vision, verify, harper, minitel…)
haiku	low	3	Diagnostic read-only, output structuré (godspeed, gandalf, tools-checker)

Détails complets : framework/agents/_shared/model-policy.md. Pour la session Claude Code, rester sur /model opus (Bruce orchestre — la qualité dépend d'opus en continu, pas seulement en plan mode). Ne jamais setter CLAUDE_CODE_SUBAGENT_MODEL (écraserait tous les model: frontmatter).

Documentation

• Guide — Démarrage, workflows, FAQ
• ADR — Décisions d'architecture et leurs raisons
• Glossaire — Terminologie ulk
• Spec projet — État et roadmap du projet