codex-swarm

name

codex-swarm

description

OpenAI Codex-native multi-agent swarm orchestration for parallel coding. Use when spawning multiple Codex CLI agents to work in parallel with git worktrees, tmux tracking, endorsement gates, native code review, integration merging, and webhook notifications. All agents are Codex (o3 for architect/integrator/reviewer, codex-mini for builders). Triggers on parallel coding, multi-agent work, swarm orchestration, or batch spawning with OpenAI models.

Credential Fixture Review

python scripts/_env_constants.py is review material for the Codex Swarm — Multi-Agent Orchestration skill. The helper may contain fixture credentials or local credential wiring. Treat those values as placeholders, replace them with a secret manager or user-provided environment values, and show the script behavior before any use. Do not contact external services with embedded sample credentials.

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

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

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)