Codex Team

The lead orchestrates, Codex agents execute. Each agent gets one focused task. The team lead prevents file conflicts before spawning — the orchestrator IS the lock manager.

When to Use

• You have 2+ tasks (bug fixes, implementations, refactors)
• Tasks are well-scoped with clear instructions
• You want Codex execution with predictable isolation
• You may be in Claude or Codex runtime (skill auto-selects backend)

Don't use when: Tasks need tight shared-state coordination. Use /swarm for dependency-heavy wave orchestration.

Backend Selection (MANDATORY)

Select backend in this order:

1. spawn_agent available -> Codex experimental sub-agents (preferred)
2. Codex CLI available -> Codex CLI via Bash (codex exec ...)
3. skill tool is read-only (OpenCode) -> OpenCode subagents — task(subagent_type="general", prompt="<task prompt>")
4. None of the above -> fall back to /swarm

Pre-Flight (CLI backend only)

# REQUIRED before spawning with Codex CLI backend
if ! which codex > /dev/null 2>&1; then
  echo "Codex CLI not found. Install: npm i -g @openai/codex"
  # Fallback: use /swarm
fi

# Model availability test
CODEX_MODEL="${CODEX_MODEL:-gpt-5.3-codex}"
if ! codex exec --full-auto -m "$CODEX_MODEL" -C "$(pwd)" "echo ok" > /dev/null 2>&1; then
  echo "Codex model $CODEX_MODEL unavailable. Falling back to /swarm."
fi

Canonical Command

codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o <output-file> "<prompt>"

Flag order: --full-auto -> -m -> -C -> -o -> prompt. Always this order.

Valid flags: --full-auto, -m, -C, -o, --json, --output-schema, --add-dir, -s

DO NOT USE: -q, --quiet (don't exist)

Cross-Project Tasks

When tasks span multiple repos/directories, use --add-dir to grant access:

codex exec --full-auto -m gpt-5.3-codex -C "$(pwd)" --add-dir /path/to/other/repo -o output.md "prompt"

The --add-dir flag is repeatable for multiple additional directories.

Progress Monitoring (optional)

Add --json to stream JSONL events to stdout for real-time monitoring:

codex exec --full-auto --json -m gpt-5.3-codex -C "$(pwd)" -o output.md "prompt" 2>/dev/null

Key events:

• turn.started / turn.completed — track progress
• turn.completed includes token usage field
• No events for 60s → agent likely stuck

Sandbox Levels

Use -s to control the sandbox:

For code review and analysis tasks, prefer -s read-only over --full-auto.

Execution

Step 1: Define Tasks

Break work into focused tasks. Each task = one Codex agent (unless merged).

Step 2: Analyze File Targets (REQUIRED)

Before spawning, identify which files each task will edit. Codex agents are headless — they can't negotiate locks or wait turns. All conflict prevention happens here.

For each task, list the target files. Then apply the right strategy:

# Decision logic (team lead performs this mentally):

tasks = [
  {name: "fix spec_path",    files: ["cmd/zeus.go"]},
  {name: "remove beads field", files: ["cmd/zeus.go"]},
  {name: "fix dispatch counter", files: ["cmd/zeus.go"]},
]

# All touch zeus.go → MERGE into 1 agent

tasks = [
  {name: "fix auth bug",     files: ["pkg/auth.go"]},
  {name: "add rate limiting", files: ["pkg/auth.go", "pkg/middleware.go"]},
  {name: "update config",    files: ["internal/config.go"]},
]

# Task 1 and 2 share auth.go → MULTI-WAVE (1+3 parallel, then 2)
# Task 3 is independent → runs in Wave 1 alongside Task 1

tasks = [
  {name: "fix auth",    files: ["pkg/auth.go"]},
  {name: "fix config",  files: ["internal/config.go"]},
  {name: "fix logging", files: ["pkg/log.go"]},
]

# No overlap → PARALLEL (all 3 at once)

Step 3: Spawn Agents

Strategy: Parallel (no file overlap)

Codex sub-agent backend (preferred):

spawn_agent(message="Fix the null check in pkg/auth.go:validateToken around line 89...")
spawn_agent(message="Add timeout field to internal/config.go:Config struct...")
spawn_agent(message="Fix log rotation in pkg/log.go:rotateLogFile...")

Codex CLI backend:

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/auth-fix.md "Fix the null check in pkg/auth.go:validateToken around line 89..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/config-fix.md "Add timeout field to internal/config.go:Config struct..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)

