codex-orchestrator（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 1.5: macOS Sandbox Compatibility

On macOS, Codex CLI (Rust binary) requires Unix socket access to configd for DNS resolution. If Claude Code's sandbox blocks this, codex exec will panic with system-configuration crate error.

Always run codex-agent Bash calls with dangerouslyDisableSandbox: true to prevent this crash. This is safe because codex-agent manages its own sandbox via -s flag.

// CORRECT - always use dangerouslyDisableSandbox for codex-agent
Bash(codex-agent start "..." --map, dangerouslyDisableSandbox: true)
Bash(codex-agent await-turn <id>, dangerouslyDisableSandbox: true)
Bash(codex-agent status <id>, dangerouslyDisableSandbox: true)
Bash(codex-agent capture <id>, dangerouslyDisableSandbox: true)

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: Trivial Task Bypass

For changes that are < 50 lines in a single file with clear requirements (typo fix, config tweak, simple rename), use your native tools directly. Do NOT spawn a Codex agent for trivial work — it adds 10-20 minutes of overhead for a 30-second edit.

Examples of trivial tasks (do yourself):

• Fix a typo in a comment or string
• Add/remove a single import
• Change a config value
• Rename a variable in one file

Examples of non-trivial tasks (spawn Codex):

• Any multi-file change
• Changes requiring understanding of data flow
• Security-sensitive modifications
• Anything touching tests

Rule 4: Only Exceptions for Claude Subagents

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:

Core Principles

1. Gold Standard Quality - No shortcuts. Security, proper patterns, thorough testing - all of it.
2. Exec by Default, Interactive When Needed - Use exec mode (auto-completes) for most tasks. Use --interactive only when you need mid-task send for course correction.
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. Constrain Codex 5.3 - Always inject scope and context constraints. Codex 5.3 is fast and eager — it will scope-drift, over-refactor, and skip reading without explicit fencing.
8. Turn-Aware by Default - Use await-turn to block until agents respond. No manual polling.

Writing Effective Agent Prompts (GPT-5.3-Codex)

GPT-5.3-Codex is fast, capable, and eager. It moves quickly and will skip reading, over-refactor, and drift scope if prompts aren't tight. When composing prompts for agents, always include the relevant constraint blocks below.

Mandatory Constraints (include in EVERY agent prompt)

Append these blocks to every prompt you send to Codex agents:

<design_and_scope_constraints>
- Implement EXACTLY and ONLY what is requested.
- No extra features, no refactoring of adjacent code, no UX embellishments.
- If any instruction is ambiguous, choose the simplest valid interpretation.
- Do NOT modify files or code outside the scope of the task.
</design_and_scope_constraints>

<context_loading>
- Read ALL files that will be modified -- in full, not just the sections mentioned in the task.
- Also read key files they import from or that depend on them.
- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
- Do not ask clarifying questions about things that are answerable by reading the codebase.
</context_loading>

For Multi-File / Complex Tasks (add to the above)

<plan_first>
- Before writing any code, produce a brief implementation plan:
  - Files to create vs. modify
  - Implementation order and prerequisites
  - Key design decisions and edge cases
  - Acceptance criteria for "done"
- Get the plan right first. Then implement step by step following the plan.
- If the plan is provided externally (e.g., PRD), follow it faithfully.
</plan_first>

<output_verbosity_spec>
- Default: 3-6 sentences or <=5 bullets for typical answers.
- Complex multi-step or multi-file tasks:
  - 1 short overview paragraph
  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
- Avoid long narrative paragraphs; prefer compact bullets and short sections.
</output_verbosity_spec>

Verification Criteria

Always tell the agent what "done" looks like. Include acceptance criteria in the prompt:

Verification:
- [ ] Typecheck passes (bun run typecheck or tsc --noEmit)
- [ ] No new lint warnings
- [ ] Existing tests still pass
- [ ] [task-specific criteria]

Prompt Composition Example

Instead of a bare prompt like:

codex-agent start "Fix the auth bug" --map

Compose a constrained prompt:

codex-agent start "Fix the auth bypass bug in src/auth/session.ts where expired tokens are not rejected.

<design_and_scope_constraints>
- Fix ONLY the token expiration check. Do not refactor surrounding code.
- If any instruction is ambiguous, choose the simplest valid interpretation.
</design_and_scope_constraints>

<context_loading>
- Read src/auth/session.ts, src/auth/jwt.ts, and src/middleware/auth.ts in full before making changes.
</context_loading>

Verification:
- [ ] Expired tokens return 401
- [ ] Valid tokens still work
- [ ] Existing tests pass" --map

Reasoning Effort Guide

Exec vs Interactive Mode

Choose the right mode for each task:

