Documentation

$ npm install -g swarm-engine
$ swarm install    # Set up Claude Code integration
$ swarm doctor     # Verify everything works

# Run a full research > implement > review cycle
$ swarm orchestrate "add rate limiting to the API"

# Preview the plan without executing
$ swarm orchestrate "add rate limiting" --dry-run

# Use a different pattern
$ swarm orchestrate "fix auth bypass" --pattern red-team

# Run a single agent
$ swarm run researcher "how does the auth middleware work?"

$ cd my-api
$ swarm init --yes

  Project: my-api
  Backend: claude
  Pattern: hybrid
  Budget: $5.00
  Created .swarm/

$ swarm plan "add rate limiting to POST /api/users"

  Execution Plan: hybrid
  Task: add rate limiting to POST /api/users

    Phase 1: research [parallel]
      researcher-code     -- researcher (claude-sonnet-4-6)
      researcher-context  -- researcher (claude-sonnet-4-6)

    Phase 2: implement [sequential]
      implementer         -- implementer (claude-opus-4-6)

    Phase 3: review [parallel]
      reviewer-security   -- security-reviewer (claude-opus-4-6)
      reviewer-convention -- reviewer (claude-sonnet-4-6)

    Est. cost:     $0.18
    Est. duration: 94s
    Est. tokens:   28,400
    Quality:       87%

$ swarm orchestrate "add rate limiting to POST /api/users"

  Swarm Engine - hybrid pattern

  Phase 1: research ━━━━━━━━━━━━━━━━━━━━ 100%  38s
    ✓ researcher-code       claude-sonnet-4-6   3.2K tokens
    ✓ researcher-context    claude-sonnet-4-6   1.8K tokens

  Phase 2: implement ━━━━━━━━━━━━━━━━━━━ 100%  1m 42s
    ✓ implementer           claude-opus-4-6     12.1K tokens

  Phase 3: review ━━━━━━━━━━━━━━━━━━━━━━ 100%  52s
    ✓ reviewer-security     claude-opus-4-6     4.8K tokens
    ✓ reviewer-convention   claude-sonnet-4-6   3.1K tokens

  ┌──────────────────────────────────────────────┐
  │  ✓ Orchestration complete                    │
  │  Pattern: hybrid (3 phases, 5 agents)        │
  │  Tokens: 24,900 | Cost: $0.21 | Time: 3m 12s│
  └──────────────────────────────────────────────┘

  Changes:
    src/middleware/rate-limit.ts    | 48 +++
    src/routes/users.ts            |  3 +-
    tests/middleware/rate-limit.test.ts | 62 +++

  Template name (or Enter to skip):

$ swarm memory search "rate limiting"

  Found 1 result(s):

  Rate limiting implementation outcome [outcome]
    Completed hybrid orchestration for rate limiting on POST /api/users...
    repo: my-api

$ cd my-project
$ swarm init

  Project: my-project
  Available backends:
    claude  ✓
    codex   ✓
    gemini  -

  Created:
    .swarm/config.yml
    .swarm/agents/
    .swarm/templates/

  ┌─────────────────────────────────────────────────────────────┐
  │  CLI / Slash Command / VS Code                              │
  │  swarm orchestrate "task"  |  /swarm "task"  |  @swarm task  │
  └────────────────────────────┬────────────────────────────────┘
                               │
  ┌────────────────────────────▼────────────────────────────────┐
  │  Planner                                                    │
  │  Pattern selection → Cost estimation → Plan search           │
  │  Heuristic injection → Adaptive replanning                   │
  └────────────────────────────┬────────────────────────────────┘
                               │
  ┌────────────────────────────▼────────────────────────────────┐
  │  DAG Executor                                               │
  │  Phase 1 (parallel) → Phase 2 (sequential) → Phase 3 ...    │
  │  Error retry · Cascade escalation · Agent dropout            │
  └──┬──────────┬──────────┬──────────┬────────────────────────┘
     │          │          │          │
  ┌──▼──┐  ┌──▼──┐  ┌──▼──┐  ┌──▼──┐    Backends
  │Claude│  │Codex│  │Gemin│  │AI SD│    (pluggable)
  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘
     │          │          │          │
  ┌──▼──────────▼──────────▼──────────▼────────────────────────┐
  │  Memory & Learning                                        │
  │  Traces → Heuristics → Knowledge compounding               │
  │  SQLite + FTS5  |  Obsidian vault (optional)                │
  └─────────────────────────────────────────────────────────────┘

