Gemini CLI

What this skill does

# 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](#quick-start)
2. [When to Use Gemini Consultation](#when-to-use-gemini-consultation)
3. [Installation](#installation)
4. [Using Gemini CLI](#using-gemini-cli)
5. [Model Selection: Flash vs Pro](#model-selection-flash-vs-pro)
6. [Proactive Consultation Patterns](#proactive-consultation-patterns)
7. [AI-to-AI Prompting Best Practices](#ai-to-ai-prompting-best-practices)
8. [Common Use Cases](#common-use-cases)
9. [Integration Examples](#integration-examples)
10. [Troubleshooting & Known Issues](#troubleshooting--known-issues)

---

## Quick Start

**Prerequisites**:
- Gemini CLI installed (`npm install -g @google/gemini-cli`)
- Authenticated with Google account (run `gemini` once to authenticate)

**Basic Usage Patterns**:

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

# Code review with file context (using --all-files)
gemini --all-files -p "Review this auth implementation for security issues"

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

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

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

---

## 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?"
   - Why: Gemini provides complementary perspective, may prioritize different concerns
   - **Pattern**: `gemini -m gemini-2.5-pro -p "[architectural question]"`

2. **Security-Sensitive Code Changes**
   - Authentication systems
   - Payment processing
   - Data handling (PII, sensitive data)
   - API key/secret management
   - Why: Gemini 2.5 Pro excels at security audits
   - **Pattern**: `cat [security-file] | gemini -m gemini-2.5-pro -p "Security audit this code"`

3. **Large Refactors**
   - Affecting 5+ files
   - Core architecture changes
   - Database schema migrations
   - Why: Fresh perspective prevents tunnel vision
   - **Pattern**: `gemini --all-files -m gemini-2.5-pro -p "Review this refactoring plan"`

4. **Stuck Debugging (2+ Failed Attempts)**
   - Error persists after 2 debugging attempts
   - Stack trace unclear
   - Intermittent bugs
   - Why: Different reasoning approach may spot root cause
   - **Pattern**: `gemini -p "Help debug: [error message]" < error.log`

5. **Context Window Pressure (70%+ Full)**
   - Approaching token limit
   - Need to offload analysis to Gemini
   - Why: Gemini's 1M context can handle large code files
   - **Pattern**: `cat large-file.ts | gemini -p "Analyze this code structure"`

### OPTIONALLY Consult

6. **Unfamiliar Technology**
   - Using library/framework for first time
   - Experimenting with new patterns
   - Why: Gemini may have more recent training data
   - **Pattern**: `gemini -p "Best practices for [new technology]"`

7. **Code Reviews**
   - Before committing major changes
   - Pull request preparation
   - Why: Catches edge cases and improvements
   - **Pattern**: `git diff | gemini -p "Review these changes"`

---

## Installation

### 1. Install Gemini CLI

```bash
npm install -g @google/gemini-cli
```

### 2. Authenticate

```bash
gemini
```

Follow the authentication prompts to link your Google account.

### 3. Verify Installation

```bash
gemini --version
```

Should show version 0.13.0 or higher.

### 4. Test Connection

```bash
gemini -p "What is 2+2?"
```

---

## Using Gemini CLI

### Core Command Patterns

#### Non-Interactive Mode (`-p` flag)

Best for Claude Code integration:

```bash
# Direct question
gemini -p "Your question here"

# With model selection
gemini -m gemini-2.5-flash -p "Quick debugging question"
gemini -m gemini-2.5-pro -p "Complex architectural decision"

# With file context via pipe
cat src/auth.ts | gemini -p "Review this code"

# With all files in current directory
gemini --all-files -p "Analyze project structure"

# With stdin input
echo "Error: Cannot connect to database" | gemini -p "Help debug this error"
```

#### Interactive Mode (`-i` flag)

For follow-up conversations:

```bash
# Start interactive session with initial prompt
gemini -i "Let's discuss the architecture"

# Interactive with model selection
gemini -m gemini-2.5-pro -i "Help me design a database schema"
```

#### YOLO Mode (`-y` flag)

Auto-accepts all actions (use with caution):

```bash
# Dangerous: Auto-executes suggested commands
gemini -y -p "Fix all linting errors"
```

⚠️ **Warning**: YOLO mode can execute commands without confirmation. Only use in trusted environments.

---

## Model Selection: Flash vs Pro

### gemini-2.5-flash (Default)

**Characteristics**:
- Fast response time: ~5-25 seconds
- Good quality for most tasks
- Lower cost
- Safe for general questions

**Use For**:
- Code reviews
- Debugging
- General questions
- Quick consultations
- When speed matters

**Example**:
```bash
gemini -m gemini-2.5-flash -p "Review this function for performance issues"
```

### gemini-2.5-pro

**Characteristics**:
- Response time: ~15-30 seconds
- Excellent quality, thorough analysis
- Higher cost
- Best for critical decisions

**Use For**:
- Architecture decisions (critical)
- Security audits (thorough)
- Complex reasoning tasks
- Major refactoring plans
- When accuracy > speed

**Example**:
```bash
gemini -m gemini-2.5-pro -p "Security audit this authentication system"
```

### gemini-3-pro-preview (Preview - November 2025)

**Characteristics**:
- Google's newest and most intelligent AI model (announced Nov 18, 2025)
- State-of-the-art reasoning and multimodal understanding
- Outperforms Gemini 2.5 Pro on every major AI benchmark
- Supports text, image, video, audio, and PDF inputs
- Response time: TBD (in testing)
- Higher cost (preview pricing)

**Use For**:
- Most complex reasoning tasks requiring deep analysis
- Critical architectural decisions on cutting-edge projects
- Advanced multimodal analysis (diagrams, videos, complex docs)
- Benchmark-critical applications
- When absolute best quality is required (and cost is secondary)

**Example**:
```bash
gemini -m gemini-3-pro-preview -p "Deep architectural analysis of this distributed system"
cat architecture-diagram.png | gemini -m gemini-3-pro-preview -p "Analyze this system design"
```

**⚠️ Preview Status**: Model is in preview. For production-critical decisions, consider using `gemini-2.5-pro` (stable) until Gemini 3 reaches general availability.

### How to Choose

```
Quick question? → Flash
Security/architecture? → 3-Pro-Preview (cutting-edge) or 2.5-Pro (stable)
Debugging? → Flash (try Pro if stuck)
Code review? → Flash
Refactoring 5+ files? → 3-Pro-Preview or 2.5-Pro
Multimodal analysis? → 3-Pro-Preview
```

---

## Proactive Consultation Patterns

### Pattern 1: Architecture Decision

**Trigger**: User asks about technology choice
**Claude Action**: Automatically consult Gemini for second opinion

```bash
# Claude runs:
gemini -m gemini-2.5-pro -p "Compare D1 vs KV for session storage in Cloudflare Workers. Consider: read/write patterns, cost, performance, complexity."

# Then synthesizes both perspectives
```

### Pattern 2: Security Review

**Trigger**: Working on auth/payment/sensitive code
**Claude Action**: Request Gemini security audit

```bash
# Claude runs:
cat src/auth/verify-token.ts | gemini -m gemini-2.5-pr