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:

~/.claude/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.

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 (architecture analysis, large codebase planning): 15 minutes (900000ms)

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

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:

# Select EFFORT based on complexity assessment (low/medium/high/xhigh)
# Bash tool timeout: 300000-900000ms based on complexity
codex exec \
  -m "${MODEL:-gpt-5.2}" \
  -c "model_reasoning_effort=${EFFORT}" \
  --profile "${CODEX_PROFILE:-quiet}" \
  -s read-only \
  --skip-git-repo-check \
  2>/dev/null <<'EOF' > /tmp/codex-analysis.txt
[constructed prompt]
EOF

Important flags:

• -m: Model selection
• -c model_reasoning_effort=: Reasoning depth (low/medium/high/xhigh) — select based on Reasoning Effort Guidelines
• --profile quiet: Default for this skill (suppresses notify hooks); change only if the user explicitly wants another profile/notifications
• -s read-only: Prevents any file modifications (non-negotiable)
• --skip-git-repo-check: Works outside git repositories
• 2>/dev/null: Suppresses thinking tokens from 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

Read the analysis from the temp file and display to the user with clear attribution:

cat /tmp/codex-analysis.txt

Format the output with clear attribution:

## Codex Analysis

[Codex output from /tmp/codex-analysis.txt]

---
Model: gpt-5.2 | 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 to ~/.claude/plans/[plan-name].md
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

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 and high
6. Present Codex's architecture recommendations
7. Synthesize into Claude plan format
8. Write to ~/.claude/plans/ and call ExitPlanMode

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)