gemini-cli-integration

name	gemini-cli-integration
description	Comprehensive guide for integrating Gemini CLI as research assistant. Use when you need to delegate research to Gemini, understand its capabilities vs Claude's, or determine the right tool for a task.

Gemini CLI Integration

Position Gemini CLI as Claude's research assistant - delegate when you need web-grounded information, codebase investigation, or sophisticated reasoning that benefits from Google Search backing.

Core Principle: Division of Labor

┌─────────────────────┐         ┌──────────────────────┐
│   GEMINI CLI        │         │   CLAUDE CODE        │
│   Research Wing     │────────>│   Implementation     │
└─────────────────────┘         └──────────────────────┘

Gemini: Investigate               Claude: Execute
- Web-grounded research          - File operations
- Codebase analysis              - Code edits
- Current docs lookup            - Following patterns
- Sophisticated reasoning        - Agent orchestration
- Multimodal analysis            - Workflow automation

Gemini CLI Capabilities

1. Google Search Grounding ⭐ KEY DIFFERENTIATOR

What: Real-time access to Google Search results within responses When to use:

• Need current framework documentation (post-Jan 2025)
• Looking up error messages and solutions
• Researching best practices and emerging patterns
• Finding library comparisons and benchmarks
• Understanding breaking changes in new releases

Example:

gemini "What are the breaking changes in Next.js 15?"
gemini "Best practices for React Server Components in 2025"
gemini "How to fix ECONNRESET errors in Node.js"

2. Codebase Investigator Agent ⭐ KEY DIFFERENTIATOR

What: Autonomous agent that maps entire codebase architecture When to use:

• Investigating unfamiliar codebases
• Understanding system-wide dependencies
• Identifying technical debt patterns
• Root-cause analysis across multiple modules

Example:

gemini "Analyze this codebase and map out:
1. Core architectural patterns
2. Module dependencies
3. Data flow
4. Testing strategy
5. Technical debt areas"

3. Massive Context Window

