codex-orchestrator

name	codex-orchestrator
description	DEFAULT PIPELINE for all tasks requiring execution. You (Claude) are the strategic orchestrator. Codex agents are your implementation army - hyper-focused coding specialists. Trigger on ANY task involving code, file modifications, codebase research, multi-step work, or implementation. This is NOT optional - Codex agents are the default for all execution work. Only skip if the user explicitly asks you to do something yourself.
triggers	["codex-orchestrator","spawn codex","use codex","delegate to codex","start agent","codex agent","init","setup codex"]

Codex Orchestrator

The Command Structure

USER - directs the mission
    |
    ├── CLAUDE #1 (Opus) --- General
    |       ├── CODEX agent
    |       ├── CODEX agent
    |       └── CODEX agent ...
    |
    ├── CLAUDE #2 (Opus) --- General
    |       ├── CODEX agent
    |       └── CODEX agent ...
    |
    ├── CLAUDE #3 (Opus) --- General
    |       └── CODEX agent ...
    |
    └── CLAUDE #4 (Opus) --- General
            └── CODEX agent ...

The user is in command. They set the vision, make strategic decisions, approve plans. They can direct multiple Claude instances simultaneously.

You (Claude) are their general. You command YOUR Codex army on the user's behalf. You are in FULL CONTROL of your agents:

• You decide which agents to spawn
• You decide what tasks to give them
• You coordinate your agents working in parallel
• You course-correct or kill agents as needed
• You synthesize your army's work into results for the user

The user can run 4+ Claude instances in parallel. Each Claude has its own Codex army. This is how massive codebases get built in days instead of weeks.

You handle the strategic layer. You translate the user's intent into actionable commands for YOUR army.

Codex agents are the army under your command. Hyper-focused coding specialists. Extremely thorough and effective in their domain - they read codebases deeply, implement carefully, and verify their work. They get the job done right.

Codex reports to you. You report to the user.

CRITICAL RULES

Rule 1: Codex Agents Are the Default

For ANY task involving:

• Writing or modifying code
• Researching the codebase
• Investigating files or patterns
• Security audits
• Testing
• Multi-step execution
• Anything requiring file access

Spawn Codex agents. Do not do it yourself. Do not use Claude subagents.

Rule 2: You Are the Orchestrator, Not the Implementer

Your job:

• Discuss strategy with the user
• Write PRDs and specs
• Spawn and direct Codex agents
• Synthesize agent findings
• Make decisions about approach
• Communicate progress

Not your job:

• Implementing code yourself
• Doing extensive file reads to "understand before delegating"
• Using Claude subagents (Task tool) unless the user explicitly asks

Rule 3: Only Exceptions

Use Claude subagents ONLY when:

• The user explicitly requests it ("you do it", "don't use Codex", "use a Claude subagent")
• Quick single-file read for conversational context

Otherwise: Codex agents. Always.

Prerequisites

Before codex-agent can run, three things must be installed:

1. tmux - Terminal multiplexer (agents run in tmux sessions)
2. Bun - JavaScript runtime (runs the CLI)
3. OpenAI Codex CLI - The coding agent being orchestrated

The user must also be authenticated with OpenAI (codex --login) so agents can make API calls.

Quick Check

codex-agent health    # checks tmux + codex are available

If Not Installed

If the user says "init", "setup", or codex-agent is not found, run the install script:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh"

Always use the install script. Do NOT manually check dependencies or try to install things yourself step-by-step. The script handles everything: detects the platform, checks each dependency, installs what's missing via official package managers, clones the repo, and adds codex-agent to PATH. No sudo required.

If ${CLAUDE_PLUGIN_ROOT} is not available (manual skill install), the user can run:

bash ~/.codex-orchestrator/plugins/codex-orchestrator/scripts/install.sh

After installation, the user must authenticate with OpenAI if they haven't already:

codex --login

All dependencies use official sources only. tmux from system package managers, Bun from bun.sh, Codex CLI from npm. No third-party scripts or unknown URLs.

The Factory Pipeline

USER'S REQUEST
     |
     v
1. IDEATION        (You + User)
     |
2. RESEARCH         (Codex, read-only)
     |
3. SYNTHESIS        (You)
     |
4. PRD              (You + User)
     |
5. IMPLEMENTATION   (Codex, workspace-write)
     |
6. REVIEW           (Codex, read-only)
     |
7. TESTING          (Codex, workspace-write)

You handle stages 1, 3, 4 - the strategic work. Codex agents handle stages 2, 5, 6, 7 - the execution work.

Pipeline Stage Detection

Detect where you are based on context:

