Gemini CLI

Leverage Gemini's 1M+ context window as your AI pair programmer within Claude Code workflows.

This skill teaches Claude Code how to use the official Google Gemini CLI (gemini command) to get second opinions, architectural advice, debugging help, and comprehensive code reviews. Based on production testing with the official CLI tool.

Table of Contents

1. Quick Start
2. When to Use Gemini Consultation
3. Installation
4. Model Selection: Flash vs Pro
5. Top 3 Use Cases
6. Integration Example
7. Top 3 Errors & Solutions
8. When to Load References
9. Production Rules

Quick Start

Prerequisites:

• Gemini CLI installed (bun add -g @google/gemini-cli)
• Authenticated with Google account (run gemini once to authenticate)

Core Command Patterns:

# Quick question (non-interactive with -p flag)
gemini -p "Should I use D1 or KV for session storage?"

# Code review with file context
cat src/auth.ts | gemini -p "Review this authentication code for security vulnerabilities"

# Architecture advice using Pro model
gemini -m gemini-2.5-pro -p "Best way to handle WebSockets in Cloudflare Workers?"

# With all files in directory
gemini --all-files -p "Review this auth implementation for security issues"

# Interactive mode for follow-up questions
gemini -i "Help me debug this authentication error"

Critical: Always use -p flag for non-interactive commands in automation/scripts.

When to Use Gemini Consultation

ALWAYS Consult (Critical Scenarios)

Claude Code should automatically invoke Gemini in these situations:

1. Major Architectural Decisions

   • Example: "Should I use D1 or KV for session storage?"
   • Example: "Durable Objects vs Workflows for long-running tasks?"
   • Pattern: gemini -m gemini-2.5-pro -p "[architectural question]"

2. Security-Sensitive Code Changes

   • Authentication systems, payment processing, PII handling
   • API key/secret management
   • Pattern: cat [security-file] | gemini -m gemini-2.5-pro -p "Security audit this code"

3. Stuck Debugging (2+ Failed Attempts)

   • Error persists after 2 debugging attempts
   • Stack trace unclear or intermittent bugs
   • Pattern: gemini -p "Help debug: [error message]" < error.log

4. Large Refactors (5+ Files)

   • Core architecture changes, database schema migrations
   • Pattern: gemini --all-files -m gemini-2.5-pro -p "Review this refactoring plan"

5. Context Window Pressure (70%+ Full)

   • Approaching token limit, need to offload analysis
   • Pattern: cat large-file.ts | gemini -p "Analyze this code structure"

OPTIONALLY Consult

6. Unfamiliar Technology - Using library/framework for first time
7. Code Reviews - Before committing major changes

Installation

1. Install Gemini CLI

bun add -g @google/gemini-cli

2. Authenticate

gemini

Follow the authentication prompts to link your Google account.

3. Verify Installation

gemini --version  # Should show 0.13.0+
gemini -p "What is 2+2?"  # Test connection

Model Selection: Flash vs Pro

gemini-2.5-flash (Default)

• Speed: ~5-25 seconds
• Quality: Good for most tasks
• Use For: Code reviews, debugging, quick questions
• Cost: Lower

gemini -m gemini-2.5-flash -p "Review this function for performance issues"

gemini-2.5-pro

• Speed: ~15-30 seconds
• Quality: Excellent, thorough analysis
• Use For: Architecture decisions, security audits, major refactors
• Cost: Higher

gemini -m gemini-2.5-pro -p "Security audit this authentication system"

Quick Decision Guide

Quick question? → Flash
Security/architecture? → Pro
Debugging? → Flash (try Pro if stuck)
Refactoring 5+ files? → Pro

CRITICAL FINDING: Flash and Pro can give opposite recommendations on the same question (both valid, different priorities). Flash prioritizes performance, Pro prioritizes consistency/correctness. For details, load references/models-guide.md.

Top 3 Use Cases

1. Security Audit

# Audit authentication code
cat src/middleware/auth.ts | gemini -m gemini-2.5-pro -p "
Security audit this authentication middleware. Check for:
1. Token validation vulnerabilities
2. Timing attack risks
3. Error handling leaks
4. CSRF protection
5. Rate limiting
"

2. Architecture Decision

# Compare technologies with context
gemini -m gemini-2.5-pro -p "
Context: Building Cloudflare Worker with user authentication.

Question: Should I use D1 or KV for storing session data?

Considerations:
1. Session reads on every request
2. TTL-based expiration
3. Cost under 10M requests/month
4. Deployment complexity
"

3. Debugging Root Cause

# Analyze error logs with context
tail -100 error.log | gemini -p "
These errors started after deploying auth changes. What's the likely root cause?

