codex-orchestrator

# 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: ```bash ~/.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: ```bash # 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: ```bash ~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh <profile> "<prompt>" ``` Examples: ```bash # 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. ```bash ~/.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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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: ```markdown --- 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 ```bash # 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