| 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:
gemini "Explain this architecture diagram and identify potential issues" < diagram.png
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
gemini
gemini "your prompt here"
gemini --prompt "your prompt here"
gemini --prompt "your prompt" > output.txt
gemini --prompt-interactive "start with this"
Modes
gemini --yolo "fix the failing tests"
gemini --sandbox "install dependencies"
gemini --resume latest
gemini --resume 3
Session Management
gemini --list-sessions
gemini --delete-session 3
Extensions & MCP
gemini --list-extensions
gemini -e extension1 -e extension2
gemini mcp list
gemini mcp add server-name command [args...]
gemini mcp remove server-name
Output Formats
gemini --output-format json "analyze code"
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:
- Research needing current information (2025 best practices)
- Investigating unfamiliar codebases
- Error debugging requiring web search
- Library/framework comparisons
- Analyzing visual artifacts (diagrams, screenshots)
Never suggest Gemini for:
- File edits in known codebases
- Tasks requiring project pattern recognition
- Workflow orchestration with multiple agents
- Tasks that don't benefit from web grounding
The Integration Pattern:
Research (Gemini) → Document (Claude) → Design (Claude) → Implement (Claude)