Phase 1: research  [parallel]
    researcher-code     claude-sonnet-4-6  Explore codebase
    researcher-context  claude-sonnet-4-6  Check memory
           |
Phase 2: implement [parallel]
    implementer         claude-opus-4-6    Build the feature
           |
Phase 3: review    [parallel]
    reviewer-security   claude-opus-4-6    OWASP, injection
    reviewer-perf       claude-sonnet-4-6  Perf regression
    reviewer-convention claude-sonnet-4-6  Code style

# TDD then red-team the result
$ swarm orchestrate "add payment processing" --pattern "tdd | red-team"

# Research first, then TDD
$ swarm orchestrate "migrate to new ORM" --pattern "research | tdd"

$ swarm agents list
$ swarm agents list --json  # Machine-readable

---
name: security-reviewer
model: claude-opus-4-6       # The actual model this agent runs on
backend: claude
---

---
name: codex-reviewer
model: o3                    # OpenAI model
backend: codex
---

---
name: gemini-researcher
model: gemini-2.5-pro        # Google model
backend: gemini
---

# Force all agents to use Opus
$ swarm orchestrate "add auth" --model claude-opus-4-6

# Force all agents to use Haiku (cheapest)
$ swarm orchestrate "add docs" --model claude-haiku-4-5-20251001

# Single agent with a specific model
$ swarm run researcher "explore codebase" -m claude-opus-4-6

---
name: my-agent
model: o3
backend: codex
tier: expensive   # Optional. Auto-inferred from model name if omitted.
---

# Claude Code (required for default backend)
$ npm install -g @anthropic-ai/claude-code

# OpenAI Codex CLI
$ npm install -g @openai/codex
$ export OPENAI_API_KEY=sk-...

# Google Gemini CLI
$ npm install -g @google/gemini-cli
$ export GEMINI_API_KEY=AIza...

# Vercel AI SDK (for programmatic access to 20+ providers)
$ npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

# Check which backends are available
$ swarm doctor

# Run entire orchestration on Codex
$ swarm orchestrate "add rate limiting" --backend codex

# Run entire orchestration on Gemini
$ swarm orchestrate "add logging" --backend gemini

# Run a single agent on Codex
$ swarm run researcher "explore the auth module" --backend codex

---
name: codex-reviewer
description: "Code reviewer powered by OpenAI"
model: o3
backend: codex
tools: Read, Glob, Grep, Bash
---

You are a code reviewer. Review for correctness, edge cases, and security.

---
name: gemini-researcher
description: "Research agent powered by Google Gemini"
model: gemini-2.5-pro
backend: gemini
tools: Read, Glob, Grep
---

You are a research agent. Thoroughly investigate the codebase and report findings.

$ swarm orchestrate "add payment processing"

  Pattern: hybrid
  Phase 1: research
    gemini-researcher     gemini   gemini-2.5-pro
  Phase 2: implement
    implementer           claude   claude-sonnet-4-6
  Phase 3: review
    codex-reviewer        codex    o3
    security-reviewer     claude   claude-opus-4-6

---
name: llama-researcher
model: groq/llama-3.3-70b-versatile
backend: vercel-ai
---

# Preview cost before running (free, instant)
$ swarm plan "add auth"

# Set a hard budget cap
$ swarm orchestrate "add auth" --budget 1

# Test with mock execution (free, no API calls)
$ swarm orchestrate "add auth" --mock

# Force cheaper models
$ swarm orchestrate "add auth" --model claude-sonnet-4-6

swarm orchestrate <task> [options]

# Full orchestration with live TUI dashboard
$ swarm orchestrate "add WebSocket support" --tui

# Test-driven with $2 budget cap
$ swarm orchestrate "add input validation" --pattern tdd --budget 2

