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).
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
- Task Decomposition — Describe a complex task. Opus 4.6 analyzes your codebase and breaks it into a dependency graph of subtasks
- Parallel Agent Spawning — Independent subtasks run simultaneously via Claude Agent SDK. Dependent tasks wait.
- Real-time Coordination — File conflict detection prevents agents from stepping on each other. Budget enforcement stops runaway costs.
- Opus Quality Gate — After agents complete, Opus 4.6 reviews the combined output for correctness, consistency, and completeness
- Rich Terminal UI —
htop-style dashboard showing agent progress, tool usage, costs, and file conflicts in real-time - Session Replay — Every swarm execution is recorded. Replay any session to review what each agent did.
# 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 │ │
│ └──────────────────────────────────────────┘ │
└────────────────────────────────────────────────┘
| Feature | Description |
|---|---|
| Dependency-aware scheduling | Tasks only start when their dependencies complete |
| File conflict detection | Pessimistic file locking prevents agents from editing the same file simultaneously |
| Budget enforcement | Hard cost limit — cancels remaining tasks when budget is exceeded |
| Cost tracking | Real-time per-agent and total cost monitoring |
| Opus Quality Gate | Phase 2.5 — Opus 4.6 reviews all agent outputs for correctness and consistency |
| Smart model selection | Opus 4.6 for planning + quality review, Haiku for worker agents (3x cheaper) |
| Task retry | Failed tasks are automatically retried with configurable attempt limits |
| Demo mode | --demo flag shows animated TUI without API key (great for presentations) |
| Session recording | Every swarm execution recorded as JSONL events |
| Session replay | claude-swarm replay <id> to review what each agent did |
| YAML config | Declarative swarm topologies via swarm.yaml |
| Progress visualization | Live htop-style dashboard with Rich |
# 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 eventsCreate 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: reviewerClaude Swarm auto-detects swarm.yaml or .claude/swarm.yaml in your project.
Claude Swarm demonstrates strategic model selection with two critical Opus 4.6 touchpoints:
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.
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.
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.
- Python 3.11+ with
anyiofor 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
# 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
MIT — Affaan Mustafa
- 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