# Exec mode (default) — auto-completes
codex-agent start "Implement the feature per PRD" --map

# Interactive mode — supports send for course correction
codex-agent start "Investigate the auth module" --map --interactive
# Later: codex-agent send <id> "Now check the session handling too"

Agent Timing Expectations (CRITICAL - READ THIS)

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

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

For interactive agents (--interactive): you can keep talking via codex-agent send. 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.

For exec agents (default): they auto-complete and exit. If the result isn't right, spawn a new agent with a refined prompt that includes context about what the previous attempt got wrong.

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

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:

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

The send command only works with interactive mode jobs (--interactive). Default exec mode jobs auto-complete and don't accept messages.

# Start an interactive agent (supports send)
codex-agent start "Analyze the auth module" --map --interactive

# 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

Jobs JSON Output

{
  "id": "8abfab85",
  "status": "completed",
  "elapsed_ms": 14897,
  "tokens": {
    "input": 36581,
    "output": 282,
    "context_window": 258400,
    "context_used_pct": 14.16
  },
  "files_modified": ["src/auth.ts", "src/types.ts"],
  "summary": "Implemented the authentication flow..."
}

Pipeline Stages in Detail

Stage 1: Ideation (You + User)

Talk through the problem with the user. Understand what they want. Think about how to break it down for the Codex army.

Your role here: Strategic thinking, asking clarifying questions, proposing approaches.

Even seemingly simple tasks go to Codex agents - remember, you are the orchestrator, not the implementer. The only exception is if the user explicitly asks you to do it yourself.

Stage 2: Research (Codex Agents - read-only)

Spawn parallel investigation agents. Use exec mode (default) for focused research:

codex-agent start "Map the data flow from API to database for user creation.

<context_loading>
- Read all relevant route handlers, service files, and database models in full.
- Trace the complete request lifecycle from HTTP handler to DB query.
</context_loading>

<design_and_scope_constraints>
- Report findings only. Do not suggest refactoring or improvements unless explicitly asked.
- If any instruction is ambiguous, choose the simplest valid interpretation.
</design_and_scope_constraints>" --map -s read-only

codex-agent start "Identify all places where user validation occurs.

<context_loading>
- Search the entire codebase for validation patterns, not just obvious locations.
</context_loading>

<design_and_scope_constraints>
- List findings with file paths and line references. No code modifications.
</design_and_scope_constraints>" --map -s read-only

Stage 3: Synthesis (You)

Review agent findings. This is where you add value as the orchestrator:

Filter bullshit from gold:

• Agent suggests splitting a 9k token file - likely good
• Agent suggests adding rate limiting - good, we want quality
• Agent suggests types for code we didn't touch - skip, over-engineering
• Agent contradicts itself - investigate further
• Agent misunderstands the codebase - discount that finding

Combine insights:

• What's the actual state of the code?
• What are the real problems?
• What's the right approach?

Stage 4: PRD Creation (You + User)

For significant changes, create PRD in docs/prds/:

# [Feature/Fix Name]

## Problem
[What's broken or missing]

## Solution
[High-level approach]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]

## Implementation Plan
### Phase 1: [Name]
- [ ] Task 1
- [ ] Task 2

### Phase 2: [Name]
- [ ] Task 3

## Files to Modify
- path/to/file.ts - [what changes]

## Testing
- [ ] Unit tests for X
- [ ] Integration test for Y

