/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