AI Swarm Orchestration

Multi-agent AI coding swarm orchestration. Plan parallel tasks, spawn Claude/Codex/Gemini agents in tmux sessions with git worktrees, auto-review, auto-integrate branches, notify via Telegram. Use when you need to break a project into parallel coding tasks and orchestrate multiple AI agents to build, review, and merge them.

Orchestrate parallel AI coding agents with automated review, integration, and notifications.

Setup

Prerequisites

• tmux — agent sessions run here
• git — worktrees for parallel branches
• claude CLI (Claude Code) — primary agent
• Telegram bot token + chat ID (optional, for notifications)

Install scripts

Copy scripts/ to your swarm directory (e.g., ~/workspace/swarm/). Make executable:

bash

chmod +x ~/workspace/swarm/*.sh

Initialize state files

bash

mkdir -p ~/workspace/swarm/{logs,endorsements}
echo '[]' > ~/workspace/swarm/active-tasks.json
echo '' > ~/workspace/swarm/pending-notifications.txt

Duty table

Copy references/duty-table-template.json to ~/workspace/swarm/duty-table.json. Configure model assignments.

Core Workflow

Phase 1: PLAN (present to human, STOP, wait for approval)

⛔ CRITICAL GATE: Present the plan table to the human. Then STOP. Do NOT write prompts or spawn agents until the human explicitly approves.

The plan message and the spawn action must be in DIFFERENT turns. Never combine them.

text

🐝 Swarm Plan: [batch description]

| # | Task ID | Description | Agent | Model |
|---|---------|-------------|-------|-------|
| 1 | fix-xyz | Fix the freeze bug | claude | sonnet |
| 2 | add-feat | Add feature X | claude | sonnet |

Dependencies: None (all parallel)
Estimated time: ~15-20 min

Proceed? 👍/👎

Wait for human reply. Only after "yes"/"go"/👍 → proceed to Phase 2.

Phase 2: BUILD (write prompts, spawn agents)

Write task prompts to /tmp/prompt-<task-id>.md, create batch JSON, then spawn:

bash

cat > /tmp/batch-tasks.json << 'EOF'
[
  {"id": "task-1", "description": "/tmp/prompt-task1.md", "agent": "claude", "model": "claude-sonnet-4-6"},
  {"id": "task-2", "description": "/tmp/prompt-task2.md", "agent": "claude", "model": "claude-sonnet-4-6"}
]
EOF

cd ~/workspace/swarm
bash spawn-batch.sh "/path/to/project" "batch-id" "Batch description" /tmp/batch-tasks.json

spawn-batch.sh handles everything automatically:

• Creates git worktrees + feature branches
• Launches agents in tmux sessions
• Starts per-agent completion watchers (auto-review + Telegram notification)
• Starts integration watcher (auto-merge when all done)

For single tasks: bash spawn-agent.sh "/path/to/project" "task-id" "/tmp/prompt.md" "claude" "claude-sonnet-4-6"

Phase 3: SHIP (automatic)

The scripts handle this automatically:

1. notify-on-complete.sh detects each agent finishing → spawns reviewer → sends Telegram
2. integration-watcher.sh detects ALL agents done → spawns Opus integration agent → merges branches → resolves conflicts → verifies builds → sends Telegram

Prompt Template

Write clear, self-contained prompts for each agent. Include:

• Project path and stack
• Specific files to modify
• What to do (detailed steps)
• Verification commands (tsc --noEmit, npm run build, etc.)

Do NOT include openclaw system event in prompts — notify-on-complete.sh handles notifications automatically.

Monitoring

bash

tmux ls                              # List active agent sessions
bash check-agents.sh                 # Health check all agents
bash pulse-check.sh                  # Detect stuck agents (auto-kills)
cat pending-notifications.txt        # Check pending notifications

Script Reference

Script	Purpose
spawn-batch.sh	Spawn N agents + auto-integration watcher
spawn-agent.sh	Spawn single agent with completion watcher
integration-watcher.sh	Poll agents, auto-merge when all done
start-integration.sh	Manual integration watcher start
notify-on-complete.sh	Per-agent watcher: detect done → review → notify
pulse-check.sh	Detect and kill stuck agents
check-agents.sh	Quick status check
endorse-task.sh	Create endorsement file for a task
esr-log.sh	Update project ESR docs
eor-log.sh	Write agent end-of-run log
fallback-swap.sh	Model selection with fallback
assess-models.sh	Weekly model benchmark
deploy-notify.sh	CI/CD notification

Hard Rules

ALWAYS

• Present plan → STOP → wait for human approval → THEN spawn (separate turns!)
• Use spawn-batch.sh for 2+ tasks, spawn-agent.sh for single tasks
• Let scripts handle tmux, notifications, review, integration — don't bypass

NEVER

• Spawn agents without human endorsement
• Present plan and spawn in the same message/turn
• Write prompts before receiving endorsement
• Use bare claude --print or background exec (bypasses entire pipeline)
• Spawn agents in the orchestrator's workspace directory

Heartbeat Checks

Read references/HEARTBEAT.md for periodic checks:

1. Read pending-notifications.txt → send to human → clear
2. Run pulse-check.sh for stuck agents
3. Check tmux ls for completed agents
4. Report brief status if agents are running

Further Reading

• references/ROLE.md — Full role definition with lessons learned
• references/TOOLS.md — Detailed script usage and prompt patterns