claude-oracle

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.
  • Install: see https://docs.anthropic.com/en/docs/claude-code/quickstart
  • First-time auth: run claude auth or start an interactive session once.
• 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:

# Resolves relative to the skill install location.
# Project install:  .claude/skills/claude-oracle/scripts/call-anthropic.sh
# Global install:   ~/.claude/skills/claude-oracle/scripts/call-anthropic.sh
<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.