Gemini: Google AI Assistant for Claude Code

---

DEFAULT MODEL: Gemini 3 Pro

The default model for ALL Gemini invocations is gemini-3-pro-preview.

• Always use gemini-3-pro-preview unless user explicitly requests another model
• This is the highest reasoning model available
• Fallback to gemini-2.5-flash ONLY on 404/access errors

# Default invocation - ALWAYS use gemini-3-pro-preview
gemini -m gemini-3-pro-preview "your prompt here"

---

CRITICAL: Positional Prompts Required

REQUIRED: Use positional prompts for Gemini CLI invocations.

DEPRECATED: -p/--prompt flag is officially deprecated and will be removed in a future version.

Examples:

• gemini -m gemini-3-pro-preview "prompt" (CORRECT - positional)
• gemini -m gemini-3-pro-preview -p "prompt" (DEPRECATED - avoid using)
• gemini -r latest (CORRECT - session resume)

Warning from CLI help: "[deprecated: Use the positional prompt instead. This flag will be removed in a future version.]"

Why? As of Gemini CLI v0.20.0, the -p flag is explicitly marked deprecated. Use positional prompts for forward compatibility.

---

IMPORTANT: Preview Features & OAuth Free Tier

For OAuth free tier users in headless mode:

When previewFeatures: true in ~/.gemini/settings.json, the CLI routes ALL requests to Gemini 3 Pro (even -m gemini-2.5-pro). Since free tier doesn't have Gemini 3 access, this causes 404 errors.

Solution: Disable preview features for reliable headless operation:

// ~/.gemini/settings.json
{
  "general": {
    "previewFeatures": false
  }
}

Plugin Behavior: This skill automatically falls back to gemini-2.5-flash when encountering 404 errors. Flash always works with OAuth free tier.

---

Trigger Examples

This skill activates when users say phrases like:

• "Use gemini to research this topic"
• "Ask gemini about this design pattern"
• "Run gemini on this analysis"
• "Call gemini for help with this problem"
• "I need Google AI for this task"
• "Get Gemini's reasoning on this"
• "Continue with gemini" or "Resume the gemini session"
• "Gemini, help me with..." or simply "Gemini"
• "Use Gemini 3" or "Use Gemini 2.5"

When to Use This Skill

This skill should be invoked when:

• User explicitly mentions "Gemini" or requests Gemini assistance
• User needs Google's AI models for reasoning, research, or analysis
• User requests complex problem-solving or architectural design
• User needs research capabilities with web search integration
• User wants to continue a previous Gemini conversation
• User needs an alternative to Codex or Claude for specific tasks

How It Works

Detecting New Gemini Requests

When a user makes a request, default to read-only mode (default approval) unless they explicitly request file editing:

Use gemini-3-pro-preview for ALL tasks with default approval mode:

• Architecture, design, reviews, research
• Explanations, analysis, problem-solving
• Code analysis and understanding
• ANY task where user does NOT explicitly request file editing

Approval Mode Selection:

• default (default): For all tasks - prompts for approval on edits (safe)
• auto_edit: ONLY when user explicitly requests file editing
• yolo: When user explicitly wants full auto-approval (use with caution)

⚠️ Explicit Edit Request: If the user explicitly asks to "edit files", "modify code", "write changes", or "make edits" - ONLY then use --approval-mode auto_edit to enable file modifications.

Fallback Chain (if primary unavailable):

1. gemini-3-pro-preview (primary - highest capability)
2. gemini-2.5-pro (stable general reasoning)
3. gemini-2.5-flash (fast, always available)

Example requests: "Design a distributed cache", "Explain CQRS pattern", "Analyze this code"

Bash CLI Command Structure

IMPORTANT: Gemini CLI works differently from Codex - no exec subcommand needed. Use positional prompts directly.

Default Command (Read-Only) - Use for ALL Tasks

gemini -m gemini-3-pro-preview \
  "Design a microservices architecture for e-commerce"

Explicit Edit Request Only - When User Asks to Edit Files

gemini -m gemini-3-pro-preview \
  --approval-mode auto_edit \
  "Edit this file to refactor the function"

For Session Continuation

# Resume most recent session
gemini -r latest

# Resume specific session by index
gemini -r 3

# Resume and add new prompt
gemini -r latest "Continue our discussion about caching strategies"

Why positional prompts?

