| description | Launch Anthropic Claude as an independent agent for code review, verification, and reasoning. Uses the claude CLI with full file system access, or the API for pure reasoning tasks. Primarily for teams whose primary agent is Codex or Gemini and want a Claude read on the work. |
| metadata | {"github-path":"skills/claude-oracle","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"2901363c12772e3db35f9fa6ee420c24138afc06"} |
| name | claude-oracle |
Claude Oracle
Core Purpose
Launch Anthropic's Claude as an independent agent that can read the codebase, review diffs, and produce detailed analysis. The claude CLI runs non-interactively via -p (print mode) and can read, explore, and reason about code without modifying it.
Key property: claude -p runs as a separate process with zero knowledge of any other agent's current conversation. It reads the codebase cold — useful when your primary driver is Codex or Gemini and you want the Claude family's perspective as part of a model-diverse review.
When to Use
- Model-diverse review, non-Claude primary: You're running Codex or Gemini as your primary agent and want Claude to review the work. This is the main use case — symmetric with
codex-oracle and gemini-oracle.
- Independent second opinion: Get a Claude-family read without carrying context from your current session. Useful even when your primary is Claude if you want a cold read without the current conversation's framing (see caveat below).
- Pure reasoning: Complex analysis that doesn't need file access (uses API fallback).
- Architecture / design second opinion: Claude's reasoning is strong for system design critique.
Independence caveat
If your primary agent is already Claude, claude-oracle gives you a fresh Claude process but still the same model family. Different context, same priors. For truly independent review when Claude is your primary, prefer codex-oracle and gemini-oracle first. Reach for claude-oracle when you specifically want a clean Claude context (e.g. the current session has built up a biased framing you want to escape).
Prerequisites
claude CLI installed and authenticated. Verify with claude --version.
- For the API fallback (pure reasoning, no file access):
ANTHROPIC_API_KEY in the environment (e.g. exported from ~/.secrets/api-keys.sh or your shell rc).
If the CLI is missing or not authenticated, the skill fails loudly. Surface the prerequisite and stop — don't silently fall back to another oracle.
Two Modes
Blind Mode (default for review/verification)
Minimal prompt. Claude explores the codebase or diff and forms its own conclusions. Maximum independence.
claude -p "Review all uncommitted changes in this repository. Identify bugs, missing edge cases, and inconsistencies with the rest of the codebase. Cite file paths and line numbers." \
--permission-mode plan \
--output-format text 2>/dev/null
Use when: You want to catch what your primary agent missed. The less framing you provide, the more independent the review.
Directed Mode
Provide specific context and a focused question.
claude -p "Analyze the retry logic in src/queue/worker.ts. Are there paths where a failed job could be silently dropped without requeuing?" \
--permission-mode plan \
--output-format text 2>/dev/null
Use when: You have a specific concern and want a second reasoning pass from a fresh Claude context.
Invocation
Basic pattern
claude -p "YOUR TASK" --permission-mode plan --output-format text 2>/dev/null
Flags explained:
-p "..." — Non-interactive headless mode (print and exit). Required for skill use.--permission-mode plan — Read-only. Claude can read files and explore but cannot modify anything. Use this by default.--output-format text — Plain text output (vs json / stream-json).2>/dev/null — Suppress stderr noise.- Model selection: Default to omitting
--model. The CLI picks its default, which is the most reliable option. Only pass --model when the user explicitly asks. See Model Selection below.
Strict cold-context mode (maximum independence)
Use --bare to skip auto-loaded CLAUDE.md, hooks, plugins, and auto-memory. This is the strongest isolation — useful when the current working directory has an agent-tuned CLAUDE.md that would bias the review.
claude -p --bare \
"Review all uncommitted changes. Be a fresh reviewer with no prior context." \
--permission-mode plan \
--output-format text 2>/dev/null
Note: --bare forces auth to ANTHROPIC_API_KEY (or apiKeyHelper via --settings) — OAuth and keychain are not read. Make sure the env var is set before using --bare.
Including additional directories
claude -p "YOUR TASK" \
--permission-mode plan \
--add-dir /path/to/other/repo \
--output-format text 2>/dev/null
Piping content (pure text analysis, no file access)
printf '%s' "$CONTENT" | claude -p "Analyze the above for logical errors" \
--output-format text 2>/dev/null
API Fallback (no file access needed)
For pure reasoning tasks where Claude doesn't need to read the codebase:
<skill-dir>/scripts/call-anthropic.sh "YOUR PROMPT" [model] [thinking_budget]
Parameters:
prompt (required): The task.model (optional): Default claude-opus-4-7. See model guide below.thinking_budget (optional): Extended-thinking budget in tokens. Default 10000. Pass 0 to disable thinking. Minimum when enabled is 1024.
Model Selection
Via CLI (claude -p)
Default: omit --model and let the CLI pick. When overriding, aliases are safer than full IDs because the CLI resolves the latest version:
| Alias | Current Model | Best For |
|---|
| (default) | CLI's configured default | Most tasks |
opus | Claude Opus (latest) | Hardest reasoning, architecture, deep review |
sonnet | Claude Sonnet (latest) | Balanced speed + capability, most reviews |
haiku | Claude Haiku (latest) | Fast, cheap, shallow passes |
Full IDs work too. Current frontier IDs as of this skill's writing:
claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001.
Use them when you need reproducibility. Haiku 4.5 requires the dated suffix in the
Messages API; Opus 4.7 and Sonnet 4.6 accept the bare form. Check
https://docs.anthropic.com/en/docs/about-claude/models for currently-supported IDs
before relying on any specific value.
Via API Script
Default: claude-opus-4-7. The script passes the model name straight through to the Messages API, so any ID the API accepts will work.
Extended thinking (API script only)
Claude 4.x Opus and Sonnet support extended thinking — the model reasons internally before responding. Pass thinking_budget to control depth:
0 — Disabled. Fastest, cheapest.1024–4096 — Light reasoning. Quick analyses.10000 — Default. Good balance for review / reasoning tasks.32000+ — Deep reasoning. Complex architecture, critical decisions. Caveat: the API script uses synchronous curl (non-streaming). Very large thinking budgets (≳32k) can push total response time past Anthropic's non-streaming timeout window and produce partial or failed responses. For budgets above ~32k, prefer splitting the task, reducing the budget, or running the task through the claude -p CLI (which streams internally) instead of the API script.
Thinking tokens count toward output budget; the script sets max_tokens to budget + 16384 automatically to leave room for the actual answer.
Common Workflows
Review Uncommitted Work (Blind)
claude -p "Review all uncommitted changes in this repository. You are a fresh reviewer with no prior context. Identify:
- Bugs or logic errors
- Missing edge cases
- Inconsistencies with the rest of the codebase
- Anything that looks wrong or suspicious
Be specific — cite file paths and line numbers." \
--permission-mode plan \
--output-format text 2>/dev/null
Review a Branch Against Main
git diff main...HEAD | claude -p "Review the diff below. Identify bugs, missing edge cases, and security concerns. Cite specific lines." \
--output-format text 2>/dev/null
Precision Analysis of Specific Code
claude -p "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." \
--permission-mode plan \
--output-format text 2>/dev/null
Architecture Second Opinion
claude -p "Read the codebase architecture. Evaluate the data flow from GitHub API through to the UI. Identify structural issues, unnecessary coupling, or scalability concerns." \
--permission-mode plan \
--output-format text 2>/dev/null
Pure Reasoning (no file access)
<skill-dir>/scripts/call-anthropic.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)
" claude-opus-4-7 16000
Integration with Multi-Model Workflows
Claude Oracle is one of three peer CLI-based model oracles alongside codex-oracle and gemini-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 (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:
claude -p "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." \
--permission-mode plan \
--output-format text 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. When /verify selects claude-oracle (typically because the implementing agent is Codex or Gemini), pair it with --bare mode for the strongest isolation — skips auto-loaded CLAUDE.md and hooks so the review is genuinely cold-context.
Manual blind-review fallback
For quick, ad hoc cross-model reads outside the gate flow:
claude -p "Review all uncommitted changes. You are a fresh reviewer with no prior context. Cite file paths and line numbers." --permission-mode plan --output-format text 2>/dev/null
Use this when you don't need the prosecution-doc machinery.
Error Handling
claude not found: Install per https://docs.anthropic.com/en/docs/claude-code/quickstart.- Auth failure (CLI): Run
claude auth or start an interactive session once to authenticate.
ANTHROPIC_API_KEY not set (API script or --bare mode): Add to ~/.secrets/api-keys.sh: export ANTHROPIC_API_KEY='your-key-here'.- Empty response: May indicate the prompt was too vague or the model refused. Check the raw response with
--output-format json for the CLI, or re-run the API script (it prints the full response JSON on parse failure).
- Timeout on large codebases: Scope with
--add-dir to specific subdirectories rather than letting Claude wander the whole workspace, or pipe a pre-scoped diff via stdin.
- Model ID rejected (API script): You passed an ID the API doesn't recognize. Use an alias via the CLI (
--model opus), or check https://docs.anthropic.com/en/docs/about-claude/models for currently-supported IDs.
Important
- Don't leak the primary agent's framing in blind mode. Saying "Codex chose X because Y, is that right?" biases the review. Let Claude read the code and form its own view.
- Read-only by default. Always use
--permission-mode plan unless you have a specific reason to let Claude modify files.
- Review Claude's output critically. Even a fresh Claude is still Claude — same training family, similar blind spots. The independence comes from the cold-read subprocess, not a different model family. For real family-diverse review, use
codex-oracle and gemini-oracle.
- Never include secrets in API prompts. The CLI handles auth; the API script reads from environment variables.