Context:
- Added JWT validation middleware
- Using @cloudflare/workers-jwt
- Errors only on /api/* routes
"

For more use cases: Load references/models-guide.md for performance optimization, refactoring plans, and code reviews.

Integration Example

Claude Consulting Gemini Automatically

Scenario: User asks architectural question

User: "Should I use D1 or KV for storing user sessions?"

Claude (internal): This is an architectural decision. Consult Gemini for second opinion.

[Runs: gemini -m gemini-2.5-pro -p "Compare D1 vs KV for user session storage in Cloudflare Workers. Consider: read/write patterns, cost, performance, complexity."]

Claude (to user): "I've consulted Gemini for a second opinion. Here's what we both think:

My perspective: [Claude's analysis]
Gemini's perspective: [Gemini's analysis]

Key differences: [synthesis]
Recommendation: [combined recommendation]"

Key Pattern: Synthesize both perspectives, don't just forward Gemini's response.

Top 3 Errors & Solutions

Error 1: Not Authenticated

Error: Error: Not authenticated

Solution:

gemini  # Follow authentication prompts

Error 2: Model Not Found

Error: Error: Model not found: gemini-2.5-flash-lite

Cause: Model deprecated or renamed (flash-lite doesn't exist)

Solution: Use stable models only:

gemini -m gemini-2.5-flash -p "Your question"
gemini -m gemini-2.5-pro -p "Your question"

Error 3: Command Hangs

Cause: Interactive mode when expecting non-interactive

Solution: Always use -p flag for non-interactive commands

# ✅ Correct
gemini -p "Question"

# ❌ Wrong (will hang waiting for input)
gemini "Question"

For more troubleshooting: Load references/models-guide.md for rate limits, large file context issues, and performance tips.

When to Load References

Load reference files in these scenarios:

Load references/models-guide.md when:

• User asks about Flash vs Pro differences
• Models give conflicting recommendations
• Need detailed performance comparison
• Choosing model for specific task type
• Want to understand why models disagree

Load references/prompting-strategies.md when:

• Crafting complex prompts to Gemini
• Need AI-to-AI prompting format template
• Want to improve prompt quality
• Comparing old vs new prompting approaches

Load references/gemini-experiments.md when:

• Need historical context on testing
• Investigating edge cases
• Understanding design decisions
• Troubleshooting unusual behavior

Note: helper-functions.md is obsolete (references old gemini-coach wrapper, not the official gemini CLI).

Production Rules

1. Always Use -p for Automation

# ✅ Good for scripts
gemini -p "Question"

# ❌ Bad (interactive)
gemini

2. Select Model Based on Criticality

# Architecture/security → Pro
gemini -m gemini-2.5-pro -p "[critical question]"

# Debugging/review → Flash
gemini -m gemini-2.5-flash -p "[general question]"

3. Provide Context in Prompts

# ✅ Good: Context + Question + Considerations
gemini -p "Context: Building Cloudflare Worker. Question: Best auth pattern? Considerations: 1) Stateless, 2) JWT, 3) <100ms overhead"

# ❌ Bad: Vague
gemini -p "Best auth?"

4. Pipe File Content for Reviews

# ✅ Efficient
cat src/auth.ts | gemini -p "Review for security"

# ❌ Less efficient
gemini -p "Review src/auth.ts"

5. Synthesize, Don't Just Forward

❌ BAD: Just paste Gemini's response

Claude: [runs gemini] "Gemini says: [paste]"

✅ GOOD: Synthesize both perspectives

Claude: "I've consulted Gemini for a second opinion:

My analysis: [Claude's perspective]
Gemini's analysis: [Gemini's perspective]
Key differences: [synthesis]
Recommendation: [unified answer]"

6. Handle Errors Gracefully

if output=$(gemini -p "Question" 2>&1); then
  echo "Gemini says: $output"
else
  echo "Gemini consultation failed, proceeding with Claude's recommendation"
fi

Version History

2.1.0 (2025-12-15):

• Optimized to <500 lines (Phase 12.5 → 13 condensation)
• Extracted detailed content to references/
• Added "When to Load References" section
• Condensed to top 3 errors, top 3 use cases

2.0.0 (2025-11-13):

• Complete rewrite for official Gemini CLI (removed gemini-coach wrapper)
• Direct CLI integration patterns
• Updated command examples for gemini CLI v0.13.0+

1.0.0 (2025-11-08):

• Initial release with gemini-coach wrapper

Related Skills

• google-gemini-api - Gemini API integration via SDK
• google-gemini-embeddings - Gemini embeddings for RAG
• google-gemini-file-search - Managed RAG with Gemini

License

MIT - See LICENSE

Support

• Issues: https://github.com/jezweb/claude-skills/issues
• Email: jeremy@jezweb.net
• Official Gemini CLI: https://github.com/google-gemini/gemini-cli