• Simpler, more direct syntax
• Future-proof (recommended by Gemini CLI)
• Works in non-TTY environments (like Claude Code's bash)
• No separate exec command needed

Model Selection Logic

Use gemini-3-pro-preview (default for ALL tasks):

• Code editing, refactoring, implementation
• Designing architecture or system design
• Conducting research or analysis
• Explaining complex concepts
• Planning implementation strategies
• General problem-solving and advanced reasoning

Fallback to gemini-2.5-pro when:

• Gemini 3 Pro unavailable or quota exhausted
• User explicitly requests "Gemini 2.5" or "use 2.5"
• Stable, production-ready tasks

Fallback to gemini-2.5-flash when:

• Both Gemini 3 Pro and 2.5 Pro unavailable
• Fast iterations needed (explicit user request)
• Simple, quick responses (explicit user request)

Version-Based Model Mapping

When users mention a version number, map to the latest model in that family:

User Request	Maps To	Actual Model ID
"use 3" / "Gemini 3"	Latest 3.x Pro	gemini-3-pro-preview
"use 2.5"	2.5 Pro	gemini-2.5-pro
"use flash"	2.5 Flash	gemini-2.5-flash
No version specified	Latest Pro (ALL tasks)	gemini-3-pro-preview

See: references/model-selection.md for detailed model selection guidance and decision tree.

Default Configuration

All Gemini invocations use these defaults unless user specifies otherwise:

Parameter	Default Value	CLI Flag	Notes
Model	gemini-3-pro-preview	-m gemini-3-pro-preview	For ALL tasks (highest capability)
Model (fallback 1)	gemini-2.5-pro	-m gemini-2.5-pro	If Gemini 3 Pro unavailable
Model (fallback 2)	gemini-2.5-flash	-m gemini-2.5-flash	Always works on free tier
Approval Mode (default)	default	No flag	Safe default - prompts for edits
Approval Mode (editing)	auto_edit	--approval-mode auto_edit	Only when user explicitly requests editing
Sandbox	false (disabled)	No flag	Sandbox disabled by default
Output Format	text	No flag	Human-readable text output
Web Search	Enabled when appropriate	-e web_search (if needed)	Context-dependent

Rationale for Defaults:

• Gemini 3 Pro for ALL tasks: Highest capability model, optimized for both reasoning and code
• Fallback chain: gemini-3-pro-preview → gemini-2.5-pro → gemini-2.5-flash
• default mode: Safe default that prompts for approval on edits
• auto_edit mode: Only use when user explicitly requests file editing
• No sandbox: Claude Code environment assumed trusted
• Text output: Default for human consumption (use --output-format json for parsing)

Note: If you have previewFeatures: true in settings, disable it for reliable headless operation (see warning above).

Error Handling

The skill handles these common errors gracefully:

CLI Not Installed

Error: command not found: gemini

Message: "Gemini CLI not installed. Install from: https://github.com/google-gemini/gemini-cli"

Action: User must install Gemini CLI before using this skill

Authentication Required

Error: Output contains "auth" or "authentication"

Message: "Authentication required. Run: gemini login to authenticate with your Google account"

Action: User must authenticate via OAuth or API key

Rate Limit Exceeded

Error: Output contains "quota" or "rate limit" or status 429

Message: "Rate limit exceeded (60 req/min, 1000 req/day free tier). Retry in X seconds or upgrade account."

Action: Wait for rate limit reset or upgrade to paid tier

Model Unavailable

Error: Output contains "model not found" or "404" or status 403

Message: "Model unavailable. Trying fallback model..."

Action: Automatically retry with fallback:

• gemini-3-pro-preview unavailable → try gemini-2.5-pro
• gemini-2.5-pro unavailable → try gemini-2.5-flash

Session Not Found

Error: Using -r flag but session doesn't exist

Message: "Session not found. Use gemini --list-sessions to see available sessions."

Action: User should list sessions or start new session

Gemini 3 Pro Access Denied

Error: Status 403 or "preview access required"

Message: "Gemini 3 Pro requires preview access. Enable Preview Features in settings or use gemini-2.5-pro instead."

Action: Either enable preview features, get API key, or use 2.5 models

See: references/gemini-help.md for complete CLI reference and troubleshooting.

---

Examples

Basic Invocation (General Reasoning)

# Design system architecture
gemini -m gemini-3-pro-preview "Design a scalable payment processing system"

# Research with web search
gemini -m gemini-3-pro-preview -e web_search "Research latest React 19 features"

# Explain complex concept
gemini -m gemini-3-pro-preview "Explain the CAP theorem with real-world examples"

Code Editing Tasks

# Refactoring (uses gemini-3-pro-preview for all tasks)
gemini -m gemini-3-pro-preview "Refactor this function for better readability"

# Fix syntax errors
gemini -m gemini-3-pro-preview "Fix the syntax errors in this JavaScript code"

# Optimize performance
gemini -m gemini-3-pro-preview "Optimize this database query for better performance"

Session Management

# Start a session (automatic)
gemini -m gemini-3-pro-preview "Design an authentication system"

# List available sessions
gemini --list-sessions

# Resume most recent
gemini -r latest

# Resume specific session
gemini -r 3

# Continue with new prompt
gemini -r latest "Now help me implement the login flow"

With Output Formatting

# JSON output for parsing
gemini -m gemini-2.5-pro --output-format json "List top 5 design patterns"

# Streaming JSON for real-time
gemini -m gemini-2.5-pro --output-format stream-json "Explain async patterns"

Approval Modes

# Default mode (prompt for all)
gemini -m gemini-2.5-pro --approval-mode default "Review this code"

# Auto-edit (auto-approve edits only)
gemini -m gemini-2.5-pro --approval-mode auto_edit "Refactor this module"

# YOLO mode (auto-approve ALL - use with caution)
gemini -m gemini-2.5-pro --approval-mode yolo "Deploy to production"

Sandbox Mode

# Enable sandbox for untrusted code
gemini -m gemini-2.5-pro -s "Analyze this suspicious code snippet"

# Disabled by default (trusted environment)
gemini -m gemini-2.5-pro "Review this internal codebase"

Extensions & MCP Integration

Gemini CLI supports extensions and Model Context Protocol (MCP) servers for enhanced functionality.

# List available extensions
gemini --list-extensions

# Use specific extensions (web search, code analysis, etc.)
gemini -m gemini-3-pro-preview -e web_search "Research React 19 features"

# Use all extensions (default)
gemini -m gemini-3-pro-preview "Design system architecture"

Note: This plugin does not implement custom extensions or MCP servers. Users can configure extensions and MCP servers through the Gemini CLI's standard configuration in ~/.gemini/settings.json. Extensions are enabled by default when appropriate for the task.

Additional Directories (--include-directories) (v0.20.0+)

Include additional directories in workspace context:

# Single directory
gemini -m gemini-3-pro-preview --include-directories /shared/libs "task"

# Multiple directories (comma-separated)
gemini -m gemini-3-pro-preview --include-directories /path1,/path2 "task"

# Multiple directories (repeated flag)
gemini -m gemini-3-pro-preview --include-directories /path1 --include-directories /path2 "task"

Note: Disabled in restrictive sandbox profiles.

Accessibility (--screen-reader) (v0.20.0+)

Enable screen reader mode for accessibility:

gemini -m gemini-3-pro-preview --screen-reader "task"

Interactive with Prompt (-i/--prompt-interactive) (v0.20.0+)

Execute a prompt and continue in interactive mode:

gemini -m gemini-3-pro-preview -i "initial prompt here"

Note: Limited applicability for Claude Code skills which use non-interactive mode.

Experimental ACP Mode (--experimental-acp)

Start agent in Agent Control Protocol mode for programmatic interaction:

gemini --experimental-acp "task"

Note: Experimental feature. Works with GEMINI_API_KEY environment variable.

---

Reference Documentation

For detailed information, see the references directory:

• references/gemini-help.md - Complete Gemini CLI help output and flag reference
• references/command-patterns.md - Common command templates organized by use case
• references/session-workflows.md - Multi-turn conversation patterns and best practices
• references/model-selection.md - Model selection decision tree and version mapping

---

Tips & Best Practices

1. Always Specify Model: Use -m flag explicitly for predictable behavior
2. Use Positional Prompts: Prefer gemini "prompt" over deprecated -p flag
3. Enable Web Search When Needed: Add -e web_search for research tasks
4. Resume Sessions for Complex Tasks: Use -r latest for multi-turn conversations
5. Start with Gemini 3 Pro: Default to gemini-3-pro-preview, fallback to 2.5 models
6. Use Appropriate Approval Mode: auto_edit for code, default for untrusted tasks
7. Monitor Rate Limits: 60 req/min, 1000 req/day on free tier
8. Check CLI Availability: Validate command -v gemini before invocation

---

Differences from Codex

Feature	Codex CLI	Gemini CLI
Invocation	codex exec "prompt"	gemini "prompt"
Subcommand	Required (exec)	Not needed
Positional Prompts	Not supported	Preferred
Session Resume	codex exec resume --last	gemini -r latest
Models	GPT-5.1, GPT-5.1-Codex	Gemini 3 Pro, 2.5 Pro/Flash
Provider	OpenAI (via Codex)	Google

---

When to Use Gemini vs Codex vs Claude

Use Gemini when:

• You need Google's latest models
• Research with web search is important
• You prefer Google's AI capabilities
• Codex is unavailable or rate-limited
• Task benefits from Gemini's strengths

Use Codex when:

• You need GPT-5.1's reasoning capabilities
• Task requires high-reasoning model
• Code editing with specific Codex optimizations
• You're already using Codex workflow

Use Claude (native) when:

• Simple queries within Claude Code's capabilities
• No external AI needed
• Quick responses preferred
• Task doesn't require specialized models

---

Version Compatibility

• Minimum Gemini CLI: v0.20.0
• Recommended: v0.20.x stable (latest)
• Preview/Nightly: Weekly previews available (Tuesdays UTC 2359)

Changes in v0.20.0:

• -p/--prompt flag officially deprecated (use positional prompts)
• New --include-directories flag for workspace expansion
• New -i/--prompt-interactive flag for interactive continuation
• New --screen-reader accessibility flag
• New --experimental-acp Agent Control Protocol mode
• Session management via -r flag standard

---

For questions or issues, consult references/gemini-help.md or run gemini --help.