affaan-m/claude-swarm

Claude Swarm

Multi-agent orchestration for Claude Code — decompose complex tasks into parallel subtasks, coordinate agents in real-time, and visualize everything in a rich terminal UI.

Built with the Claude Agent SDK for the Claude Code Hackathon (Feb 10-16, 2026).

How It Works

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

1. Task Decomposition — Describe a complex task. Opus 4.6 analyzes your codebase and breaks it into a dependency graph of subtasks
2. Parallel Agent Spawning — Independent subtasks run simultaneously via Claude Agent SDK. Dependent tasks wait.
3. Real-time Coordination — File conflict detection prevents agents from stepping on each other. Budget enforcement stops runaway costs.
4. Opus Quality Gate — After agents complete, Opus 4.6 reviews the combined output for correctness, consistency, and completeness
5. Rich Terminal UI — htop-style dashboard showing agent progress, tool usage, costs, and file conflicts in real-time
6. Session Replay — Every swarm execution is recorded. Replay any session to review what each agent did.

Quick Start

# 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"

Architecture

┌───────────────────────────────────────────────┐
│              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                 │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

Features

CLI Reference

# 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

YAML Configuration

Create swarm.yaml in your project root to define custom agent types:

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

Claude Swarm auto-detects swarm.yaml or .claude/swarm.yaml in your project.

How Opus 4.6 Is Used

Claude Swarm demonstrates strategic model selection with two critical Opus 4.6 touchpoints:

Phase 1: Task Decomposition (Planning)

Opus 4.6 handles the hardest reasoning task — analyzing your codebase, understanding the architecture, identifying dependencies between subtasks, and producing a parallelizable execution plan. This requires deep understanding of code relationships and optimal task splitting.

Phase 2: Worker Execution

Haiku handles the parallelizable work — each agent follows focused instructions from the plan. Using Haiku here is 3x cheaper while maintaining 90% of Sonnet's capability for focused tasks.

Phase 2.5: Quality Gate (Review)

After all agents complete, Opus 4.6 reviews the combined output. It checks for integration issues between agents' work, missed edge cases, security concerns, and whether the original task was fully addressed. This catches problems that individual agents can't see.

This mirrors real engineering team structure: a senior architect designs the plan, junior engineers execute in parallel, and the senior reviews the combined result.

Tech Stack

• Python 3.11+ with anyio for structured async concurrency
• claude-agent-sdk (v0.1.35+) for Claude Code subprocess control
• Rich for terminal UI (Live dashboard with panels and tables)
• Click for CLI framework
• Pydantic for data validation
• NetworkX for dependency graph topological sorting

Development

# 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/

Project Structure

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

License

MIT — Affaan Mustafa

Acknowledgments

• Claude Agent SDK for the subprocess control layer
• Everything Claude Code for agent patterns and inspiration
• Built for the Cerebral Valley x Anthropic Claude Code Hackathon