| description | Launch OpenAI Codex/GPT as an independent agent for code review, verification, and precision analysis. Uses the codex CLI with full file system access, or the API for pure reasoning tasks. |
| metadata | {"github-path":"skills/codex-oracle","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"7dbb6d452598ed35afcdb55affda136bd1f32f0b"} |
| name | codex-oracle |
Codex Oracle
Core Purpose
Launch OpenAI's models as an independent agent that can read the codebase, review diffs, and produce precise analysis. The codex CLI provides purpose-built commands for code review and general agentic tasks.
Key property: Codex runs as a separate process with zero knowledge of the current Claude conversation. It reads the codebase cold — different training data, different failure modes, different blind spots from both Claude and Gemini.
Prerequisites
codex CLI installed: npm install -g @openai/codex, then codex login once.- For the API fallback (pure reasoning, no file access):
OPENAI_API_KEY in the
environment (e.g. exported from ~/.secrets/api-keys.sh or your shell rc).
If the CLI is missing, the skill fails loudly — don't try to fake a review with
another tool. Surface the prerequisite and stop.
When to Use
- Model-diverse review: Get a non-Claude read on work before shipping. Pairs with
gemini-oracle and claude-oracle for a three-way cross-check.
- Code review: Built-in
codex review command reviews diffs with high precision.
- Independent verification: Get a genuinely independent read on work Claude has done.
- Precision analysis: Detailed, rigorous analysis of specific code or logic.
- Second opinion: Different model family's perspective on architecture, bugs, or approach.
- Pure reasoning: Complex analysis that doesn't need file access (uses API fallback).
Two Modes
Blind Mode (default for review/verification)
Minimal prompt. Codex explores the codebase or diff and forms its own conclusions. Maximum independence.
codex review --uncommitted 2>/dev/null
or
codex exec "Review this codebase for bugs, missed edge cases, and security issues. Be specific." -m gpt-5.4 2>/dev/null
Use when: You want to catch what Claude missed. The less framing you provide, the more independent the review.
Directed Mode
Provide specific context and a focused question.
codex exec "Analyze the error handling in server/apiMiddleware.ts. Are there request paths that could hang without a timeout?" -m gpt-5.4 2>/dev/null
Use when: You have a specific concern and want a different model family's take.
Invocation
Code Review (primary use case)
The codex review command is purpose-built for reviewing code changes.
codex review --uncommitted 2>/dev/null
codex review --base main 2>/dev/null
codex review --commit abc123 2>/dev/null
codex review --uncommitted "Focus on security vulnerabilities and race conditions" 2>/dev/null
codex review --uncommitted -m gpt-5.4 2>/dev/null
General Agentic Tasks
codex exec "YOUR TASK" -m gpt-5.4 2>/dev/null
echo "YOUR TASK" | codex exec - -m gpt-5.4 2>/dev/null
API Fallback (no file access needed)
For pure reasoning tasks where Codex doesn't need to read the codebase, use the API script directly:
<skill-dir>/scripts/call-openai.sh "YOUR PROMPT" [model] [reasoning_effort]
Parameters:
prompt (required): The taskmodel (optional): Default gpt-5.4. See model guide below.reasoning_effort (optional): high (default). Options: xhigh, high, medium, low, none
Model Selection
Via CLI (codex exec / codex review)
| Model | Best For | Speed |
|---|
gpt-5.4 | Most capable, coding + reasoning + computer use (DEFAULT) | Medium |
gpt-5.4-pro | Premium tier, highest capability | Slow |
o3 | Deep reasoning, complex planning | Slow |
Via API Script (reasoning tasks)
| Model | Best For | Speed | Cost |
|---|
gpt-5.4 | Most capable frontier model (DEFAULT) | Medium | High |
gpt-5.4-pro | Premium tier, highest capability | Slow | High |
gpt-5.3-codex | Specialized agentic coding | Medium | High |
gpt-5.3-codex-spark | Fast real-time coding (1000+ tok/s) | Fast | Medium |
o3 | Deep reasoning | Slow | High |
gpt-4o | Quick tasks, low cost | Fast | Low |
Reasoning Effort (API script only, GPT-5.x and o-series)
xhigh: Maximum depth. Critical decisions, complex architecture. (GPT-5.x only)high: Deep reasoning. Default.medium: Balanced.low: Quick answers.none: No extended reasoning.
Common Workflows
Review Uncommitted Work (Blind)
codex review --uncommitted 2>/dev/null
Simple. Codex sees the diff cold and reports what it finds. This is the highest-value pattern — a genuinely independent review from a different model family.
Review a Branch
codex review --base main 2>/dev/null
Reviews everything on the current branch vs main.
Precision Analysis of Specific Code
codex exec "Read src/api/readiness.ts and its tests. Verify that every edge case in the scoring logic is covered. List any inputs that would produce incorrect scores." -m gpt-5.4 2>/dev/null
Architecture Second Opinion
codex exec "Read the codebase architecture. Evaluate the data flow from GitHub API through to the UI. Identify any structural issues, unnecessary coupling, or scalability concerns." -m gpt-5.4 2>/dev/null
Pure Reasoning (no file access)
<skill-dir>/scripts/call-openai.sh "
## Task
Evaluate these two approaches to cache invalidation and recommend which is better for our constraints.
## Approach A
[description]
## Approach B
[description]
## Constraints
- 10k req/s, 90% reads
- Must handle concurrent writes
- Eventual consistency acceptable (< 5s)
" gpt-5.4 high
Integration with Multi-Model Workflows
Codex Oracle is one of three peer CLI-based model oracles alongside gemini-oracle and claude-oracle. Each launches a different model family as an independent process.
For gate-level cross-model verification, use /verify
/verify is the single entry point for gate-level cross-model review. It owns the pairing rule (which oracle to pick based on the implementing agent's family), writes the prosecution doc, and handles the fix-and-re-review loop. Do not invoke this oracle directly from a gate flow — call /verify and it will pick and invoke the right oracle.
The pairing table lives inside /verify. It is not duplicated here.
Composing with in-repo adversarial skills
When you invoke this oracle (either directly for an ad hoc cross-model check, or indirectly via /verify), the highest-signal prompt pattern is to hand it a specific in-repo skill as the checklist:
codex exec "Read the full text of .agents/skills/trade-path-audit/SKILL.md in the current repo and follow that protocol on the diff between main and HEAD. Produce the report format the skill specifies. Do not invent your own checklist — use the skill's." -m gpt-5.4 2>/dev/null
Common in-repo payloads:
/adversarial-verifier — Chain-of-Verification methodology with Saboteur / New Hire / Security Auditor personas./strategy-verification — scoring / statistical verification against replay integrity, capital adequacy, determinism./trade-path-audit — comprehensive retrofit audit.adversarial-trading.md — domain-specific trading attack checklist.
This pattern keeps the methodology reproducible across model families — same protocol, different pretraining, genuinely different blind spots.
Manual blind-review fallback
For quick, ad hoc cross-model reads outside the gate flow, the simplest pattern is still:
codex review --uncommitted 2>/dev/null
Codex sees the diff cold and reports what it finds. Use this when you don't need the prosecution-doc machinery.
Error Handling
codex not found: Install via npm install -g @openai/codex or check OpenAI's docs.OPENAI_API_KEY not set (API script): Add to ~/.secrets/api-keys.sh: export OPENAI_API_KEY='your-key-here'- Auth failure (CLI): Run
codex login to authenticate.
- Empty response: May indicate rate limiting or the prompt was too vague. Check model availability.
- Timeout: For large codebases, give Codex a more focused scope rather than "review everything."
Important
- Don't leak the primary agent's framing in blind mode. The value is independence. Saying "Claude chose X because Y, is that right?" biases the review. Just let Codex read the code and form its own view.
codex review is the primary tool for code review. Don't craft manual review prompts when the built-in command exists.- Review Codex's output critically. Different model, different blind spots. Synthesize, don't blindly adopt.
- Never include secrets in API prompts. The CLI handles auth; the API script reads from environment variables.
