name: oracle-codex
argument-hint: '[--model] [--reasoning]'
context: fork
user-invocable: false
description: This skill should be used when the user asks to "use Codex", "ask Codex", "consult Codex", "Codex review", "use GPT for planning", "ask GPT to review", "get GPT's opinion", "what does GPT think", "second opinion on code", "consult the oracle", "ask the oracle", or mentions using an AI oracle for planning or code review. NOT for implementation tasks.

Codex Oracle

Use OpenAI Codex CLI as a planning oracle and code reviewer. Codex provides analysis and recommendations; Claude synthesizes and presents to the user.

Critical: This skill is for planning and review ONLY. Never use Codex to implement changes.

Prerequisites

Before invoking Codex, validate availability:

~/.agents/skills/oracle-codex/scripts/check-codex.sh

If the script exits non-zero, display the error message and stop. Do not proceed without Codex CLI.

For codex exec, prefer the wrapper script (handles flag compatibility and surfaces errors):

~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh

Configuration Defaults

Timeout Guidelines

When invoking codex exec via the Bash tool, always set an appropriate timeout:

• Minimum: 5 minutes (300000ms) for any Codex operation
• Simple queries (single file review, focused question): 5 minutes (300000ms)
• Moderate complexity (multi-file review, feature planning): 10 minutes (600000ms)
• High complexity (high reasoning): 15 minutes minimum (900000ms)
• Maximum complexity (xhigh reasoning): 20 minutes (1200000ms)

Reasoning Effort Guidelines

Select reasoning effort based on task complexity:

Selection heuristics:

• low: Task involves \<3 files, simple question, or quick validation
• medium: Task involves 3-10 files or requires moderate analysis
• high: Task spans multiple modules or requires architectural thinking
• xhigh: Task requires comprehensive codebase understanding or critical decisions

For available models and reasoning levels, consult references/codex-flags.md.

Workflow

1. Validate Prerequisites

Run the check script. On failure, report the installation instructions and abort.

2. Determine Mode

• Planning mode: User wants architecture, implementation approach, or design decisions
• Review mode: User wants code analysis, bug detection, or improvement suggestions
• Preferred: Use codex review subcommand (simpler, see below)

2b. Quick Review with codex review

For code review requests, prefer the dedicated codex review subcommand:

# Review uncommitted changes
codex review --uncommitted

# Review changes against a base branch
codex review --base main

# Review a specific commit
codex review --commit <SHA>

# With custom focus instructions
codex review --base main "Focus on security and error handling"

Important: Before using --uncommitted, verify there are changes to review:

# Check for uncommitted changes (staged or unstaged)
if git diff --quiet && git diff --cached --quiet; then
  echo "No uncommitted changes to review"
  # Fall back to --base or inform user
fi

If there are no uncommitted changes, either:

1. Use --base <branch> to review committed changes against a branch
2. Inform the user there's nothing to review

This is simpler than codex exec for review workflows. Fall back to codex exec when more control is needed (custom prompts, specific reasoning effort, output redirection).

3. Construct Prompt

Build a focused prompt for Codex based on mode:

Planning prompt template:

Analyze this codebase and provide a detailed implementation plan for: [user request]

Focus on:
- Architecture decisions and trade-offs
- Files to create or modify
- Implementation sequence
- Potential risks or blockers

Do NOT implement anything. Provide analysis and recommendations only.

Review prompt template:

Review the following code for:
- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Code quality and maintainability
- Adherence to best practices

[code or file paths]

Provide specific, actionable feedback with file locations and line references.

4. Assess Complexity and Execute Codex

Before executing, assess task complexity to select appropriate reasoning effort:

1. Count files involved in the query
2. Evaluate scope (single module vs cross-cutting)
3. Consider depth (surface review vs architectural analysis)

Use HEREDOC syntax for safe prompt handling. Always use the Bash tool's timeout parameter (minimum 300000ms / 5 minutes).

Redirect output to a temp file to avoid context bloat and race conditions.

Step 1: Generate a unique temp file path using $RANDOM for randomness:

CODEX_OUTPUT="/tmp/codex-${RANDOM}${RANDOM}.txt"

Step 2: Execute Codex via the wrapper (detects supported flags and surfaces stderr):

# Select EFFORT based on complexity assessment (low/medium/high/xhigh)
# Bash tool timeout: 5-20 minutes based on complexity
MODEL="${MODEL:-gpt-5.2-codex}" \
EFFORT="${EFFORT}" \
CODEX_OUTPUT="$CODEX_OUTPUT" \
~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh <<'EOF'
[constructed prompt]
EOF

Important flags:

• -m: Model selection
• -c model_reasoning_effort=: Reasoning depth (low/medium/high/xhigh) — select based on Reasoning Effort Guidelines
• -s read-only: Prevents any file modifications (non-negotiable)
• --skip-git-repo-check: Works outside git repositories (exec-specific)
• -o <file>: Write output to file (cleaner than shell redirection)
• --search: Enable web search for queries needing current information (optional)
• 2>/dev/null: Suppresses stderr (progress/thinking output)

Bash tool timeout: Estimate based on task complexity (see Timeout Guidelines above). Never use the default 2-minute timeout for Codex operations.

5. Present Codex Output

Step 3: Read the analysis from the temp file and display to the user:

cat "$CODEX_OUTPUT"

Format the output with clear attribution:

## Codex Analysis

[Codex output from the temp file]

---
Model: gpt-5.2-codex | Reasoning: [selected effort level]

For very large outputs (>5000 lines), summarize key sections rather than displaying everything.

6. Synthesize and Plan

After presenting Codex output:

1. Synthesize key insights from Codex analysis
2. Identify actionable items and critical decisions
3. If Codex's analysis presents multiple viable approaches or significant trade-offs, consider using AskUserQuestion to clarify user preferences before finalizing the plan
4. Write a structured plan
5. Call ExitPlanMode to present the plan for user approval

When to use AskUserQuestion:

• Codex proposes multiple architectures with different trade-offs
• Technology or library choices need user input
• Scope decisions (minimal vs comprehensive) are ambiguous

Skip clarification when:

• Codex's recommendations are clear and unambiguous
• User's original request already specified preferences
• Only one viable approach exists

Error Handling

The check script returns specific exit codes:

The codex review command returns:

The codex exec command returns:

Runtime errors:

Usage Examples

Planning Request

User: "Ask Codex to plan how to add authentication to this app"

1. Validate Codex CLI available
2. Gather relevant codebase context
3. Assess complexity → auth spans multiple modules → high reasoning
4. Construct planning prompt with auth requirements
5. Execute Codex with gpt-5.2-codex and high
6. Present Codex's architecture recommendations
7. Synthesize into Claude plan format

Code Review Request

User: "Have Codex review the changes in src/auth/"

1. Validate Codex CLI available
2. Read files in src/auth/ directory
3. Assess complexity → single directory, focused review → medium reasoning
4. Construct review prompt with file contents
5. Execute Codex review with medium
6. Present findings with file/line references
7. Summarize critical issues and recommendations

Additional Resources

Reference Files

• references/codex-flags.md - Complete model and flag documentation

Scripts

• scripts/check-codex.sh - Prerequisite validation (run before any Codex command)