# Red-team with agents in visible tmux panes
$ swarm orchestrate "harden the auth flow" --pattern red-team --panes

# Compose patterns: TDD then adversarial review
$ swarm orchestrate "add payment API" --pattern "tdd | red-team"

# Dry run to preview cost and plan
$ swarm orchestrate "refactor database layer" --dry-run

swarm run <agent> <task> [options]

# Research a codebase question
$ swarm run researcher "how does the caching layer work?"

# Run the security reviewer on current changes
$ swarm run security-reviewer "review recent changes for vulnerabilities" -m claude-opus-4-6

# Debug a specific issue
$ swarm run debugger "why does the login endpoint return 500?"

swarm plan <task> [options]

# Options: -p/--pattern, --budget, --json

$ swarm plan "add rate limiting" --pattern hybrid

Execution Plan: hybrid
Task: add rate limiting
Budget: $5

  Phase 1: research [parallel]
    researcher-code     — researcher (claude-sonnet-4-6)
    researcher-context  — researcher (claude-sonnet-4-6)

  Phase 2: implement [sequential]
    implementer         — implementer (claude-opus-4-6)

  Phase 3: review [parallel]
    reviewer-security   — security-reviewer (claude-opus-4-6)
    reviewer-perf       — performance-reviewer (claude-sonnet-4-6)
    reviewer-convention — reviewer (claude-sonnet-4-6)

  Est. cost:     $0.1842
  Est. duration: 94s
  Est. tokens:   28,400
  Quality:       87%

  Optimizations applied:
    → Downgraded reviewer-convention from expensive to mid tier (low complexity)
    → Injected 2 heuristics from similar past runs

# List available templates
$ swarm template list

# Run a template interactively (prompts for parameters)
$ swarm template run add-feature -i

# Run with explicit parameters
$ swarm template run bug-fix --param bug_description="login fails on mobile"

# Create template from last successful orchestration
$ swarm template create my-workflow --from-last

# Create a blank template scaffold
$ swarm template create my-workflow

# Search the knowledge base
$ swarm memory search "authentication"
$ swarm memory search "rate limiting" --type decision --repo my-api

# Store a new entry
$ echo "Use Redis for rate limiting, not in-memory" | swarm memory store decision "Rate limit backend choice" --repo my-api

# List recent entries
$ swarm memory list --type outcome --limit 5

# View statistics
$ swarm memory stats

# List conversion targets
$ swarm convert --list

# Convert agents for a specific tool
$ swarm convert --to copilot   # GitHub Copilot instructions
$ swarm convert --to cursor    # Cursor rules
$ swarm convert --to codex     # OpenAI Codex agents
$ swarm convert --to gemini    # Gemini CLI
$ swarm convert --to opencode  # OpenCode
$ swarm convert --to windsurf  # Windsurf

# Convert only agent definitions (skip commands)
$ swarm convert --to cursor --agents-only

# Custom output directory
$ swarm convert --to copilot --output ./my-copilot-config

# List all registered agents
$ swarm agents list
$ swarm agents list --json

# Show full agent definition (frontmatter + prompt)
$ swarm agents show researcher

# Create a new agent scaffold
$ swarm agents new my-reviewer
$ swarm agents new my-reviewer --dir ~/.swarm/agents

# Install agents from a GitHub repo
$ swarm agents install github:myorg/my-agents

# Test an agent with mock execution
$ swarm agents test researcher "explore the auth module"

# Search GitHub for agent packs
$ swarm agents search security

$ swarm init          # Interactive setup
$ swarm init --yes    # Accept defaults, skip prompts

$ swarm verify                   # Run all detected checks
$ swarm verify --cwd ./packages/api  # Verify a subdirectory

$ swarm status              # Full status overview
$ swarm status --backends    # Available execution backends
$ swarm status --patterns    # Orchestration patterns with phase breakdown

# Extract solutions from recent traces
$ swarm compound extract --count 10

# Search compounded knowledge
$ swarm compound search "rate limiting"

# List by category
$ swarm compound list --category security

# Statistics and stale entries
$ swarm compound stats
$ swarm compound stale

