Gemini

Gemini CLI

Second opinion, grounding, broad analysis, verification, code review, or autonomous task delegation using Google's Gemini CLI.

Model

Do NOT force a model with -m. Let auto mode handle routing — it picks the best available model as primary with built-in fallback for transient 429s. Forcing a model with -m disables this automatic fallback and will cause hard failures on rate limits.

# CORRECT — auto-routing with fallback
gemini -p "<PROMPT>" -y

# WRONG — disables fallback, will fail on 429s
gemini -m gemini-3.1-pro-preview -p "<PROMPT>" -y

Gemini's Strengths: Grounding & Broad Context

Gemini is not just another code reviewer. Its unique value is grounding — connecting code to the broader world:

• 1M token context: Can ingest entire codebases, not just snippets
• Web-connected: Can search for current docs, APIs, best practices, GitHub issues
• Broad perspective: Thinks differently from Claude and Codex — triangulates answers
• Research-oriented: Can look up papers, libraries, patterns before answering

When to Use Gemini (vs Codex)

Prompting for Grounding

When using Gemini for grounding, explicitly tell it to research:

Before answering, search for:
- Current best practices for [topic]
- Whether [library/pattern] is still recommended
- Any known issues or CVEs with [dependency]
- How other projects handle [problem]

Then ground your review in what you find.

Mode Selection

Choose mode based on the intent — is Claude providing context, or is Gemini doing its own work?

1. Quick Mode — Simple questions, short answers

For questions where Claude already has the answer context and just needs a second opinion.

Bash tool timeout: 120000ms

OUTPUT_FILE="~/.claude/subagent-results/gemini-output-$(date +%s).md"
ERROR_FILE="~/.claude/subagent-results/gemini-errors-$(date +%s).log"
gemini \
  -p "<PROMPT>" \
  -o text -y \
  > "$OUTPUT_FILE" 2>"$ERROR_FILE"
# Verify output
[ -s "$OUTPUT_FILE" ] || { echo "EMPTY OUTPUT — errors:"; cat "$ERROR_FILE"; }

2. Analysis Mode — Claude curates context, Gemini analyzes

When Claude has already read the code/docs and can provide a focused brief. Use this when Gemini does NOT need filesystem access — Claude is the context engineer.

Bash tool timeout: 300000ms

Step 1: Write a structured prompt file using the Write tool:

PROMPT_FILE="~/.claude/subagent-results/gemini-prompt-$(date +%s).md"
OUTPUT_FILE="~/.claude/subagent-results/gemini-output-$(date +%s).md"
ERROR_FILE="~/.claude/subagent-results/gemini-errors-$(date +%s).log"

Prompt template:

## Goal
[What we're building/fixing and WHY]

## Context
[Curated summary — architecture, relevant snippets, dependencies.
YOU decide what's relevant. Don't dump entire files.]

## What We Need
[Clear, numbered questions. Tell Gemini if it should search/research before answering.]

## Grounding Request (when applicable)
Before answering, look up: [specific things to verify against real-world state]

Step 2: Invoke with stdin + file output:

gemini \
  -p "Respond to the analysis request provided on stdin." \
  -o text -y \
  < "$PROMPT_FILE" \
  > "$OUTPUT_FILE" 2>"$ERROR_FILE"

Step 3: Verify output exists, then read with the Read tool:

[ -s "$OUTPUT_FILE" ] || { echo "EMPTY OUTPUT — errors:"; cat "$ERROR_FILE"; }

3. Delegated Mode — Gemini works autonomously

When Gemini needs to explore a codebase, analyze files, search the web, or do independent work. This gives Gemini full tool access in a project directory. Use when:

• User wants Gemini to explore and form its own opinion
• User wants Gemini to review code itself
• User wants Gemini to research, ground, or investigate
• User wants Gemini to implement something

Bash tool timeout: 600000ms. For tasks likely to exceed 10 minutes, use run_in_background: true on the Bash tool and check the output file later.

OUTPUT_FILE="~/.claude/subagent-results/gemini-output-$(date +%s).md"
ERROR_FILE="~/.claude/subagent-results/gemini-errors-$(date +%s).log"
cd /path/to/project && gemini \
  -p "<PROMPT>" \
  -o text -y \
  > "$OUTPUT_FILE" 2>"$ERROR_FILE"
# Verify output
[ -s "$OUTPUT_FILE" ] || { echo "EMPTY OUTPUT — errors:"; cat "$ERROR_FILE"; }

For multi-directory projects, use --include-directories:

gemini \
  --include-directories /path/to/other/dir \
  -p "<PROMPT>" \
  -o text -y \
  > "$OUTPUT_FILE" 2>"$ERROR_FILE"

No output constraints in delegated mode. Let Gemini produce whatever it needs. In delegated mode, Gemini can and should:

• Read files across the codebase
• Search the web for current docs and best practices
• Check GitHub for related issues or patterns
• Verify dependencies are current and secure
• Ground its analysis in real-world state

Choosing the Right Mode

Output Handling

ALWAYS redirect stdout to a file. Don't rely on inline capture for anything beyond quick mode.

• For Analysis Mode: Read the output file, summarize if presenting inline, or give full output if user wants detail.
• For Delegated Mode: Present the full output — Gemini may have done substantial work.
• ALWAYS verify output is non-empty after every invocation (all modes).
• If the Bash tool times out, the process was killed and output is lost. For Delegated tasks, re-run with run_in_background: true.

Error Handling

NEVER suppress stderr with 2>/dev/null. Always redirect to a timestamped error file.

• ALWAYS verify output is non-empty after every invocation (all modes): [ -s "$OUTPUT_FILE" ] || ...
• If output file is empty or missing, read the error file and report to user
• Common errors: auth expired (run gemini interactively to re-auth), model unavailable, rate limiting
• Don't retry silently — report the error, then retry with context
• Auto-routing handles 429s automatically — this is why we don't force -m

Context Engineering (Analysis Mode only)

When YOU are curating context for Gemini, be a good context engineer:

Don't artificially constrain output length unless the user wants brevity. If the question warrants a detailed answer, let Gemini be detailed.

Thinking / Reasoning

Gemini defaults to maximum reasoning depth (thinkingLevel: HIGH). No extra flags needed. Do NOT lower the thinking level.

Compaction Resilience

Output files are written to ~/.claude/subagent-results/ (persistent, not /tmp/). After context compaction:

• The output file still exists on disk — re-read it with the Read tool if needed
• CLAUDE.md compact instructions tell the compactor to preserve these file paths
• If you lose track of the file path, run: ls -t ~/.claude/subagent-results/gemini-output-* | head -1

Notes

• Gemini's unique value is grounding — connecting code to real-world state via search and broad context
• Best for: grounding, broad research, architecture validation, long-context analysis, ecosystem checks
• 1M token context window — can handle very large codebases
• Auth: uses Google OAuth (run gemini interactively once to authenticate)
• Gemini's -p flag appends to stdin, so use stdin for bulk context and -p for the directive
• Web-connected: can search docs, GitHub, papers — leverage this for grounding work