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.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| 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