Strategy: Merge (same file)

Combine all fixes into a single agent prompt:

spawn_agent(message="Fix these 3 issues in cmd/zeus.go: (1) rename spec_path to spec_location in QUEST_REQUEST payload (2) remove beads field (3) fix dispatch counter increment location")

# CLI equivalent:
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md \
  "Fix these 3 issues in cmd/zeus.go: \
   (1) Line 245: rename spec_path to spec_location in QUEST_REQUEST payload \
   (2) Line 250: remove the spurious beads field from the payload \
   (3) Line 196: fix dispatch counter — increment inside the loop, not outside"', run_in_background=true)

One agent, one file, no conflicts possible.

Strategy: Multi-wave (partial overlap)

# Wave 1: non-overlapping tasks (sub-agent backend)
spawn_agent(message='Fix null check in pkg/auth.go:89...')
spawn_agent(message='Add timeout to internal/config.go...')

# Wait for Wave 1 (sub-agent backend)
wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)

# Wave 1: non-overlapping tasks (CLI backend)
Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "Fix null check in pkg/auth.go:89..."', run_in_background=true)
Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "Add timeout to internal/config.go..."', run_in_background=true)

# Wait for Wave 1
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)

# Read Wave 1 results — understand what changed
Read(.agents/codex-team/auth-fix.md)
git diff pkg/auth.go

# Wave 2: task that shares files with Wave 1 (sub-agent backend)
spawn_agent(message='Add rate limiting to pkg/auth.go and pkg/middleware.go. Note: validateToken now has a null check at line 89. Build on current file state.')

# Wave 2: CLI backend equivalent
Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md \
  "Add rate limiting to pkg/auth.go and pkg/middleware.go. \
   Note: pkg/auth.go was recently modified — the validateToken function now has a null check at line 89. \
   Build on the current state of the file."', run_in_background=true)

TaskOutput(task_id="<id-3>", block=true, timeout=120000)

The team lead synthesizes Wave 1 results and injects relevant context into Wave 2 prompts. Don't dump raw diffs — describe what changed and why it matters for the next task.

Step 4: Wait for Completion

# Sub-agent backend:
wait(ids=["<id-1>", "<id-2>", "<id-3>"], timeout_ms=120000)

# CLI backend:
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)

Step 5: Verify Results

• Read output files from .agents/codex-team/
• Check git diff for changes made by each agent
• Run tests if applicable
• For multi-wave: verify Wave 2 agents built correctly on Wave 1 changes

Output Directory

mkdir -p .agents/codex-team

Output files: .agents/codex-team/<task-name>.md

Prompt Guidelines

Good Codex prompts are specific and self-contained:

# GOOD: Specific file, line, exact change
"Fix in cmd/zeus.go line 245: rename spec_path to spec_location in the QUEST_REQUEST payload struct"

# BAD: Vague, requires exploration
"Fix the spec path issue somewhere in the codebase"

Include in each prompt:

