Menu
Spawns parallel pi agents to work on multiple GitHub issues or PRs using git worktrees. Use when asked to process multiple items in parallel, perform bulk reviews/fixes, or orchestrate entire projects.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | pi-swarm |
| description | Spawns parallel pi agents to work on multiple GitHub issues or PRs using git worktrees. Use when asked to process multiple items in parallel, perform bulk reviews/fixes, or orchestrate entire projects. |
Orchestrates parallel headless pi agents across isolated git worktrees to process GitHub issues, PRs, epics, and entire projects.
Commander (Project/Milestone level)
โ
โโโบ Captain (Epic level)
โ โโโบ swarm.sh (Issue wave 1)
โ โโโบ pr-swarm.sh (Review PRs)
โ โโโบ swarm.sh (Issue wave 2)
โ โโโบ ...
โ
โโโบ Captain (Another Epic)
โโโบ ...
Process multiple issues in parallel:
scripts/swarm.sh 48 50 52
Review and fix multiple PRs in parallel:
scripts/pr-swarm.sh 101 105
Orchestrate an entire epic with dependency-aware wave execution:
scripts/captain.sh --epic 151
Orchestrate multiple epics or generate a project from scratch:
# From a milestone issue
scripts/commander.sh --milestone 200
# From specific epics
scripts/commander.sh --epics 151 160 175
# Generate new project from description
scripts/commander.sh --project "Build a CLI todo app with SQLite backend"
For each issue:
For each PR:
For an epic:
For a project/milestone:
| Flag | Description | Default |
|---|---|---|
--model <name> | Model to use | (default) |
--push / --no-push | Push changes | enabled |
--pr / --no-pr | Create PRs | enabled |
--cleanup / --no-cleanup | Delete worktrees | enabled |
-j, --jobs <n> | Max parallel jobs | unlimited |
--timeout <min> | Timeout per task | no timeout |
--dry-run | Preview only | disabled |
| Flag | Description | Default |
|---|---|---|
--epic <num> | Epic issue number | required |
--model <name> | Model for agents | (default) |
--max-retries <n> | Retries per task | 2 |
--wave-timeout <m> | Timeout per wave | 60 min |
--resume | Resume from state | disabled |
--force | Force start (override stale lock) | disabled |
-j, --jobs <n> | Jobs per wave | unlimited |
--dry-run | Plan only | disabled |
| Flag | Description | Default |
|---|---|---|
--milestone <num> | Milestone issue | - |
--epics <n> ... | Epic numbers | - |
--project <spec> | Project description | - |
--model <name> | Model for agents | (default) |
--max-parallel <n> | Parallel captains | 2 |
--max-retries <n> | Retries per epic | 1 |
--epic-timeout <m> | Timeout per epic | 120 min |
--resume | Resume from state | disabled |
--force | Force start (override stale lock) | disabled |
-j, --jobs <n> | Jobs per captain | unlimited |
--dry-run | Plan only | disabled |
# Swarm logs
tail -f .worktrees/*.log
# Captain state
cat .captain/epic-151.json | jq .
# Commander state
cat .commander/milestone-200.json | jq .
# Watch all logs
tail -f .worktrees/*.log .captain/*.log .commander/*.log
.worktrees/
โโโ issue-48/ # Worktree
โโโ issue-48.log # Log
โโโ issue-48.jsonl # Agent JSON log
โโโ issue-48.pr # PR URL
.captain/
โโโ epic-151.json # State
โโโ epic-151-plan.json # Plan
โโโ epic-151.log # Log
.commander/
โโโ milestone-200.json # State
โโโ milestone-200-plan.json # Plan
โโโ epic-151.log # Captain logs
โโโ epic-160.log
commander.sh --project "Todo CLI app"
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโ
โ Generate Plan โ โ Pi creates epics & issues
โโโโโโโโโโโโฌโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโ
โ Create GH Issues โ โ Creates epic + sub-issues
โโโโโโโโโโโโฌโโโโโโโโโโโ
โ
โโโโโโโโดโโโโโโโ
โผ โผ
โโโโโโโโโโ โโโโโโโโโโ
โCaptain โ โCaptain โ โ Parallel epics
โEpic #1 โ โEpic #2 โ
โโโโโฌโโโโโ โโโโโฌโโโโโ
โ โ
โผ โผ
โโโโโโโโโโ โโโโโโโโโโ
โ Waves โ โ Waves โ โ swarm.sh + pr-swarm.sh
โโโโโฌโโโโโ โโโโโฌโโโโโ
โ โ
โโโโโโโฌโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโ
โ Final Report โ โ Posted to milestone/project
โโโโโโโโโโโโโโโโโโโโโโโ
The scripts detect and handle various error types:
| Error Type | Detection | Behavior |
|---|---|---|
| Rate Limit (429) | "rate limit", "too many requests" | Retry with exponential backoff |
| Auth (401/403) | "unauthorized", "forbidden" | Fatal - stop immediately |
| Quota Exceeded | "quota", "billing", "insufficient" | Fatal - stop immediately |
| Timeout | Exit code 124 | Retry with backoff |
| Network | "connection", "ECONNREFUSED" | Retry with backoff |
| API Error (5xx) | "500", "502", "503" | Retry with backoff |
When quota/auth errors are detected:
fatal (won't retry)# Fix the issue (add credits, update API key, etc.)
# Then resume:
scripts/captain.sh --epic 151 --resume
# Force restart if lock is stale:
scripts/captain.sh --epic 151 --resume --force
--force overrides stale locks# Process issues with timeout
scripts/swarm.sh --timeout 30 -j 2 48 50 52
# Review PRs (no push)
scripts/pr-swarm.sh --no-push 101 102
# Dry run captain
scripts/captain.sh --epic 151 --dry-run
# Execute epic with opus
scripts/captain.sh --epic 151 --model opus -j 3
# Resume interrupted epic
scripts/captain.sh --epic 151 --resume
# Force resume if lock is stale
scripts/captain.sh --epic 151 --resume --force
# Execute milestone with 3 parallel captains
scripts/commander.sh --milestone 200 --max-parallel 3
# Execute specific epics
scripts/commander.sh --epics 151 160 175
# Generate and execute new project
scripts/commander.sh --project "Build REST API for user management with JWT auth"
# Dry run project generation (shows plan + creates issues)
scripts/commander.sh --project "CLI todo app" --dry-run
# Run cleanup after completion
scripts/commander.sh --milestone 200 --cleanup
# Merge PRs after completion
scripts/commander.sh --epics 151 160 --merge-prs