Codex Orchestrator

Spawn specialized Codex CLI subagents for focused development tasks. Each profile becomes process-local developer instructions; the repository's global, root, and nested AGENTS.md files remain untouched and continue to apply.

Architecture

Claude Code (orchestrator)
    ↓ invokes skill
codex-orchestrator scripts
    ↓ spawns via Bash
Codex CLI with process-local persona + project AGENTS.md chain
    ↓ executes
Specialized subagent task

Prerequisites

Verify Codex CLI is installed and configured:

~/.claude/skills/codex-orchestrator/scripts/codex-status.sh

Required:

• Codex CLI: npm install -g @openai/codex
• API Key: export OPENAI_API_KEY=sk-...

Auto-Update

The skill automatically checks for Codex CLI updates on each invocation and updates if needed. This prevents issues caused by outdated CLI versions.

To manually check/update:

# Check version only
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh

# Check and auto-update if needed
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh --auto-update

Available Profiles

Profile	Purpose	Use When
reviewer	Code quality, bugs, performance	Pre-commit review, PR assessment
debugger	Root cause analysis, fixes	Investigating bugs, tracing issues
architect	System design, component boundaries	Planning changes, evaluating architecture
security	OWASP, vulnerabilities, secrets	Security audits, compliance checks
refactor	Code cleanup, modernization	Reducing tech debt, improving structure
docs	API docs, READMEs, comments	Documentation tasks
planner	ExecPlan design documents	Multi-hour tasks, complex features, significant refactors
syseng	Infrastructure, DevOps, CI/CD, monitoring	Deployment, containers, observability, production ops
builder	Greenfield implementation, new features	Creating new code from specs, incremental feature development
researcher	Read-only Q&A, codebase analysis	Questions, analysis, comparisons (no file changes)
adjudicator	Read-only comparative evidence weighing	Ambiguous hypotheses, rival interpretations, corpus comparisons, sign-value adjudication
chat	Open-ended conversation	General questions, brainstorming, discussion (read-only, ephemeral)
goal	Goal specification for /goal runs	Drafting structured objectives for autonomous multi-hour Codex sessions

Quick Execution

Execute a one-shot task with a specific profile:

~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh <profile> "<prompt>"

Examples:

# Code review
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/auth.ts for security issues"

# Debug investigation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the login timeout on slow networks"

# Architecture design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the payment module for vulnerabilities"

# Write profiles auto-approve by default (uses -a never + --sandbox workspace-write)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Fix all lint errors"

# Create execution plan for complex feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create an ExecPlan for adding WebSocket support"

# Build new feature from spec
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement user authentication with JWT"

# Continue from previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue"

# Open-ended conversation (read-only, ephemeral, gpt-5.6-terra via subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What are the tradeoffs of event sourcing vs CRUD?"

# Conversation via API billing (gpt-5.6-sol, bypasses Codex subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain quantum error correction" --api --model gpt-5.6-sol

# Multi-turn API chat with session file
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is the tallest mountain?" --api --session /tmp/chat.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "And the deepest ocean?" --api --session /tmp/chat.json

# Streaming API response
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me about CQRS" --api --model gpt-5.6-sol --stream

# Ask a question about the codebase (read-only, no file changes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "Explain the authentication flow in this project"

# Weigh rival hypotheses or ambiguous evidence (read-only, high reasoning)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh adjudicator "With Linear B and Linear A inscriptions side-by-side, weigh candidate values for the missing sound and rank the hypotheses."

# Research with Exa web search (appends Exa guide to this process's persona)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React Server Component patterns?" --web-search

# Research with native Codex web search (model-level tool, works in all sandboxes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --search

# Review a screenshot (vision input)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review this mockup for UX issues" --image screenshot.png

# Resume previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue" --resume

# JSONL output for structured capture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What is 2+2?" --json | head -5

GPT-6-Astra Subagents

Use codex-astra.sh to run any existing persona on GPT-6-Astra. The launcher defaults to medium reasoning on the standard tier and validates Astra-specific choices.

~/.claude/skills/codex-orchestrator/scripts/codex-astra.sh list
~/.claude/skills/codex-orchestrator/scripts/codex-astra.sh architect "Design a fault-tolerant queue" --reasoning max --service-tier priority

