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.
For Claude-runtime feature compatibility (agents/hooks/worktree/settings), use
../shared/references/claude-code-latest-features.md
when this skill falls back to
/swarm
.
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:
spawn_agent
available ->
Codex experimental sub-agents
(preferred)
Codex CLI available ->
Codex CLI via Bash
(
codex exec ...
)
skill
tool is read-only (OpenCode) ->
OpenCode subagents
—
task(subagent_type="general", prompt="
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
"
" 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: Level Flag Use When Read-only -s read-only Judges, reviewers (no file writes needed) Workspace write -s workspace-write Default with --full-auto Full access -s danger-full-access Only in externally sandboxed environments 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: File Overlap Strategy Action All tasks touch same file Merge Combine into 1 agent with all fixes Some tasks share files Multi-wave Shared-file tasks go sequential across waves No overlap Parallel Spawn all agents at once
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=["
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="
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="
Sub-agent backend:
wait(ids=["
CLI backend:
TaskOutput(task_id="
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
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
Item
Value
Model
gpt-5.3-codex
Command
codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o