Signal	Stage	Action
New feature request, vague problem	IDEATION	Discuss with user, clarify scope
"investigate", "research", "understand"	RESEARCH	Spawn read-only Codex agents
Agent findings ready, need synthesis	SYNTHESIS	You review, filter, combine
"let's plan", "create PRD", synthesis done	PRD	You write PRD to docs/prds/
PRD exists, "implement", "build"	IMPLEMENTATION	Spawn workspace-write Codex agents
Implementation done, "review"	REVIEW	Spawn review Codex agents
"test", "verify", review passed	TESTING	Spawn test-writing Codex agents

Core Principles

1. Gold Standard Quality - No shortcuts. Security, proper patterns, thorough testing - all of it.
2. Always Interactive - Agents stay open for course correction. Never kill and respawn - send a message to redirect.
3. Parallel Execution - Multiple Claude instances can spawn multiple Codex agents simultaneously.
4. Codebase Map Always - Every agent gets --map for context.
5. PRDs Drive Implementation - Complex changes get PRDs in docs/prds/.
6. Patience is Required - Agents take time. This is normal and expected.
7. Turn-Aware by Default - Use await-turn to block until agents respond. No manual polling.

Agent Timing Expectations (CRITICAL - READ THIS)

Codex agents take time. This is NORMAL. Do NOT be impatient.

Task Type	Typical Duration
Simple research	10-20 minutes
Implementation (single feature)	20-40 minutes
Complex implementation	30-60+ minutes
Full PRD implementation	45-90+ minutes

Why agents take this long:

• They read the codebase thoroughly (not skimming)
• They think deeply about implications
• They implement carefully with proper patterns
• They verify their work (typecheck, tests)
• They handle edge cases

When you keep talking to an agent via codex-agent send, it stays open and continues working. Sessions can extend to 60+ minutes easily - and that is FINE. A single agent that you course-correct is often better than killing and respawning.

Do NOT:

• Kill agents just because they have been running for 20 minutes
• Assume something is wrong if an agent runs for 30+ minutes
• Spawn new agents to replace ones that are "taking too long"
• Ask the user "should I check on the agent?" after 15 minutes

DO:

• Use codex-agent await-turn <id> in a background Bash task to get notified instantly when an agent finishes
• Check progress with codex-agent capture <id> if you need to peek before a turn completes
• Send clarifying messages if the agent seems genuinely stuck (no progress for 5+ minutes)
• Let agents finish their work - they are thorough for a reason
• Trust the process - quality takes time

await-turn has NO wall-clock timeout. It blocks until one of: the agent completes a turn, hits the context window, the job ends, or you SIGINT. A long-running await-turn does NOT mean the agent is dead - it means the agent is still working. Never re-spawn just because await-turn has been blocked for a while.

Codebase Map: Giving Agents Instant Context

The --map flag is the most important flag you'll use. It injects docs/CODEBASE_MAP.md into the agent's prompt - a comprehensive architecture document that gives agents instant understanding of the entire codebase: file purposes, module boundaries, data flows, dependencies, conventions, and navigation guides.

Without a map, agents waste time exploring and guessing at structure. With a map, agents know exactly where things are and how they connect. They start working immediately instead of orienteering.

The map is generated by Cartographer, a separate Claude Code plugin that scans your codebase with parallel subagents and produces the map:

/plugin marketplace add kingbootoshi/cartographer
/plugin install cartographer
/cartographer

This creates docs/CODEBASE_MAP.md. After that, every codex-agent start ... --map command gives agents full architectural context.

Always generate a codebase map before using codex-orchestrator on a new project. It's the difference between agents that fumble around and agents that execute with precision.

CLI Defaults

The CLI ships with strong defaults so most commands need minimal flags:

Setting	Default	Why
Model	gpt-5.5	Full capability model
Reasoning	low	Efficient default; raise with -r high or -r xhigh for harder work
Sandbox	workspace-write	Agents can modify files by default

You almost never need to override these. The main flags you'll use are --map (include codebase context), -s read-only (for research tasks), and -f (include specific files).

Turn-Aware Orchestration

Codex agents have a built-in notify hook that fires the instant an agent finishes responding. This means you get notified within milliseconds of an agent going idle - no polling, no delays, no forgetting to check.

How It Works

When codex-agent start spawns an agent, it injects a per-job notify hook via -c notify=.... When the Codex agent finishes a turn, Codex calls our script with a JSON payload containing the agent's response. The script writes a signal file at ~/.codex-agent/jobs/<jobId>.turn-complete. The await-turn command blocks until that file appears.

Each job gets its own notify command with its own job ID baked in. 16 agents running in the same directory? No ambiguity - each one's hook writes to its own signal file.

The Standard Orchestration Loop

This is how you should interact with agents. Use this pattern every time.

Step 1: Spawn (foreground, instant - get the job ID)

codex-agent start "Your task prompt here" -r high --map -s read-only

Parse the job ID from the output.

Step 2: Await (blocks until agent responds)

