affaan-m/claude-swarm

You: "Refactor auth module from Express middleware to Next.js API routes"

Claude Swarm:
  Phase 1:   Opus 4.6 decomposes task into dependency graph
  Phase 2:   Parallel agents execute subtasks with live dashboard
  Phase 2.5: Opus 4.6 Quality Gate reviews all agent outputs
  Phase 3:   Results summary with costs and session replay

# See it in action instantly (no API key needed!)
pip install claude-swarm
claude-swarm --demo

# Or install from source
git clone https://github.com/affaan-m/claude-swarm
cd claude-swarm
pip install -e .

# Set your API key for real usage
export ANTHROPIC_API_KEY="sk-ant-..."

# Run a swarm
claude-swarm "Refactor auth module from Express middleware to Next.js API routes"

# Dry run (shows plan without executing)
claude-swarm --dry-run "Add user authentication with JWT"

# Custom budget, agents, and retries
claude-swarm --budget 3.0 --max-agents 6 --retry 2 "Build a REST API for user management"

# Disable quality gate for faster execution
claude-swarm --no-quality-gate "Quick fix: update README"

┌───────────────────────────────────────────────┐
│              Claude Swarm CLI                  │
│                                                │
│  Phase 1: Decompose                            │
│  ┌─────────────────────────────────────────┐   │
│  │  Opus 4.6 Task Decomposer              │   │
│  │  "Add auth" -> [create routes,          │   │
│  │   add middleware, write tests, review]   │   │
│  └──────────────┬──────────────────────────┘   │
│                 │ dependency graph              │
│  Phase 2: Execute                              │
│  ┌──────────────▼──────────────────────────┐   │
│  │       Swarm Orchestrator                │   │
│  │                                         │   │
│  │  Wave 1: ┌────────┐ ┌────────┐         │   │
│  │          │ Agent 1 │ │ Agent 2 │  (parallel)│
│  │          │ coder   │ │ coder   │         │  │
│  │          └────┬────┘ └────┬────┘         │  │
│  │  Wave 2:      └─────┬─────┘              │  │
│  │               ┌─────▼─────┐              │  │
│  │               │  Agent 3  │  (depends)   │  │
│  │               │  tester   │              │  │
│  │               └─────┬─────┘              │  │
│  │  Wave 3:      ┌─────▼─────┐              │  │
│  │               │  Agent 4  │  (depends)   │  │
│  │               │  reviewer │              │  │
│  │               └───────────┘              │  │
│  │                                          │  │
│  │  File Locks: {auth.ts -> Agent 1}       │  │
│  │  Budget: $0.23 / $5.00                  │  │
│  │  Retries: task-2 (attempt 2/3)          │  │
│  └──────────────────────────────────────────┘  │
│                                                │
│  Phase 2.5: Quality Gate                       │
│  ┌──────────────────────────────────────────┐  │
│  │  Opus 4.6 reviews combined agent output  │  │
│  │  Score: 8/10 | Verdict: PASS            │  │
│  └──────────────────────────────────────────┘  │
│                                                │
│  Phase 3: Results                              │
│  ┌──────────────────────────────────────────┐  │
│  │  4/4 tasks completed | $0.45 | 32s      │  │
│  │  Session: swarm-a1b2c3d4                 │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

# Main command
claude-swarm [OPTIONS] TASK

Options:
  -d, --cwd TEXT            Working directory (default: .)
  -n, --max-agents INTEGER  Max concurrent agents (default: 4)
  -m, --model TEXT          Decomposition model (default: opus)
  -b, --budget FLOAT        Max budget in USD (default: 5.0)
  -r, --retry INTEGER       Max retries for failed tasks (default: 1)
  -c, --config PATH         Path to swarm.yaml
  --demo                    Run demo simulation (no API key needed)
  --dry-run                 Show plan without executing
  --quality-gate/--no-quality-gate  Enable/disable Opus quality review (default: on)
  --no-ui                   Disable rich terminal UI
  -v, --version             Show version

# Subcommands
claude-swarm sessions              # List past sessions
claude-swarm replay <session-id>   # Replay a session's events

swarm:
  name: full-stack-review
  max_concurrent: 4
  budget_usd: 5.0
  model: opus

agents:
  security-reviewer:
    description: Reviews code for OWASP vulnerabilities
    model: opus
    tools: [Read, Grep, Glob]
    prompt: |
      Analyze the code for SQL injection, XSS, CSRF...

  tester:
    description: Writes and runs tests
    model: haiku
    tools: [Read, Write, Edit, Bash]
    prompt: |
      Write comprehensive tests. Ensure 80% coverage...

connections:
  - from: coder
    to: security-reviewer
  - from: coder
    to: tester
  - from: [security-reviewer, tester]
    to: reviewer

# Clone and install
git clone https://github.com/affaan-m/claude-swarm
cd claude-swarm
pip install -e ".[dev]"

# Run tests (44 passing)
pytest tests/ -v

# Lint
ruff check src/ tests/

src/claude_swarm/
  cli.py           CLI entry point (Click group + subcommands)
  types.py         Core dataclasses (SwarmTask, SwarmPlan, etc.)
  decomposer.py    Opus 4.6 task decomposition
  orchestrator.py  Parallel execution with file locks, budget, retries
  quality_gate.py  Opus 4.6 quality review of agent outputs
  demo.py          Demo simulation with animated TUI
  config.py        YAML swarm topology configuration
  session.py       JSONL event recording and replay
  ui.py            Rich terminal dashboard