## Success Criteria
- [How we know it's done]

Review PRD with user before implementation.

Stage 5: Implementation (Codex Agents - workspace-write)

Spawn implementation agents with PRD context and constraints:

codex-agent start "Implement Phase 1 of docs/prds/auth-refactor.md.

<context_loading>
- Read the PRD in full first.
- Read ALL files listed in the PRD's 'Files to Modify' section before writing any code.
</context_loading>

<design_and_scope_constraints>
- Implement EXACTLY what Phase 1 specifies. Do not start Phase 2 work.
- Do not refactor existing code outside the scope of the PRD.
</design_and_scope_constraints>

<plan_first>
- Before writing code, list the files you will modify and the order of changes.
</plan_first>

Verification:
- [ ] Typecheck passes
- [ ] Existing tests still pass
- [ ] All Phase 1 tasks from PRD are completed" --map -f "docs/prds/auth-refactor.md"

For large PRDs, implement in phases with separate agents.

Stage 6: Review (Codex Agents - read-only)

Spawn parallel review agents:

# Security review
codex-agent start "Security review the changes. Check:
- OWASP top 10 vulnerabilities
- Auth bypass possibilities
- Data exposure risks
- Input validation
- SQL/command injection
Report any security concerns." --map -s read-only

# Error handling review
codex-agent start "Review error handling in changed files. Check for:
- Swallowed errors
- Missing validation
- Inconsistent patterns
- Raw errors exposed to clients
Report any violations." --map -s read-only

# Data integrity review
codex-agent start "Review for data integrity. Check:
- Existing data unaffected
- Database queries properly scoped
- No accidental data deletion
- Migrations are additive/safe
Report any concerns." --map -s read-only

After review agents complete — Review → Fix Loop:

1. Synthesize findings into categories: Critical (must fix), Important (should fix), Minor (note for later)
2. For each Critical finding, spawn a new implementation agent with:

- The specific finding as context - The original PRD reference - Explicit constraint: fix ONLY this issue

1. After fix agents complete, spawn a verification review agent to confirm the fixes
2. Repeat until no Critical findings remain
3. Note Important/Minor findings in a tracking file for future work

# Example: Review found SQL injection in auth module
codex-agent start "Fix SQL injection vulnerability found in src/auth/query.ts:45.
Review finding: User input is concatenated into SQL query without parameterization.

<design_and_scope_constraints>
- Fix ONLY the SQL injection in the identified location.
- Use parameterized queries matching the existing pattern in src/db/base-query.ts.
- Do not refactor other queries or add new abstractions.
</design_and_scope_constraints>

<context_loading>
- Read src/auth/query.ts and src/db/base-query.ts in full.
</context_loading>

Verification:
- [ ] Query uses parameterized input
- [ ] Existing tests pass
- [ ] No other queries modified" --map

Stage 7: Testing (Codex Agents - workspace-write)

# Write tests
codex-agent start "Write comprehensive tests for the auth module changes" --map

# Run verification
codex-agent start "Run typecheck and tests. Fix any failures." --map

Scaling: Multiple Claude Instances

The real power of this system is parallelism at every level:

USER runs 4 Claude instances simultaneously
  |
  Claude #1: researching auth module     (3 Codex agents)
  Claude #2: implementing feature A      (2 Codex agents)
  Claude #3: reviewing recent changes    (4 Codex agents)
  Claude #4: writing tests               (2 Codex agents)

When running multiple Claude Code sessions on the same codebase:

1. Each Claude instance spawns and manages its own agents independently
2. Use codex-agent jobs --json to see all agents across instances
3. Use job IDs to track which agent belongs to which Claude instance
4. Each Claude should claim a stage or module to prevent conflicts

This is how you get exponential execution: N Claude instances x M Codex agents each = N*M parallel workers on your codebase.

Agent Tracking

All agent state is stored per-job in ~/.codex-agent/jobs/ (one JSON + log file per agent). Use codex-agent jobs --json for a unified view across all instances.

Do NOT maintain a shared agents.log file. Multiple Claude instances writing to the same file causes race conditions and data loss. Instead:

• Use codex-agent jobs --json to check all agent status
• Use codex-agent status <id> for individual agent details (turn state, last message)
• Use codex-agent capture <id> --clean to read agent output
• Communicate findings to the user directly in conversation

Multi-Agent Patterns

Parallel Investigation

# Spawn 3 research agents simultaneously (parallel Bash calls)
codex-agent start "Audit auth flow" --map -s read-only          # -> jobA
codex-agent start "Review API security" --map -s read-only      # -> jobB
codex-agent start "Check data validation" --map -s read-only    # -> jobC

# Await all 3 in parallel (background Bash calls)
codex-agent await-turn $jobA; codex-agent status $jobA    # bg task 1
codex-agent await-turn $jobB; codex-agent status $jobB    # bg task 2
codex-agent await-turn $jobC; codex-agent status $jobC    # bg task 3

# Each notifies you independently the instant its agent finishes
# Quit each when done reading results
codex-agent send $jobA "/quit"
codex-agent send $jobB "/quit"
codex-agent send $jobC "/quit"

Sequential Implementation

# Phase 1
codex-agent start "Implement Phase 1 of PRD" --map       # -> job1
codex-agent await-turn $job1                              # blocks until done
codex-agent status $job1                                  # review result
codex-agent send $job1 "/quit"

# Phase 2 (after Phase 1 verified)
codex-agent start "Implement Phase 2 of PRD" --map       # -> job2
codex-agent await-turn $job2
codex-agent status $job2
codex-agent send $job2 "/quit"

Multi-Provider Patterns

The CLI supports --provider openai|gemini. Use these patterns when cross-model analysis adds value.

Pattern A: Parallel Analysis (reviewing existing code)

When: Analytical reasoning on project-specific code (bugs, security, architecture). Why: Both providers analyze the SAME code; different analytical approaches = useful signal. Constraint: At least one provider MUST be read-only to prevent filesystem races.

codex-agent start "review src/auth.ts for vulnerabilities" --provider openai -s read-only --map
codex-agent start "review src/auth.ts for vulnerabilities" --provider gemini --map
# Gemini defaults to read-only; OpenAI explicitly set here
# await both, then synthesize per Synthesis Protocol below

Pattern B: Generate → Adversarial Review (code generation)

When: Implementing or refactoring features. Why: Parallel generation produces style noise; sequential review produces substantive critique.

codex-agent start "implement auth refactor per PRD" --provider openai --map
# await completion, read output
codex-agent start "review this implementation for correctness, security, and edge cases: [paste output]" --provider gemini --map
# await, synthesize implementation + critique

Pattern C: Specialist Routing (context-heavy tasks)

When: Task requires 50+ files, cross-service analysis, large log analysis. Why: Gemini's context window advantage is decisive; single provider is sufficient.

codex-agent start "analyze dependency graph across all services" --provider gemini --map
# No consensus needed — specialist routing

When NOT to Use Multi-Provider

• Pattern-recognition tasks on common code (JWT, bcrypt) — correlated training = correlated blind spots
• Vague specs ("make it better") — divergence reflects ambiguity, not quality
• Trivial tasks — cost and latency not justified
• Subjective preferences (naming, formatting) — consensus is coincidence

Synthesis Protocol (Multi-Provider)

Pre-Synthesis

1. Randomly relabel provider outputs as "Analysis Alpha" and "Analysis Beta". Do NOT reveal which model produced which until AFTER synthesis.

Hard-Fail Preconditions (stop, do not synthesize)

• Either job status ≠ completed → report failure
• Either exit code ≠ 0 → report failure
• Either output is empty or clearly off-topic → flag and explain

Synthesis Steps (all four required, in order)

1. Enumerate differences — List every divergence between Alpha and Beta. Do NOT evaluate or judge. Format: "Alpha says X; Beta says Y."
2. Steel-man unique findings — For each finding reported by only one analysis: argue FOR it. Cite specific code or context that supports it. Do NOT evaluate yet.
3. Require technical rebuttal — For each unique finding: attempt to rebut with specific code evidence. PROHIBITED: Labeling any finding as "false positive" without citing (a) specific code evidence and (b) why the analysis's reasoning is wrong.
4. Preserve unrebutted — If you cannot technically rebut a finding, it MUST appear in the final synthesis, even if you disagree with severity.

Rules

• Never request or use self-reported scoring (e.g., Security: X/10)
• Output length is not a quality signal
• Agreement between providers is not proof of correctness (correlated training)
• For high-stakes tasks: use two separate synthesis passes (advocacy then judgment) to disrupt latent reasoning chain bias

Parallel Sandbox Safety

• In Pattern A (parallel execution), at least one provider MUST run read-only
• Default: Gemini is read-only unless user explicitly sets sandbox
• If both need write access: run sequentially, not in parallel

Quality Gates

Before marking any stage complete:

Error Recovery

Agent Stuck (exec mode)

codex-agent jobs --json           # check status
codex-agent capture <jobId> 100   # see what's happening
codex-agent kill <jobId>          # kill and respawn with refined prompt

Exec agents can't receive messages. If stuck, kill and spawn a new one with a better prompt.

Agent Stuck (interactive mode)

codex-agent jobs --json           # check status
codex-agent capture <jobId> 100   # see what's happening
codex-agent send <jobId> "Status update - what's blocking you?"
codex-agent kill <jobId>          # only if truly stuck

Agent Didn't Get Message

If codex-agent send doesn't seem to work:

1. Verify the job was started with --interactive (exec jobs don't support send)
2. Check agent is still running: codex-agent jobs --json
3. Agent might be "thinking" - wait a moment
4. Try sending again with clearer instruction
5. Attach directly: tmux attach -t codex-agent-<jobId>

Implementation Failed

1. Check the error in output
2. Don't retry with the same prompt
3. Mutate the approach - add context about what failed and include tighter constraint blocks
4. Consider splitting into smaller tasks

Post-Compaction Recovery

After Claude's context compacts, immediately:

# Check all running and completed agents
codex-agent jobs --json

# Check specific agent status
codex-agent status <jobId>

Review agent statuses. Understand current stage. Resume from where you left off.

When NOT to Use This Pipeline

Skip Codex agents when:

• The user explicitly says "you do it" or "don't use Codex"
• Pure conversation/discussion (no code, no files)
• You need to read a single file to understand context for the conversation
• Trivial changes (< 50 lines, single file, clear requirements) — use your native tools directly (see Rule 3)

Everything else goes to Codex agents. Even tasks you think you could handle yourself — your job is orchestration, not implementation. Codex agents are specialized for coding work, and delegating frees you to continue strategic discussion with the user.