- name
- claude-swarm
- description
- Claude-native multi-agent swarm orchestration for parallel coding. Use when spawning multiple Claude Code agents to work in parallel on a project with git worktrees, tmux tracking, endorsement gates, auto-review chains, integration merging, and webhook notifications. All agents are Claude (opus for architect/integrator, sonnet for builders/reviewers). Triggers on parallel coding, multi-agent work, swarm orchestration, batch spawning, or when 2+ coding tasks need coordinated execution.
Claude Swarm — Multi-Agent Orchestration
Parallel Claude Code agents: plan → endorse → spawn → monitor → review → integrate → ship.
Quick Start
# 1. Write task prompts
cat > /tmp/prompt-task1.md << 'EOF'
Implement feature X...
EOF
# 2. Create tasks JSON
cat > /tmp/tasks.json << 'EOF'
[
{"id": "feat-x", "description": "/tmp/prompt-task1.md", "role": "builder"},
{"id": "feat-y", "description": "/tmp/prompt-task2.md", "role": "builder"}
]
EOF
# 3. Spawn batch (auto-endorses + auto-integration)
bash scripts/spawn-batch.sh "/path/to/project" "batch-1" "Description" /tmp/tasks.jsonRoles & Models
| Role | Model | Effort | Use |
|---|---|---|---|
| architect | opus | high | Design, planning, complex decisions |
| builder | sonnet | high | Feature implementation (parallel) |
| reviewer | sonnet | medium | Auto-review on completion |
| integrator | opus | high | Cross-branch merge + conflict resolution |
Configure in config/duty-table.json.
Scripts
| Script | Purpose |
|---|---|
spawn-batch.sh | Spawn N parallel agents + integration watcher |
spawn-agent.sh | Spawn single agent in worktree + tmux |
endorse-task.sh | Endorse task (required before spawn) |
check-agents.sh | Show status of all running agents |
cleanup.sh | Remove worktrees, branches, tmux sessions |
notify.sh | Send webhook/Telegram notification |
notify-on-complete.sh | Auto-watcher: notify + review on completion |
integration-watcher.sh | Auto: merge all branches when batch completes |
Workflow Detail
1. Planning (human + architect)
Break work into parallel tasks. Each task needs: ID, prompt, role.
2. Endorsement Gate
Every task requires endorsement before spawning — safety gate to prevent runaway agents.
spawn-batch.shauto-endorses all tasks in batch- Manual:
bash scripts/endorse-task.sh <task-id> - 30-second cooldown between endorsement and spawn
3. Spawning
Each agent runs in:
- Isolated git worktree (
<project>-worktrees/<task-id>/) - tmux session (
claude-<task-id>) - Non-interactive mode (
claude --print --permission-mode bypassPermissions) - Auto-retry with model fallback (opus → sonnet → haiku) on rate limits
4. Auto-Review
When an agent completes, notify-on-complete.sh:
- Detects completion (polls tmux every 60s)
- Sends notification
- Spawns a reviewer (sonnet) that checks the diff
- If issues found: fixes and commits (up to 3 rounds)
- Pushes final state
5. Integration
When all agents in a batch complete, integration-watcher.sh:
- Collects all branches
- Merges sequentially into main
- Uses opus to resolve any conflicts
- Runs integration review (opus, up to 3 rounds)
- Pushes to main (if auto-merge enabled)
Setup
- Copy this skill's
scripts/andconfig/to your workspace - Copy
config/swarm.conf.example→config/swarm.confand configure - Ensure installed:
bash 4+,tmux,git,gh,jq,claude(Claude Code CLI)
Notifications
Set SWARM_NOTIFY in swarm.conf:
webhook— POST toSWARM_WEBHOOK_URL(Slack/Discord/custom)telegram— Send viaSWARM_TELEGRAM_BOT_TOKEN+SWARM_TELEGRAM_CHAT_IDnone— Log only (default)
Hard Rules
- Always endorse before spawning — no exceptions
- Use spawn-batch.sh for 2+ tasks — starts integration watcher
- Never run bare
claude --printin background — use spawn-agent.sh - Let the watcher handle reviews — don't add review logic to prompts