$ swarm learn      # List lessons with completion status
$ swarm learn 1    # Lesson 1: Your First Plan
$ swarm learn 2    # Lesson 2: Run a Mock Orchestration
$ swarm learn 3    # Lesson 3: Explore Your Agents
$ swarm learn 4    # Lesson 4: Templates
$ swarm learn 5    # Lesson 5: Health Check

$ swarm doctor

Swarm Doctor

  ✓ Node.js 22.1.0
  ✓ jq
  ✓ Claude Code
  ✓ swarm on PATH
  ✓ CLAUDE.md configured
  ✓ ~/.swarm/ exists
  ✓ Claude Code integration installed

  Optional backends:
  ✓ Codex CLI
  - Gemini not installed (npm i -g @google/gemini-cli)

  All checks passed.

name: add-feature
description: "Add a new feature with tests and documentation"
parameters:
  feature:
    type: string
    description: "Feature description"
    required: true
  test_framework:
    type: string
    description: "Test framework to use"
    default: "jest"
pattern: hybrid
agents:
  researcher:
    extra_rules:
      - "Understand how similar features are implemented"
      - "Identify affected modules and side effects"
  implementer:
    extra_rules:
      - "Follow existing code patterns"
      - "Write tests using ${test_framework}"
  reviewer:
    extra_rules:
      - "Check for edge cases and error handling"
      - "Verify test coverage"
success_criteria:
  - "Feature works as described"
  - "Tests pass with good coverage"
  - "No regressions"
tags: [feature, implementation]

---
name: api-reviewer
description: "Reviews API endpoints for consistency and best practices"
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
permissionProfile: safe
maxTurns: 20
---

You are an API Review Agent. Check every endpoint for:

1. Consistent naming (REST conventions)
2. Proper HTTP status codes
3. Input validation on all parameters
4. Rate limiting configuration
5. Authentication requirements
6. Response schema consistency

## Output Format
```
## API Review
- Endpoint: [path]
  - Status: [pass/fail]
  - Issues: [list]
```

# Option 1: Use the default location
$ mkdir -p ~/swarm-vault

# Option 2: Use a custom location via environment variable
$ export SWARM_VAULT=/path/to/your/obsidian/vault

# Then open the vault directory in Obsidian

~/swarm-vault/
  decisions/
    2026-04-05-rate-limit-backend-choice.md
    2026-04-03-auth-session-storage.md
  patterns/
    2026-04-04-error-handling-pattern.md
  learnings/
    2026-04-05-q1-refactor-results.md
  repos/
    my-api/
      rate-limiting.md
      auth-middleware.md

Run 1: "add auth" → research took 60s, implement took 120s
Run 2: "add rate limiting" → engine injects heuristic:
         "Similar tasks average 90s research. Allocate accordingly."
Run 3: "add caching" → engine now has 2 data points, refines estimate

$ swarm compound extract   # Extract knowledge from recent traces
$ swarm compound search "auth"  # Search compounded knowledge
$ swarm compound stats    # Show category breakdown
$ swarm compound stale    # Find outdated entries

project: my-api
default_pattern: hybrid
default_backend: claude
cost_budget: 5.00
agents:
  reviewer:
    extra_rules:
      - "Check for PII in log statements"
      - "Verify all endpoints have rate limiting"
context_files:
  - docs/architecture.md
  - docs/api-spec.md

$ swarm install

  Installed:
    ~/.claude/agents/     26 agent definitions
    ~/.claude/commands/    9 slash commands
    ~/.claude/hooks/       event hooks
    ~/.claude/CLAUDE.md    swarm snippet injected

# Full orchestration (hybrid pattern by default)
/swarm "add rate limiting to the API"

# Pattern-specific commands
/research "how does the auth system work?"
/tdd "add input validation to user endpoints"
/red-team "harden the payment flow"
/review-cycle "refactor the database layer"

# Utility commands
/diff-review                # Review current git diff
/fix-pr "fix CI failures"   # Fix a failing pull request

# Use the @swarm chat participant
@swarm add rate limiting to the API

# Or use the command palette
Cmd+Shift+P → Swarm: Orchestrate