Codex Swarm — Multi-Agent Orchestration
Parallel Codex 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
bash scripts/spawn-batch.sh "/path/to/project" "batch-1" "Description" /tmp/tasks.json
Roles & Models
| Role | Model | Reasoning | Use |
|---|---|---|---|
| architect | o3 | high | Design, planning, complex decisions |
| builder | codex-mini | medium | Feature implementation (parallel) |
| reviewer | o3 | medium | Auto-review via codex exec review |
| integrator | o3 | high | Cross-branch merge + conflict resolution |
Key Codex Features Used
codex exec --full-auto— non-interactive sandboxed executioncodex exec review— native code review (replaces custom reviewer)-c model=o3— deep reasoning model for complex tasks-c model_reasoning_effort=high— maximum reasoning depth
Scripts
| Script | Purpose |
|---|---|
spawn-batch.sh |
Spawn N parallel agents + integration watcher |
spawn-agent.sh |
Spawn single agent (manual worktree + tmux + codex exec) |
endorse-task.sh |
Endorse task before spawn |
check-agents.sh |
Show running agent status |
cleanup.sh |
Remove worktrees, branches, sessions |
notify.sh |
Webhook/Telegram notification |
notify-on-complete.sh |
Auto-watcher with native codex exec review |
integration-watcher.sh |
Auto-merge when batch completes |
Setup
- Copy
scripts/andconfig/to your workspace - Configure
config/swarm.conf(copy from.example) - Required:
bash 4+,tmux,git,gh,jq,codex(Codex CLI)