What: 1M tokens (vs Claude's 200k in standard mode) When to use:

• Analyzing entire documentation sets
• Processing very large codebases
• Reviewing extensive conversation history

4. Multimodal Analysis

What: Process images, PDFs, diagrams alongside text When to use:

• Analyzing architecture diagrams
• Reviewing UI mockups or screenshots
• Processing technical documentation PDFs
• Debugging from error screenshots

Example:

# Analyze diagram
gemini "Explain this architecture diagram and identify potential issues" < diagram.png

# Process PDF documentation
gemini "Summarize the key APIs from this documentation" < api-docs.pdf

5. Shell Interpolation

What: Inject live shell command output into prompts using !{command} When to use: Dynamic context in GEMINI.md custom commands Example:

prompt = """
Current git status:
!{git status --short}

Recent commits:
!{git log --oneline -5}

Analyze the current state and suggest next steps.
"""

6. Advanced Reasoning (Gemini 3 Pro)

What: State-of-the-art reasoning capabilities When to use:

• Complex technical problem-solving
• Architectural decision analysis
• Tradeoff evaluation
• Debugging intricate issues

Claude Code Capabilities (Stay in Claude for These)

1. Superior File Operations

• Edit tool: Precise string replacement in files
• Write tool: Create new files efficiently
• Read tool: Fast file reading with line ranges
• MultiEdit: Batch edits across files

2. Agent Orchestration

• Task tool: Launch specialized subagents in parallel
• Multiple specialized agents (architecture-strategist, code-simplicity-reviewer, etc.)
• Sophisticated workflow coordination

3. Project Pattern Recognition

• Understands established codebase patterns
• Maintains consistency with existing code
• Follows project-specific conventions
• Respects CLAUDE.md instructions

4. Skills System

• Modular skill invocation
• Context-aware best practices
• Domain-specific expertise (testing, documentation, etc.)

Decision Matrix: Claude vs Gemini

Task	Tool	Rationale
Research current framework best practices	Gemini	Web grounding gives latest info
Implement feature based on design	Claude	Superior file operations
Investigate unfamiliar codebase	Gemini	Codebase Investigator agent
Edit files in known codebase	Claude	Pattern recognition + Edit tool
Look up error solution	Gemini	Google Search grounding
Orchestrate multiple agents	Claude	Task tool + specialized agents
Analyze architecture diagram	Gemini	Multimodal analysis
Follow project conventions	Claude	Understands CLAUDE.md context
Debug with web research	Gemini	Real-time docs + Search
Refactor existing code	Claude	File operations + patterns
Understand new library API	Gemini	Latest docs via Search
Run slash commands	Claude	Designed for Claude's workflow
Design/UX research before frontend work	Gemini	Current trends, real examples, anti-convergence

Integration Patterns

Pattern 1: Research → Implement

1. Use Gemini for research
   gemini "/research Best practices for WebSocket in Next.js"

2. Document findings in RESEARCH.md

3. Return to Claude for implementation
   /architect (design based on research)
   /plan (create tasks)
   /execute (implement with Claude)

Pattern 2: Investigate → Fix

1. Gemini investigates error
   gemini "Analyze this error and suggest root cause"

2. Claude implements fix
   /execute (make the changes)
   /verify (run tests)

Pattern 3: Parallel Research

# Launch multiple Gemini sessions in parallel for different research topics
Terminal 1: gemini "Research authentication patterns"
Terminal 2: gemini "Research state management options"
Terminal 3: gemini "Research API design best practices"

# Consolidate findings in Claude

Pattern 4: Design Research → Implement

1. Gemini researches design direction
   gemini -p "Research distinctive approaches for [component type]"

2. Claude synthesizes and implements
   /skill frontend-design (apply research to implementation)

When to Explicitly Suggest Gemini

Claude should proactively suggest delegating to Gemini when:

Trigger Phrases from User:

• "What are current best practices for..."
• "How do people typically implement..."
• "I'm not familiar with this codebase..."
• "What's the latest on..."
• "Research whether..."
• "Investigate this error..."

Contextual Signals:

• User is about to implement something unfamiliar
• Need information about tools/frameworks after Jan 2025
• Working with an unfamiliar codebase
• Facing an error that needs web research
• Evaluating multiple technical options

Frontend/UX Work (ALWAYS):

• Building any new UI component
• Designing page layouts
• Choosing typography, colors, or visual direction
• Creating user flows or interactions

Example Response:

I can help implement this, but first let's research current best practices
using Gemini CLI's web grounding:

    gemini "What are Next.js 15 best practices for data fetching?"

This will give us the latest recommendations, then I can implement
following those patterns.

Gemini CLI Command Reference

Basic Usage

# Interactive mode (default)
gemini
gemini "your prompt here"

# Non-interactive mode
gemini --prompt "your prompt here"
gemini --prompt "your prompt" > output.txt

# Continue in interactive after prompt
gemini --prompt-interactive "start with this"

Modes

# YOLO mode (auto-approve all actions)
gemini --yolo "fix the failing tests"

# Sandbox mode (safer execution)
gemini --sandbox "install dependencies"

# Resume previous session
gemini --resume latest
gemini --resume 3  # Resume session #3

Session Management

# List previous sessions
gemini --list-sessions

# Delete a session
gemini --delete-session 3

Extensions & MCP

# List available extensions
gemini --list-extensions

# Use specific extensions
gemini -e extension1 -e extension2

# MCP server management
gemini mcp list
gemini mcp add server-name command [args...]
gemini mcp remove server-name

Output Formats

# JSON output for scripting
gemini --output-format json "analyze code"

# Streaming JSON
gemini --output-format stream-json "long analysis"

Best Practices

DO:

✅ Use Gemini for web-grounded research before implementing unfamiliar features ✅ Delegate codebase investigation to Codebase Investigator agent ✅ Use multimodal capabilities for diagram/screenshot analysis ✅ Bring research findings back to Claude for implementation ✅ Use non-interactive mode in scripts and automation ✅ Leverage Google Search grounding for current best practices

DON'T:

❌ Use Gemini for file edits in known codebases (Claude's Edit tool is better) ❌ Use Gemini when pattern matching matters (Claude knows project conventions) ❌ Use Gemini for agent orchestration (Claude's Task tool is superior) ❌ Duplicate work - if Gemini researched it, don't re-research in Claude ❌ Use Gemini for tasks that don't benefit from web grounding

GEMINI.md Configuration

Gemini uses ~/.gemini/GEMINI.md for project-specific context (like Claude's CLAUDE.md).

Key differences from Claude:

• Uses shell interpolation !{command} for dynamic context
• Custom commands are TOML format (not markdown)
• Emphasizes Google grounding capabilities

Current state: Well-configured GEMINI.md exists at ~/.gemini/GEMINI.md

Free Tier Limits

With Personal Google Account:

• 60 requests per minute
• 1,000 requests per day
• Access to Gemini 2.5 Pro (1M context)

Cost-effective for:

• Daily development research
• Periodic codebase investigations
• Error debugging sessions
• Best practice lookups

Philosophy: Complementary Tools

Gemini CLI ≠ Replacement for Claude
Gemini CLI = Research Assistant for Claude

Claude remains the primary interface for:
- File operations
- Code implementation
- Workflow orchestration
- Project pattern adherence

Gemini serves as specialized tool for:
- Web-grounded research
- Codebase investigation
- Current information lookup
- Multimodal analysis

The Goal: Use the right tool for each task, creating a powerful workflow where research (Gemini) feeds implementation (Claude).

Quick Decision Tree

Need to write/edit code?
├─ Yes → Use Claude
└─ No → Need current web info?
    ├─ Yes → Use Gemini
    └─ No → Analyzing unfamiliar code?
        ├─ Yes → Use Gemini (Codebase Investigator)
        └─ No → Following project patterns?
            ├─ Yes → Use Claude
            └─ No → Use Gemini for research, Claude for implementation

Summary: When to Suggest Gemini

Always suggest Gemini for:

1. Research needing current information (2025 best practices)
2. Investigating unfamiliar codebases
3. Error debugging requiring web search
4. Library/framework comparisons
5. Analyzing visual artifacts (diagrams, screenshots)

Never suggest Gemini for:

1. File edits in known codebases
2. Tasks requiring project pattern recognition
3. Workflow orchestration with multiple agents
4. Tasks that don't benefit from web grounding

The Integration Pattern: Research (Gemini) → Document (Claude) → Design (Claude) → Implement (Claude)