gemini-oracle

description	Launch Gemini as an independent agent for codebase analysis, planning, and large-context synthesis. Uses the gemini CLI with full file system access.
metadata	{"github-path":"skills/gemini-oracle","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"9c65f97bfce668658dba0977f420cdcb52226cfa"}
name	gemini-oracle

Gemini Oracle

Core Purpose

Launch Google's Gemini as an independent agent that can read the codebase, explore files, and form its own conclusions. Gemini 3.1 Pro's 1M token context makes it exceptionally good at digesting entire codebases and producing structured analysis.

Key property: Gemini runs as a separate process with zero knowledge of the current Claude conversation. It reads the codebase cold and forms independent conclusions — different training data, different biases, different blind spots.

Prerequisites

• gemini CLI installed (npm install -g @google/gemini-cli, or Homebrew brew install gemini-cli — verify with which gemini).
• First-time auth: run gemini interactively once to sign in, then headless invocations work.

If gemini is not installed or not authenticated, the skill fails loudly — surface the prerequisite and stop. Don't silently fall back to a different oracle.

When to Use

• Model-diverse review: Get a non-Claude read on work before shipping. Pairs with codex-oracle and claude-oracle for a three-way cross-check.
• Session start: Digest codebase, identify what matters, produce a structured plan.
• Architecture analysis: Evaluate structure, dependencies, patterns across a large codebase.
• Planning: Create detailed implementation plans from complex requirements.
• Synthesis: Make sense of many files, docs, and context simultaneously.
• Independent verification: Get a genuinely independent read on work Claude has done.

Two Modes

Blind Mode (default for verification)

Minimal prompt. Gemini explores the codebase and forms its own conclusions. Maximum independence — no framing from Claude's perspective.

gemini -p "Review the recent changes in this repository. Identify any issues, missed edge cases, or concerns." \
  --approval-mode plan \
  -o text 2>/dev/null

Use when: You want to catch what Claude missed. The less context you provide, the more independent the analysis.

Directed Mode

Provide specific context and a focused question. Better for getting a second opinion on a particular concern.

gemini -p "Analyze the caching strategy in src/api/. Evaluate whether the TTL approach handles cache invalidation correctly under concurrent writes." \
  --approval-mode plan \
  -o text 2>/dev/null

Use when: You have a specific question and want a different model family's take on it.

Invocation

Basic pattern

gemini -p "YOUR TASK" --approval-mode plan -o text 2>/dev/null

Flags explained:

• -p "..." — Non-interactive headless mode. Required for skill use.
• --approval-mode plan — Read-only. Gemini can read files and explore but cannot modify anything. Use this by default.
• -o text — Plain text output (no formatting artifacts).
• 2>/dev/null — Suppress stderr noise (deprecation warnings, etc.).
• Model selection: Do NOT pass -m unless the user explicitly asks for a specific model. The CLI resolves its own default, which is the only reliably-available model on the installed CLI. Hardcoding a model ID tends to break when Google rotates aliases. See Model Selection below.

Including additional directories

gemini -p "YOUR TASK" \
  --approval-mode plan \
  --include-directories /path/to/other/repo \
  -o text 2>/dev/null

Piping content (for pure text analysis without file access)

printf '%s' "$CONTENT" | gemini -p "Analyze the above for logical errors" \
  -o text 2>/dev/null

Stdin content is prepended to the -p prompt.

Model Selection

Default: omit -m entirely and let the CLI pick its own default model. This is the only reliably-available configuration. The installed gemini CLI resolves its own default (typically the current Pro-class model), and explicit model IDs frequently break when Google rotates aliases (e.g. gemini-3.1-pro is rejected with ModelNotFoundError, and preview aliases return RESOURCE_EXHAUSTED 429s).

Only pass -m <model-id> if the user has a specific reason to override (e.g. they asked for a faster/cheaper flash-class model, or they are testing a specific model) and they supply the exact ID. Do not guess model IDs.

If you need to discover currently-available models, run gemini --help or check the gemini-cli release notes — don't guess.

Common Workflows

Session Start — Codebase Orientation

gemini -p "Read this codebase thoroughly. Produce:
1. A summary of the architecture and key components
2. The current state of the project (what's done, what's in progress)
3. Key patterns and conventions used
4. Areas of complexity or technical debt
5. A recommended plan for the next session of work based on what you see" \
  --approval-mode plan \
  -o text 2>/dev/null

Implementation Planning

gemini -p "Read the codebase and the requirements below. Create a detailed, step-by-step implementation plan that accounts for existing patterns, dependencies, and edge cases. Be thorough — the plan should be specific enough that a developer can follow it without making assumptions.

Requirements:
[PASTE REQUIREMENTS HERE]" \
  --approval-mode plan \
  -o text 2>/dev/null

Independent Review (Blind)

gemini -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." \
  --approval-mode plan \
  -o text 2>/dev/null

Integration with Multi-Model Workflows

Gemini Oracle is one of three peer CLI-based model oracles alongside codex-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 (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:

gemini -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." \
  --approval-mode plan \
  -o 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 — same protocol, different pretraining, genuinely different blind spots. Gemini's large-context strength is especially useful when the payload requires the reviewer to hold the whole codebase in mind.

Manual blind-review fallback

For quick, ad hoc cross-model reads outside the gate flow:

gemini -p "Review all uncommitted changes in this repository. You are a fresh reviewer with no prior context. Be specific — cite file paths and line numbers." --approval-mode plan -o text 2>/dev/null

Use this when you don't need the prosecution-doc machinery.

Error Handling

• gemini not found: Run which gemini to check installation. Install via npm: npm install -g @google/gemini-cli (or Homebrew: brew install gemini-cli).
• Auth failure: Run gemini interactively once to authenticate, then retry.
• Empty output: May indicate the model couldn't access files or the prompt was too vague. Try a more specific prompt.
• Timeout on large codebases: Narrow the prompt's scope. Name specific files or subdirectories in the prompt, or cd into a subdirectory before invoking gemini so the workspace starts smaller. Note that --include-directories adds directories to the workspace — it cannot shrink scope.
• ModelNotFoundError: Requested entity was not found / model not found / 404: You passed -m <model-id> with a model the installed CLI can't resolve (e.g. older docs referenced gemini-3.1-pro, which current CLIs reject). Fix: remove the -m flag entirely and let the CLI use its default. Rerun the exact same command minus -m <anything>.
• RESOURCE_EXHAUSTED / 429 / capacity exhausted: You passed -m pointing at a preview/alpha model alias (e.g. -pro-preview) whose quota is saturated. Fix: remove the -m flag so the CLI routes to its default stable model, which has separate capacity. Do not retry-loop on the exhausted alias.
• General rule: If a gemini invocation fails with anything model-related, the first remediation step is always: strip -m <model> from the command. Only reintroduce a specific model ID when the user has explicitly asked for one and confirmed the ID exists on the current CLI.

Important

• Don't leak the primary agent's framing in blind mode. The value of independence comes from Gemini forming its own conclusions. Saying "Claude wrote X and thinks Y, check it" defeats the purpose.
• Read-only by default. Always use --approval-mode plan unless you have a specific reason to let Gemini modify files.
• Review Gemini's output critically. Different model, different blind spots. Synthesize findings, don't blindly adopt them.