gemini

name

gemini

description

Use Google Gemini CLI for second opinions, grounding, broad analysis, verification, code review, or delegated autonomous tasks. Triggers when user says "use gemini", "ask gemini", "gemini check", "double check with gemini", "verify with gemini", "gemini analyze", "gemini review", "gemini implement", "have gemini do", "what does Gemini think", "Google's take", "cross-check with gemini", "ground this", or wants an alternative AI perspective. Gemini's 1M token context and web-connected tools make it especially strong for grounding work in reality, large-codebase analysis, and broad research. See also: the Codex skill for code-heavy tasks.

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)

Task	Use Gemini	Use Codex
"Is our approach standard?"	Yes — can search for patterns	No
"Are we using this library correctly?"	Yes — can check current docs	Maybe
"Review this code for bugs"	Either	Preferred
"What does the ecosystem look like?"	Yes — broad research	No
"Implement this feature"	Either	Preferred
"Validate our architecture against best practices"	Yes — grounding	Maybe
"Find security vulnerabilities"	Either	Preferred

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

Signal	Mode	Why
"Ask gemini about X" + Claude already has context	Analysis	Claude curates, Gemini analyzes. Efficient.
"Have gemini review the repo"	Delegated	Gemini needs to read files itself.
"Quick question for gemini"	Quick	Inline, fast, minimal.
"Get gemini's opinion on this architecture" + code already explored	Analysis	Claude summarizes what it knows.
"Have gemini explore and analyze this project"	Delegated	Gemini does its own exploration.
"Ground this in current best practices"	Delegated	Gemini needs web access to research.
"Use gemini to implement X"	Delegated	Gemini needs write access.

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:

Context Type	Strategy
Architecture	Summarize in your own words, don't paste READMEs
Code	Only relevant snippets — hot paths, the specific functions under discussion
Dependencies	Names and versions, not full package.json
Question	Numbered, specific, with enough context to answer without filesystem access
Grounding	Tell Gemini what to look up/verify against current state

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