• Exact file path(s)
• Line numbers or function names
• What to change and why
• Any constraints (don't touch other files, preserve API compatibility)

For multi-wave Wave 2+ prompts, also include:

• What changed in prior waves (summarized, not raw diffs)
• Current state of shared files after prior edits

Limits

• Max agents: 6 per wave (resource-reasonable)
• Timeout: 2 minutes default per agent. Increase with timeout param for larger tasks
• Max waves: 3 recommended. If you need more, reconsider task decomposition

Team Runner Backend (Headless Orchestration)

For headless batch execution of multiple Codex agents with structured output, use the team-runner script. This is the recommended backend when you need deterministic orchestration without interactive sessions.

When to Use Team Runner

• Headless CI/CD or automation contexts
• Batch execution where all agents run from a single spec file
• When you need structured JSONL event monitoring and token tracking
• When you need retry logic and consolidated reporting

Team Spec Format

Create a JSON spec file conforming to lib/schemas/team-spec.json:

{
  "team_id": "my-team-001",
  "repo_path": "/path/to/repo",
  "agents": [
    {
      "name": "fix-auth",
      "prompt": "Fix the null check in pkg/auth.go:validateToken around line 89",
      "files": ["pkg/auth.go"],
      "output_file": "auth-fix.json",
      "sandbox_level": "workspace-write"
    },
    {
      "name": "fix-config",
      "prompt": "Add timeout field to internal/config.go:Config struct",
      "files": ["internal/config.go"],
      "output_file": "config-fix.json",
      "sandbox_level": "read-only"
    }
  ]
}

Running

# Execute team
bash lib/scripts/team-runner.sh path/to/team-spec.json

# Dry run (shows commands without executing)
TEAM_RUNNER_DRY_RUN=1 bash lib/scripts/team-runner.sh path/to/team-spec.json

Components

Features

• Pre-flight checks: Validates codex, jq, git availability; sets BEADS_NO_DAEMON=1
• JSONL event watching: Monitors turn.completed events, tracks token usage, detects idle agents
• Retry logic: Up to 3 attempts per failed agent with context injection
• Sandbox mapping: workspace-write -> --full-auto, read-only -> -s read-only, full-access -> -s danger-full-access
• Consolidated reporting: Generates team-report.md with per-agent status, tokens, duration

Environment Variables

Output

Results are written to .agents/teams/<team_id>/:

• <agent-name>/output.json — Agent output artifact
• <agent-name>/events.jsonl — Raw JSONL event stream
• <agent-name>/status.json — Watcher status (tokens, duration, exit code)
• team-report.md — Consolidated team report

Fallback

If Codex is unavailable, delegate to /swarm which auto-selects the best available backend (native teams with messaging/redirect/graceful shutdown, or background tasks as last resort):

Skill(skill="swarm")

Note: /codex-team runs Codex CLI processes as background shell commands — this is fine (separate OS processes). For Claude agent orchestration, use /swarm which uses your runtime's native multi-agent primitives.

Quick Reference

---

Examples

Parallel Execution (No File Overlap)

User says: Fix three bugs in auth.go, config.go, and logging.go using /codex-team

What happens:

1. Agent analyzes file targets (auth.go, config.go, log.go — no overlap)
2. Agent selects PARALLEL strategy
3. Agent spawns three Codex agents (sub-agents if available, else CLI via Bash)
4. All agents execute simultaneously, write to .agents/codex-team/*.md
5. Team lead verifies results with git diff and tests
6. Team lead commits all changes together

Result: Three bugs fixed in parallel with zero file conflicts.

Merge Strategy (Same File)

User says: Fix three issues in zeus.go: rename field, remove unused field, fix counter

What happens:

1. Agent analyzes file targets (all three tasks touch zeus.go)
2. Agent selects MERGE strategy
3. Agent combines all three fixes into a single Codex prompt with line-specific instructions
4. Agent spawns ONE Codex agent with merged prompt
5. Agent completes all three fixes in one pass
6. Team lead verifies and commits

Result: One agent, one file, no conflicts possible.

Multi-Wave (Partial Overlap)

User says: Fix auth.go, add rate limiting to auth.go + middleware.go, update config.go

What happens:

1. Agent identifies overlap: tasks 1 and 2 both touch auth.go
2. Agent decomposes into waves: W1 = task 1 + task 3 (non-overlapping), W2 = task 2
3. Agent spawns Wave 1 agents in parallel, waits for completion
4. Agent reads Wave 1 results, synthesizes context for Wave 2
5. Agent spawns Wave 2 agent with updated file-state context
6. Team lead validates and commits after Wave 2

Result: Sequential wave execution prevents conflicts, context flows forward.

---

Troubleshooting