Astra exposes 12 effort/tier permutations per persona. Use priority when latency materially matters and ultra only for independent parallel workstreams. See references/codex-models.md for the matrix and CLI mapping.

Session Management

For more control, use the Python session manager:

# List available profiles
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py list

# Start non-interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py start debugger "Trace the null pointer in UserService"

# Start interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py interactive architect

# Show profile details
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py info security

Profile Selection Guide

Review Tasks

• reviewer for general code quality and bugs
• security for vulnerability-focused review
• refactor for cleanup opportunities

Investigation Tasks

• debugger for bug investigation
• architect for understanding system behavior
• researcher for questions and analysis (read-only, no changes)
• adjudicator for weighing rival hypotheses, ambiguous evidence, and corpus-level comparisons (read-only, high reasoning)
• chat for open-ended conversation and brainstorming (read-only, ephemeral)

Creation Tasks

• architect for design decisions
• builder for new feature implementation
• docs for documentation
• refactor for implementation improvements
• planner for multi-hour implementation plans
• goal for autonomous /goal objective specifications

Chaining Patterns

Review → Debug → Fix

# 1. Identify issues
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/api/ for bugs"

# 2. Investigate specific bug
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the race condition found in cache.ts"

Planner → Architect → Builder

# 1. Create comprehensive ExecPlan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for new authentication system"

# 2. Validate architecture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Review the auth system ExecPlan for design issues"

# 3. Build (plan guides implementation)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement milestone 1 from the auth ExecPlan"

Architect → Builder → Reviewer

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# 2. Build the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

# 3. Review the implementation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the new caching implementation"

Architect → Review → Refactor

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design repository layer extraction"

# 2. Validate design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the proposed repository pattern"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh refactor "Extract repository pattern from services"

Syseng → Architect → Planner

# 1. Assess infrastructure needs
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Evaluate current deployment for scaling to 10x traffic"

# 2. Design architecture changes
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design infrastructure to support 10x scale"

# 3. Create implementation plan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for infrastructure scaling"

Security → Syseng

# 1. Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the Kubernetes cluster configuration"

# 2. Infrastructure hardening
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Implement security recommendations from audit"

Researcher → Architect → Builder

# 1. Understand the problem space
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "How does the current caching work? What are its limitations?"

# 2. Design the solution
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a new caching layer addressing the limitations"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

Backgrounding & Parallel Execution

Codex CLI v0.124.0+ requires a controlling TTY. When run with shell & or Claude Code's run_in_background: true, the TTY is detached and Codex silently produces empty output (openai/codex#19945). Longer prompts increase failure likelihood (empirically observed) — the researcher profile is especially vulnerable.

codex-exec.sh and codex-goal.sh automatically detect non-TTY contexts and wrap codex exec with script(1) to re-attach a pseudo-TTY. No user action is required.

Inside Codex's own exec_command tool the command already has a PTY, so the wrapper stays out of the way; requesting tty:true there changes nothing and is not a fix for missing output.

For direct codex exec calls (not through codex-exec.sh), wrap manually:

# macOS
script -q /dev/null codex exec --skip-git-repo-check -- "prompt" </dev/null

# Linux
script -qfc 'codex exec --skip-git-repo-check -- "prompt" </dev/null' /dev/null

Argv rules for direct codex exec calls

