name	gemini
version	1.2.0
description	Invoke Google Gemini CLI for complex reasoning tasks, research, and AI assistance. Trigger phrases include "use gemini", "ask gemini", "run gemini", "call gemini", "gemini cli", "Google AI", "Gemini reasoning", or when users request Google's AI models, need advanced reasoning capabilities, research with web search, or want to continue previous Gemini conversations. Automatically triggers on Gemini-related requests and supports session continuation for iterative development.

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):

gemini-3-pro-preview (primary - highest capability)
gemini-2.5-pro (stable general reasoning)
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

Always Specify Model: Use -m flag explicitly for predictable behavior
Use Positional Prompts: Prefer gemini "prompt" over deprecated -p flag
Enable Web Search When Needed: Add -e web_search for research tasks
Resume Sessions for Complex Tasks: Use -r latest for multi-turn conversations
Start with Gemini 3 Pro: Default to gemini-3-pro-preview, fallback to 2.5 models
Use Appropriate Approval Mode: auto_edit for code, default for untrusted tasks
Monitor Rate Limits: 60 req/min, 1000 req/day on free tier
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.

name	gemini
version	1.2.0
description	Invoke Google Gemini CLI for complex reasoning tasks, research, and AI assistance. Trigger phrases include "use gemini", "ask gemini", "run gemini", "call gemini", "gemini cli", "Google AI", "Gemini reasoning", or when users request Google's AI models, need advanced reasoning capabilities, research with web search, or want to continue previous Gemini conversations. Automatically triggers on Gemini-related requests and supports session continuation for iterative development.

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:

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)

Fallback Chain (if primary unavailable):

gemini-3-pro-preview (primary - highest capability)
gemini-2.5-pro (stable general reasoning)
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"

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

Always Specify Model: Use -m flag explicitly for predictable behavior
Use Positional Prompts: Prefer gemini "prompt" over deprecated -p flag
Enable Web Search When Needed: Add -e web_search for research tasks
Resume Sessions for Complex Tasks: Use -r latest for multi-turn conversations
Start with Gemini 3 Pro: Default to gemini-3-pro-preview, fallback to 2.5 models
Use Appropriate Approval Mode: auto_edit for code, default for untrusted tasks
Monitor Rate Limits: 60 req/min, 1000 req/day on free tier
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.

gemini

Gemini: Google AI Assistant for Claude Code

DEFAULT MODEL: Gemini 3 Pro

CRITICAL: Positional Prompts Required

IMPORTANT: Preview Features & OAuth Free Tier

Trigger Examples

When to Use This Skill

How It Works

Detecting New Gemini Requests

Bash CLI Command Structure

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

Explicit Edit Request Only - When User Asks to Edit Files

For Session Continuation

Model Selection Logic

Version-Based Model Mapping

Default Configuration

Error Handling

CLI Not Installed

Authentication Required

Rate Limit Exceeded

Model Unavailable

Session Not Found

Gemini 3 Pro Access Denied

Examples

Basic Invocation (General Reasoning)

Code Editing Tasks

Session Management

With Output Formatting

Approval Modes

Sandbox Mode

Extensions & MCP Integration

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

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

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

Experimental ACP Mode (--experimental-acp)

Reference Documentation

Tips & Best Practices

Differences from Codex

When to Use Gemini vs Codex vs Claude

Version Compatibility

Gemini: Google AI Assistant for Claude Code

DEFAULT MODEL: Gemini 3 Pro

CRITICAL: Positional Prompts Required

IMPORTANT: Preview Features & OAuth Free Tier

Trigger Examples

When to Use This Skill

How It Works

Detecting New Gemini Requests

Bash CLI Command Structure

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

Explicit Edit Request Only - When User Asks to Edit Files

For Session Continuation

Model Selection Logic

Version-Based Model Mapping

Default Configuration

Error Handling

CLI Not Installed

Authentication Required

Rate Limit Exceeded

Model Unavailable

Session Not Found

Gemini 3 Pro Access Denied

Examples

Basic Invocation (General Reasoning)

Code Editing Tasks

Session Management

With Output Formatting

Approval Modes

Sandbox Mode

Extensions & MCP Integration

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

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

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

Experimental ACP Mode (--experimental-acp)

Reference Documentation

Tips & Best Practices

Differences from Codex

When to Use Gemini vs Codex vs Claude

Version Compatibility

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

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

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

Experimental ACP Mode (`--experimental-acp`)

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

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

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

Experimental ACP Mode (`--experimental-acp`)