Getting Started with ulk

ulk is a monorepo of 90 specialized AI agents for Claude Code. Each agent is a markdown file with a YAML frontmatter that defines its role, model, tools, and invocation protocol. Once installed, agents appear as slash commands in any Claude Code session.

Prerequisites

Requirement	Details
Claude Code	Latest version — the agents run inside Claude Code sessions
macOS or Linux	Windows is not supported
Git	Required for cloning the repo
Node.js	18+ (used by the Go CLI wrapper and some optional tools)
`ANTHROPIC_API_KEY`	Required only for Managed Agents (cloud sessions without a local machine)

The agents themselves have no runtime dependencies — they are dependency-free markdown files. Optional CLIs (gh, vercel, rtk, etc.) extend specific agents but are not required to start.

Installation

# 1. Clone the repository
git clone https://github.com/izo/ulk
cd ulk

# 2. Run the installer
./install.sh

# 3. Verify the installation
./framework/tools/check-tools.sh

install.sh is a wrapper around the ulk install Go CLI. It compiles the CLI, then installs agents and skills into ~/.claude/. No system-level packages are written outside that directory.

To upgrade an existing installation:

git pull && ./install.sh

The script reinstalls cleanly — no manual migration needed.

Common install flags

./install.sh --dry-run              # Simulate without writing files
./install.sh --with-vps             # Include VPS management agents (17 agents)
./install.sh --with-teams           # Include Agent Teams (experimental)
./install.sh --with-context-mode    # Token optimization: store verbose outputs in SQLite
./install.sh --with-caveman-output-skill  # Token optimization: terse output mode (-79%)
./install.sh --with-memory-loop     # Persistent memory between sessions
./install.sh --with-auto-dream      # REM-style memory consolidation (runs in background)

Full flag reference: .claude/rules/install-reference.md

First Command

Open any project in Claude Code and type:

/ulk:bruce go

Bruce (agent 25) is the primary orchestrator. It detects the project state via Godspeed (agent 00), then routes to the appropriate agents. On an empty project it generates a spec and a Kanban backlog. On an existing project it picks up the next task from docs/todo.md.

You do not need to know the other 89 agents to get started. Bruce selects and delegates automatically.

Verify the Installation

/ulk:godspeed

Godspeed runs a project diagnostic in seconds and outputs:

Stack detected (Next.js, Astro, Swift, Go, etc.)
Project state (greenfield / in progress / stalled / production)
Available CLIs (gh, vercel, rtk, etc.)
Key files present or missing
Recommended next action

If agents are not found, check that ~/.claude/commands/ contains the expected files:

ls ~/.claude/commands/ | grep ulk

The 3 Essential Workflows

Workflow 1 — New project

/ulk:bruce go

Bruce calls Godspeed → project diagnostic
Shuri generates docs/spec.md (narrative spec) + docs/todo.md (Kanban backlog)
Task Runner picks the first task and begins

Result: structured spec + prioritized backlog from a single command.

Workflow 2 — Daily development session

# Morning: surface context from previous sessions
/ulk:godspeed

# Work: take and execute the next task
/ulk:bruce next

# End of session: lint → tests → commit → memory capture
/ulk:2b3

After 2b3, run /clear before starting the next unrelated task.

Workflow 3 — Audit an existing project

# Full 10-axis audit
/ulk:sargeras

# Security audit (OWASP top 10)
/ulk:ed209

# Cost audit (Vercel, GitHub, Neon)
/ulk:killbill

# All four audits in parallel with a consolidated report
/ulk:blackemperor

Troubleshooting

Agent not found

Symptom: /ulk:bruce returns “command not found” or has no effect.

Checks:

# Verify commands are installed
ls ~/.claude/commands/ | grep ulk | head -5

# Re-run the installer
cd /path/to/ulk && ./install.sh

# Check the installer output for errors
./install.sh 2>&1 | grep -i error

Install failed

Symptom: ./install.sh exits with an error.

Checks:

# Check Go is available (needed to compile the ulk CLI)
go version

# If Go is missing, the installer will fall back to the legacy shell installer
# Check if the Go CLI binary was compiled
ls framework/cli/ulk 2>/dev/null || echo "CLI not compiled"

# Run in dry-run mode to see what would be written
./install.sh --dry-run