• End options with -- before the prompt. -i/--image <FILE>... is variadic: placed right before the prompt it consumes the prompt as another image path, Codex then reads stdin, finds nothing, and exits 1 with No prompt provided via stdin. --image also splits its value on commas.
• With resume, pass -i after the subcommand: codex exec <opts> resume --last -i shot.png -- "prompt". A parent-level -i before resume swallows the word resume.
• Keep </dev/null. When stdin is not a terminal and a prompt is present, Codex prints Reading additional input from stdin... and appends whatever it reads as a <stdin> block; an immediate EOF makes that a harmless one-liner, while an open pipe hangs forever (openai/codex#27019).

Personas are passed with -c developer_instructions=...; multiple codex-exec.sh instances can run in the same directory without changing or serializing around AGENTS.md. Still serialize agents that write overlapping project files, or give them separate worktrees.

--no-cleanup flag (codex-exec.sh only): When set, the output temp file is preserved after exit and its path is printed to stderr (OUTPUT_FILE=<path>). Use when the caller needs to retrieve the output file asynchronously.

Goal Runs

The /goal command sets a persistent objective that Codex works toward autonomously for hours. Goals are TUI-only (not available in codex exec mode), so goal runs use a two-phase workflow.

Two-Phase Workflow

Phase 1 — Draft: Generate a structured goal specification file using codex exec with the goal profile.

Phase 2 — Run: Launch the interactive Codex TUI with /goal set from the spec file.

Usage

# Draft a goal specification
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Add authentication with JWT to the API"

# Draft with custom output path
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Migrate to PostgreSQL" --output goals/pg-migration.md

# List existing goals
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh list

# Launch Codex TUI with a goal
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# Run with custom model
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-01.md --model gpt-5.6-sol

Goal File Format

Goal specifications follow a structured format with YAML frontmatter:

---
objective: "One-line summary"
status: draft
created: 2026-05-18
project: /path/to/project
---

# Goal: <objective>

## Objective / Stopping Condition / Context / Constraints / Validation / Checkpoints / Progress Log

Goals under 3,500 characters are inlined directly into the /goal command. Longer goals are referenced by file path.

Chaining: Planner → Goal → Run → Reviewer

# 1. Plan the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching layer"

# 2. Draft a goal from the plan
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Implement caching layer per ExecPlan"

# 3. Launch autonomous goal run
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# 4. Review what Codex built
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the caching implementation"

Caveats

• /goal is TUI-only — the run subcommand launches an interactive Codex session (stdin is not redirected)
• Requires features.goals = true in ~/.codex/config.toml (or --enable goals flag, which the script passes automatically)
• One goal per thread — must /goal clear before setting a different goal
• 4,000 character limit on /goal content (the draft phase targets under 3,500 to leave overhead)

See references/goal-command.md for the full /goal command reference.

Script Options

codex-exec.sh Options

Option	Description
--model <model>	Override model (default: per-profile, see below)
--astra	Shortcut for --model gpt-6-astra
--reasoning <level>	Override reasoning effort: none, minimal, low, medium, high, xhigh, max, ultra
--service-tier <tier>	Override Codex CLI service tier: default or priority (not API mode)
--sandbox <mode>	read-only, workspace-write, danger-full-access
--no-approve	Force read-only sandbox (no file writes)
--web-search	Enable Exa web search (appends guide to process-local persona)
--search	Enable native Codex web search (model-level tool, works in all sandboxes)
--json	Output JSONL event stream (pipe to jq, logs, etc.)
--image <file>	Attach image to prompt (vision input); the launcher emits it after resume and before -- so the variadic -i cannot swallow the prompt
--resume	Resume previous exec session (builder "continue" workflow)
--with-mcp	(no-op, kept for compatibility; manage MCPs in ~/.codex/config.toml)
--api	Use OpenAI API directly (API billing, not Codex subscription)
--session <file>	Session file for multi-turn API chat (requires --api)
--system <prompt>	System prompt for API chat (requires --api)
--stream	Stream API response tokens (requires --api)

Model & Reasoning Defaults

Each profile has a default model and reasoning effort. User flags override these.

Profile Type	Profiles	Model	Reasoning
Coding	builder, reviewer, debugger, refactor, syseng, security, docs	gpt-5.6-sol	high
Planning	planner, architect, goal	gpt-5.6-sol	high
Research	researcher	gpt-5.6-sol	medium
Adjudication	adjudicator	gpt-5.6-sol	high
Chat	chat	gpt-5.6-terra	medium

General reasoning effort levels: none < minimal < low < medium < high < xhigh < max < ultra. Model support varies; Astra accepts low through ultra.

# Uses profile defaults (builder → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement auth module"

# Uses profile defaults (planner → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching"

# Override model for quick tasks
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Style check" --model gpt-5.6-luna

# Override reasoning only
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Quick lint fix" --reasoning medium

# Override both
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Design distributed cache" --model gpt-5.6-sol --reasoning max

# Astra at maximum depth on the priority tier
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Design distributed cache" --astra --reasoning max --service-tier priority

API Mode (Direct OpenAI API)

The --api flag bypasses Codex CLI entirely and calls the OpenAI API directly via gpt-api-chat.py. Billing goes to your OPENAI_API_KEY, not the Codex subscription.

When to use API mode:

• Access models not in your Codex subscription (e.g. gpt-5.6-sol)
• Multi-turn conversations with session persistence
• Streaming responses
• Custom system prompts

# One-shot API query
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain X" --api --model gpt-5.6-sol

# Multi-turn with session file (context carries across calls)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is X?" --api --session /tmp/session.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me more" --api --session /tmp/session.json

# Streaming output
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Describe Y" --api --model gpt-5.6-sol --stream

# Custom system prompt
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Analyze this" --api --system "You are a security analyst"

# Any profile works with --api (sends raw prompt to OpenAI API, no Codex CLI)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --api --model gpt-5.6-sol

Supported API-mode models: gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5-mini. Use codex-astra.sh for Astra subagents.

Three-way mode (Claude + GPT): Within a Claude Code session, invoke gpt-api-chat.py via Bash, read GPT's response, synthesize perspectives, and steer the conversation. Use --session to maintain GPT's context across turns.

Requires: OPENAI_API_KEY in environment (loaded from ~/.config/env/secrets.env)

Testing

Run the test suite to verify installation:

~/.claude/skills/codex-orchestrator/scripts/test-codex.sh         # Full tests
~/.claude/skills/codex-orchestrator/scripts/test-codex.sh --quick # Skip API test

Reference Documentation

For detailed information:

• references/codex-cli.md - Complete CLI command reference
• references/codex-models.md - Model, reasoning-effort, and service-tier matrix
• references/agents-md-format.md - AGENTS.md syntax and best practices
• references/subagent-patterns.md - Delegation patterns and examples
• references/goal-command.md - /goal command reference and best practices

Troubleshooting

"Codex CLI not found"

npm install -g @openai/codex

"Authentication error"

export OPENAI_API_KEY=sk-...
# or
codex login

"Model not supported with ChatGPT account"

Older model names (codex-mini, o3, o4-mini) have been deprecated. Current models include gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-pro, and gpt-5-mini. Previous generation (gpt-5.4, gpt-5.4-pro, gpt-5.3-codex, gpt-5.2) still works but is superseded. Set an API key instead of using codex login:

export OPENAI_API_KEY=sk-...

"Profile not found"

Available profiles: reviewer, debugger, architect, security, refactor, docs, planner, syseng, builder, researcher, adjudicator, chat, goal

Check profile exists:

ls ~/.claude/skills/codex-orchestrator/agents/

"Codex produced no output"

The researcher/adjudicator/chat profiles capture output to a temp file. If Codex exits without writing to it, the script prints the last diagnostic lines from Codex (stderr, PTY-merged log lines, and JSONL error events), warns, and exits 1. Read those lines first; they name the cause. Common causes:

• Prompt never reached Codex: stderr shows Reading prompt from stdin... then No prompt provided via stdin. This was the 2026-09-19 failure: --image was emitted directly before the prompt and the variadic -i consumed it. The launcher now places -i after resume and terminates options with --; if you see this from a hand-written codex exec, apply the argv rules above. Codex CLI 0.155.x did not change PTY handling or prompt forwarding, so do not reach for TTY workarounds on this symptom.
• Auth or model errors: stderr shows the Codex banner followed by an API error. Retry or fix credentials.
• TTY detachment: Codex CLI v0.124.0+ silently crashes when backgrounded without a TTY. codex-exec.sh auto-wraps with script(1), so this only applies to hand-written background launches.
• Codex session too short to produce a response
• Model returned empty response (retry)
• Profile instructions were rejected by an outdated Codex CLI (update Codex and retry)

Upgrade from AGENTS.md-injection releases

An interrupted run from an older release may have left an AGENTS.md symlink into codex-orchestrator/agents/ plus .AGENTS.md.codex-backup.<pid>. Inspect those paths and restore the matching backup once before parallel use. Keep the backup until the repository instructions are verified; current launchers deliberately do not guess among legacy backups.

Poor Results

• Narrow the task scope
• Provide more context in the prompt
• Try a different profile
• Use --model gpt-5.6-sol --reasoning max for complex tasks