SKILL.md
Full skill instructions
name description
codex-oracle
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:
~ /.claude/skills/codex-oracle/scripts/check-codex.sh
If the script exits non-zero, display the error message and stop. Do not proceed without Codex CLI.
Configuration Defaults
Setting Default User Override
Model gpt-5.2 "use model X" or "with gpt-5.2"
Reasoning Dynamic (based on complexity) "use medium reasoning" or "with xhigh effort"
Sandbox read-only Not overridable (safety constraint)
Timeout 5 minutes minimum Estimate based on task complexity
Profile quiet (notify=[]) User opts into another profile or notifications
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:
Complexity Effort Examples
Simple low Single file review, syntax check, quick question
Moderate medium Multi-file review, focused feature planning, bug analysis
Complex high Architecture analysis, cross-cutting concerns, security audit
Maximum xhigh Large codebase planning, comprehensive design, deep reasoning
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
- Validate Prerequisites
Run the check script. On failure, report the installation instructions and abort.
- Determine Mode
Planning mode : User wants architecture, implementation approach, or design decisions
Review mode : User wants code analysis, bug detection, or improvement suggestions
- 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.
- Assess Complexity and Execute Codex
Before executing, assess task complexity to select appropriate reasoning effort:
Count files involved in the query
Evaluate scope (single module vs cross-cutting)
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.
- 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.
- Synthesize and Plan
After presenting Codex output:
Synthesize key insights from Codex analysis
Identify actionable items and critical decisions
If Codex's analysis presents multiple viable approaches or significant trade-offs , consider using AskUserQuestion to clarify user preferences before finalizing the plan
Write a structured plan to ~/.claude/plans/[plan-name].md
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
Error Response
Codex not installed Show installation instructions from check script
Codex timeout Inform user, suggest simpler query or lower reasoning
API rate limit Wait and retry, or inform user of limit
Empty response Retry once, then report failure
Usage Examples
Planning Request
User: "Ask Codex to plan how to add authentication to this app"
Validate Codex CLI available
Gather relevant codebase context
Assess complexity → auth spans multiple modules → high reasoning
Construct planning prompt with auth requirements
Execute Codex with gpt-5.2 and high
Present Codex's architecture recommendations
Synthesize into Claude plan format
Write to ~/.claude/plans/ and call ExitPlanMode
Code Review Request
User: "Have Codex review the changes in src/auth/"
Validate Codex CLI available
Read files in src/auth/ directory
Assess complexity → single directory, focused review → medium reasoning
Construct review prompt with file contents
Execute Codex review with medium
Present findings with file/line references
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)