Audit-only run (no writes to ~/.claude)

ulk install --audit-only
# Report written to .ulk-reports/audit-<timestamp>.json

Stack not detected correctly

Run Godspeed and share the output:

/ulk:godspeed

If the detected stack is wrong, check CLAUDE.md at the project root — Bruce reads it at startup to understand the project context.

What Gets Installed

After ./install.sh, the following are written to ~/.claude/:

Path	Contents
`~/.claude/commands/`	Slash commands for each agent (`ulk:bruce`, `ulk:sargeras`, etc.)
`~/.claude/skills/`	Bundled skills (Figma, Swift, Obsidian, etc.)
`~/.claude/hooks/`	Optional hooks (memory loop, auto-dream, accountability) if flags were passed
`~/.claude/agent-memory-local/`	Persistent memory for the 9 memory-enabled agents

Nothing is written outside ~/.claude/ and the ulk repo directory.

The 4-Layer System

Understanding how ulk is structured helps you know when to go beyond Bruce.

Layer 1 — The orchestrator

Bruce (/ulk:bruce) is the only agent you need to know. It understands 9 natural commands and handles routing internally. Bruce has persistent memory between sessions — it remembers the project, stack, and preferences.

Layer 2 — Diagnostics

Godspeed (agent 00) scans the project and caches the result for 30 minutes. It is called by Bruce at startup and can be called directly for a quick status. Gandalf (agent 34) monitors context consumption and alerts above 40%.

Layer 3 — Work agents

Organized by function:

Documentation: Shuri (spec + todo + sync), Strange (reverse doc), Lovecraft (cross-session memory)
Execution: Task Runner (tasks from todo.md), Robocop (error fixing)
Quality: Vision (8 dimensions), Perf Auditor, A11y Auditor, SEO Auditor, Sargeras (10 axes)
End of session: 2b3 (lint → tests → simplification → commit)

Layer 4 — Specialists

Activated based on project context:

Frontend (10 agents): Stark, Brique, Visual-Auditor, frontend-qa, etc.
Stack analyzers (6): analyze-next, analyze-nuxt, analyze-astro, analyze-spip, analyze-swiftui, benjamin
Deploy (6): Vercel, Netlify, Cloudflare, AWS, Docker, Fly
Tests (2): test-unit, test-e2e
VPS (17): full VPS lifecycle management suite
Mobile (3): Happy (routing), Steve (iOS/macOS), Fluke (Android)
Sync (2): Bifrost (Notion), Brigitte (Linear)

FAQ

Do I need to know all 90 agents? No. Bruce selects and delegates automatically. /ulk:bruce go covers 80% of use cases. Learn the other agents gradually as Bruce routes to them.

Does ulk work on any project type? Yes. Agents detect the stack automatically: Next.js, Nuxt, Astro, SPIP, Swift, SwiftUI, Python, Go, Rust, Laravel, WordPress, and more.

How do I update ulk?

git pull && ./install.sh

The installer reinstalls cleanly. No manual migration.

Can I use ulk on a team? Yes. Each team member installs ulk on their machine. The project’s CLAUDE.md (committed to git) is the shared source of truth for agent behavior. All team members use the same slash commands (/ulk:bruce, /ulk:2b3, etc.), which creates a common vocabulary.

What is the performance overhead of running multiple agents? Agents that are not invoked consume no tokens. Each agent starts fresh. The only overhead is the CONTEXTE PROJET: block that Bruce passes to sub-agents (saving 3K–10K tokens compared to having each agent scan the project independently).

Can I run sessions without being at my computer? Yes — via Managed Agents (cloud sessions). Install with ./install.sh --with-managed-agents and configure cron or webhook triggers. Five agents are available in cloud mode: sargeras, ed209, lovecraft, 2b3, and ci-guard.

What model does ulk use? By default, 64 agents run on Sonnet, 20 on Opus (orchestrators and deep auditors), and 3 on Haiku (lightweight scanners). For interactive sessions, running Claude Code with /model opus is recommended for best orchestration quality.

Can I create my own agents? Yes. Create a markdown file in framework/agents/<category>/NN-<name>.md with the required YAML frontmatter, then run ./install.sh. See customization.md for a complete example and the full frontmatter reference.