Use the Bash tool with run_in_background: true:

JOB_ID="abc12345"
codex-agent await-turn "$JOB_ID"
echo "CODEX_AGENT_TURN_COMPLETE=$JOB_ID"
codex-agent status "$JOB_ID"

This gives you a task_id from Claude's background task system. When the agent finishes its turn, TaskOutput returns the agent's response.

Step 3: React - Read the output, decide what to do next:

• Send a follow-up: codex-agent send $id "Now do X"
• Close it: codex-agent send $id "/quit"
• Just read more: codex-agent capture $id 200 --clean

If you send a follow-up, repeat Step 2 to await the next turn.

Spawning Multiple Agents in Parallel

When spawning N agents, make all Step 1 calls in parallel (single message, multiple Bash tool calls). Then make all Step 2 calls in parallel (single message, multiple Bash tool calls with run_in_background: true).

Message 1 (parallel foreground):
  - Bash: codex-agent start "Research task A" --map -s read-only
  - Bash: codex-agent start "Research task B" --map -s read-only
  - Bash: codex-agent start "Research task C" --map -s read-only

Message 2 (parallel background):
  - Bash (bg): codex-agent await-turn <jobA>; echo "DONE_A"; codex-agent status <jobA>
  - Bash (bg): codex-agent await-turn <jobB>; echo "DONE_B"; codex-agent status <jobB>
  - Bash (bg): codex-agent await-turn <jobC>; echo "DONE_C"; codex-agent status <jobC>

Each background task notifies you independently the instant its agent finishes. No 3-second poll gaps. No wasted time.

Multi-Turn Conversation Pattern

For tasks requiring back-and-forth with an agent:

# Spawn
codex-agent start "Investigate the auth module" --map -s read-only
# Block until agent responds
codex-agent await-turn $id
# Read what it said
codex-agent status $id
# Send follow-up
codex-agent send $id "Now check the database layer"
# Block again
codex-agent await-turn $id
# Read response, close when done
codex-agent send $id "/quit"

Checking on Agents Without Waiting

You do NOT have to use await-turn. At any time you can still:

codex-agent status <jobId>           # includes turn state, last message
codex-agent capture <jobId> 50       # peek at recent output
codex-agent send <jobId> "message"   # steer the agent
codex-agent jobs --json              # check all agents at once

When "completed" Actually Fires

A Codex job status stays running after the agent has answered - it only transitions to completed when the session is closed. This happens when:

• The agent finishes and exits naturally
• You send /quit via codex-agent send <id> "/quit"
• The session times out from inactivity

So if you use await-turn, you get the agent's response immediately. Then you decide whether to send a follow-up or close the session.

Signal File Interface (For Advanced Bash Scripting)

The signal file is a plain JSON file. You can check it directly from bash without spawning a subprocess:

signal="$HOME/.codex-agent/jobs/${id}.turn-complete"
# Cheapest possible check - no subprocess
while [ ! -f "$signal" ]; do sleep 1; done
# Read the agent's message
cat "$signal"

The codex-bg -t wrapper also supports turn notifications:

codex-bg -t -- codex-agent start "task"
# Prints CODEX_AGENT_TURN_COMPLETE=<id> on each turn

CLI Reference

Spawning Agents

# Research (read-only - override sandbox)
codex-agent start "Investigate auth flow for vulnerabilities" --map -s read-only

# Implementation (defaults are perfect - high reasoning, workspace-write)
codex-agent start "Implement the auth refactor per PRD" --map

# With file context
codex-agent start "Review these modules" --map -f "src/auth/**/*.ts" -f "src/api/**/*.ts"

Monitoring Agents

# Wait for agent to finish current turn (PREFERRED - blocks until done)
codex-agent await-turn <jobId>

# Status with turn info - shows turn state, count, last message
codex-agent status <jobId>

# Structured status - tokens, files modified, summary
codex-agent jobs --json

# Human readable table
codex-agent jobs

# Recent output
codex-agent capture <jobId>
codex-agent capture <jobId> 200    # more lines

# Full output
codex-agent output <jobId>

# Live stream
codex-agent watch <jobId>

Communicating with Agents

# Send follow-up message
codex-agent send <jobId> "Focus on the database layer"
codex-agent send <jobId> "The dependency is installed. Run bun run typecheck"

# Direct tmux attach (for full interaction)
tmux attach -t codex-agent-<jobId>
# Ctrl+B, D to detach

IMPORTANT: Use codex-agent send, not raw tmux send-keys. The send command handles escaping and timing properly.

Control

codex-agent kill <jobId>           # stop agent (last resort)
codex-agent clean                  # remove old jobs (>7 days)
codex-agent health                 # verify codex + tmux available

Flags Reference

Flag	Short	Values	Description
--reasoning	-r	low, medium, high, xhigh	Reasoning depth