Codex Swarm — Multi-Agent Orchestration#

Parallel Codex agents: plan → endorse → spawn → monitor → review → integrate → ship.

Quick Start#

bash

# 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#

RoleModelReasoningUsearchitecto3highDesign, planning, complex decisionsbuildercodex-minimediumFeature implementation (parallel)reviewero3mediumAuto-review via codex exec reviewintegratoro3highCross-branch merge + conflict resolution

Key Codex Features Used#

• codex exec --full-auto — non-interactive sandboxed execution
• codex 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#

ScriptPurposespawn-batch.shSpawn N parallel agents + integration watcherspawn-agent.shSpawn single agent (manual worktree + tmux + codex exec)endorse-task.shEndorse task before spawncheck-agents.shShow running agent statuscleanup.shRemove worktrees, branches, sessionsnotify.shWebhook/Telegram notificationnotify-on-complete.shAuto-watcher with native codex exec review``integration-watcher.shAuto-merge when batch completes

Setup#

1. Copy scripts/ and config/ to your workspace
2. Configure config/swarm.conf (copy from .example)
3. Required: bash 4+, tmux, git, gh, jq, codex (Codex CLI)