diegosouzapw Codex Orchestrator
Spawn specialized Codex CLI subagents for focused development tasks. Each profile injects a custom AGENTS.md persona that shapes the agent's behavior, focus areas, and output format.
Architecture
Claude Code (orchestrator)
↓ invokes skill
codex-orchestrator scripts
↓ spawns via Bash
Codex CLI with AGENTS.md
↓ 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) |
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"
# Full-auto mode (no approval prompts)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Fix all lint errors" --full-auto
# 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"
# 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"
# Research with Exa web search (falls back to built-in if Exa unavailable)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React Server Component patterns?" --web-search
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)
Creation Tasks
- architect for design decisions
- builder for new feature implementation
- docs for documentation
- refactor for implementation improvements
- planner for multi-hour implementation plans
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" --full-auto
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"
Script Options
codex-exec.sh Options
| Option | Description |
|---|---|
--model <model> |
Override model (default: per-profile, see below) |
--reasoning <level> |
Override reasoning effort: minimal, low, medium, high, xhigh |
--sandbox <mode> |
read-only, workspace-write, danger-full-access |
--full-auto |
Skip approval prompts |
--web-search |
Enable Exa web search (built-in fallback if Exa unavailable) |
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.3-codex |
xhigh |
| Planning | planner, architect, researcher | gpt-5.2 |
xhigh |
Reasoning effort levels: minimal < low < medium < high < xhigh
# Uses profile defaults (builder → gpt-5.3-codex + xhigh)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement auth module"
# Uses profile defaults (planner → gpt-5.2 + xhigh)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching"
# Override model only
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Style check" --model gpt-5.3-codex-spark
# 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.3-codex --reasoning high
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 referencereferences/agents-md-format.md- AGENTS.md syntax and best practicesreferences/subagent-patterns.md- Delegation patterns and examples
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: gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2.
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
Check profile exists:
ls ~/.claude/skills/codex-orchestrator/agents/
Poor Results
- Narrow the task scope
- Provide more context in the prompt
- Try a different profile
- Use
--model gpt-5.3-codexfor complex tasks