oracle-codex
npx machina-cli add skill PaulRBerg/agent-skills/oracle-codex --openclawCodex Oracle
Use OpenAI Codex CLI as a read-only oracle — planning, review, and analysis only. Codex provides its perspective; you synthesize and present results to the user.
Sandbox is always read-only. Codex must never implement changes.
Arguments
Parse $ARGUMENTS for:
- query — the main question or task (everything not a flag). Required — if empty, tell the user to provide a query and stop.
--reasoning <level>— override reasoning effort (low,medium,high,xhigh). Optional; default is auto-selected based on complexity.
Prerequisites
Run the check script before any Codex invocation:
scripts/check-codex.sh
If it exits non-zero, display the error and stop. Use the wrapper for all codex exec calls:
scripts/run-codex-exec.sh
Configuration
| Setting | Default | Override |
|---|---|---|
| Model | gpt-5.3-codex | Allowlist only (see references/codex-flags.md) |
| Reasoning | Auto | --reasoning <level> or user prose |
| Sandbox | read-only | Not overridable |
Reasoning Effort
| Complexity | Effort | Timeout | Criteria |
|---|---|---|---|
| Simple | low | 300000ms | <3 files, quick question |
| Moderate | medium | 300000ms | 3–10 files, focused analysis |
| Complex | high | 600000ms | Multi-module, architectural thinking |
| Maximum | xhigh | 600000ms | Full codebase, critical decisions |
For xhigh tasks that may exceed 10 minutes, use run_in_background: true on the Bash tool and set CODEX_OUTPUT so you can read the output later.
See references/codex-flags.md for full flag documentation.
Workflow
1. Parse and Validate
- Parse
$ARGUMENTSfor query and--reasoning - Run
scripts/check-codex.sh— abort on failure - Assess complexity to select reasoning effort (unless overridden)
2. Construct Prompt
Build a focused prompt from the user's query and any relevant context (diffs, file contents, prior conversation). Keep it direct — state what you want Codex to analyze and what kind of output you need. Do not implement; request analysis and recommendations only.
3. Execute
Invoke via the wrapper with HEREDOC. Set the Bash tool timeout per the reasoning effort table above.
EFFORT="<effort>" \
CODEX_OUTPUT="/tmp/codex-${RANDOM}${RANDOM}.txt" \
scripts/run-codex-exec.sh <<'EOF'
[constructed prompt]
EOF
For xhigh, consider run_in_background: true on the Bash tool call, then read CODEX_OUTPUT when done.
4. Present Results
Read the output file and present with attribution:
## Codex Analysis
[Codex output — summarize if >200 lines]
---
Model: gpt-5.3-codex | Reasoning: [effort level]
Synthesize key insights and actionable items for the user.
Source
git clone https://github.com/PaulRBerg/agent-skills/blob/main/skills/oracle-codex/SKILL.mdView on GitHub Overview
This skill uses the OpenAI Codex CLI as a read-only oracle for planning, review, and analysis. It never implements changes; Codex provides perspective and rationale which you synthesize into actionable insights.
How This Skill Works
The skill parses a required query and an optional --reasoning level, runs a pre-check script, and selects a reasoning effort based on complexity. It then constructs a focused prompt and invokes Codex via the provided wrapper, returning analyzed output that you translate into recommendations for the user.
When to Use It
- When you want a second opinion on code or design without making changes
- When planning or reviewing code, architecture, or diffs for guidance only
- When you need structured analysis and rationale from Codex before implementation
- When you want an external perspective on potential risks and trade-offs
- When asked to consult an AI oracle for planning or code review, not for coding tasks
Quick Start
- Step 1: Ensure prerequisites and run the codex check script
- Step 2: Construct your query and optional --reasoning level, then invoke the wrapper with a focused prompt
- Step 3: Read the Codex Analysis output and synthesize key insights and recommendations
Best Practices
- Provide clear, scoped queries (e.g., focus on a function, module, or design decision)
- Attach relevant context such as diffs, file contents, or prior discussion to the query
- Use --reasoning <level> to control depth or let the tool auto-select based on complexity
- Treat Codex output as guidance; do not rely on it to implement changes
- Review Codex results and surface key insights before applying changes manually
Example Use Cases
- Review the algorithm design in src/Algorithms/NodeSort.cpp for efficiency concerns
- Plan the next steps for refactoring module auth in a read-only review
- Analyze potential performance bottlenecks in function computeResults in service.go
- Ask for a second opinion on the architecture proposed in PR #123
- Outline risks and trade-offs of adopting a microservices approach in the roadmap
