Oracle

Delegate deep analysis to Codex CLI — launch it with a clear question, wait for it to finish, then present the results. Codex runs in a read-only sandbox with full codebase access, so it gathers its own context.

Prerequisites

Codex CLI (required): Install with npm i -g @openai/codex, authenticate with codex login

If Codex CLI is not installed, stop and tell the user to install it.

When to Use

Architecture analysis and design decisions
Debugging elusive or complex bugs
Impact assessment of proposed changes
Security reasoning and threat modeling
Refactoring strategy evaluation
Trade-off analysis between approaches
Complex "why" or "how" questions about a codebase

When NOT to Use

Simple factual questions (just answer directly)
Code generation tasks (just write the code)
Code review (use council-review instead)
Tasks that require file modifications (oracle is read-only analysis)

Workflow

Do not read script source code. Run scripts directly and use --help for usage.

Step 1: Formulate Question

Codex CLI has full read access to the codebase and can explore files, grep code, and web search on its own. Your job is to craft a clear, specific question — not to gather context for it.

Understand the user's question and what they need analyzed.
Formulate a clear, specific question that captures the user's intent — include relevant file paths, function names, or architectural areas to point Codex in the right direction.
Optionally use --context-file for truly external context that Codex cannot access on its own (e.g., user-provided files outside the repo, paste content).

Step 2: Run Codex

Scripts are in scripts/ relative to this skill's directory. Run <script> --help for full usage.

Launch scripts/codex-oracle.py as a background Bash task (run_in_background: true). Codex CLI may take up to 30 minutes.

python3 scripts/codex-oracle.py --question "..." --context-file path1 --context-file path2 [--focus text] [--dry-run]

After launching the background task, end your response immediately and wait. Do not poll, read output files, or check process status. You will be notified automatically when Codex completes.

Step 3: Present Results

Use the Read tool on the output-file path from the completion notification to retrieve the Codex analysis.
Present the results to the user — use your own judgment on formatting and what to highlight.

Rules

Do not start your own parallel analysis while Codex runs — Codex is the analyst. Your role is to formulate the question, launch Codex, and present the results.
Wait for Codex to complete before presenting results — the oracle's value depends on Codex's deep reasoning output.
Organize findings by theme — group related insights together, not by severity alone. Structure adapts to question type (architecture -> components/trade-offs, bug -> root cause hypotheses, security -> threat model, etc.).
Never use TaskOutput for background tasks — TaskOutput cannot find background Bash task IDs and will fail. Use the Read tool on the output-file path from the completion notification instead.
Do not poll or probe background tasks — Do not read output files, check process status, or run any commands while waiting. End your response after launching. You will be notified automatically when Codex completes.
Always use the wrapper script for Codex — do not call codex CLI directly, because the script sets the correct model and read-only mode.