Claude-code-minoan codex-orchestrator

Spawn specialized OpenAI Codex CLI subagents for code review, debugging, architecture analysis, security audits, refactoring, and documentation via AGENTS.md persona injection (gpt-5.4, gpt-5.4-pro, gpt-5-mini). Triggers on 'delegate to Codex', 'Codex subagent', 'code review agent', 'security audit', 'refactor with Codex'.

install

source · Clone the upstream repo

git clone https://github.com/tdimino/claude-code-minoan

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/tdimino/claude-code-minoan "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/integration-automation/codex-orchestrator" ~/.claude/skills/tdimino-claude-code-minoan-codex-orchestrator && rm -rf "$T"

manifest: skills/integration-automation/codex-orchestrator/SKILL.md

source content

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 (injects Exa guide into AGENTS.md)
~/.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

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 (injects guide into AGENTS.md)
`--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)
`--resume`	Resume previous exec session (builder "continue" workflow)
`--with-mcp`	Keep global MCP servers enabled (disabled by default for speed)

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.4`	`high`
Planning	planner, architect	`gpt-5.4-pro`	`high`
Research	researcher	`gpt-5.4`	`medium`

Reasoning effort levels:

none

minimal

low

medium

high

xhigh

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

# Uses profile defaults (planner → gpt-5.4-pro + 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-mini

# 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.4 --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 reference
```
references/agents-md-format.md
```
- AGENTS.md syntax and best practices
```
references/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.4

gpt-5.4-pro

gpt-5-mini

gpt-5-nano

. Previous generation (

gpt-5.3-codex

gpt-5.3-codex-spark

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

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.4-pro
```
for complex tasks