Gemini CLI Integration Skill

This skill enables Claude Code to orchestrate Google Gemini CLI (v0.22.0+) with Gemini 3 Pro for code generation, review, analysis, and specialized tasks including real-time web search.

What's New in v0.22.0 (December 2025)

•Gemini 3: Free tier users now have access to Gemini 3 via Preview Features toggle
•Colab Integration: Pre-installed in Google Colab, usable headlessly in notebook cells
•
Extensions Support:
- •Conductor: Planning++ with context-driven development
- •Endor Labs: Code analysis, vulnerability scanning, dependency checks
•Comprehensive Quota Visibility: /stats shows all model usage
•Multi-file Drag & Drop: Proper @ prefix handling for multiple files

When to Use This Skill

Ideal Use Cases

•
Second Opinion / Cross-Validation
- •Review code after Claude writes it (different AI perspective)
- •Security audit with alternative analysis
- •Find bugs Claude might have missed
•
Google Search Grounding
- •Questions requiring current internet information
- •Latest library versions, API changes, documentation
- •Current events, recent releases
•
Codebase Architecture Analysis
- •Use codebase_investigator tool
- •Understanding unfamiliar codebases
- •Mapping cross-file dependencies
•
Parallel Processing
- •Offload tasks while continuing other work
- •Multiple code generations simultaneously
- •Background documentation generation
•
Extensions Workflows
- •Conductor for detailed planning before implementation
- •Endor Labs for security/vulnerability scanning

When NOT to Use

•Simple, quick tasks (overhead not worth it)
•Tasks requiring immediate response (rate limits cause delays)
•When context is already loaded in Claude
•Interactive refinement requiring conversation

Quick Start

Prerequisites

bash

# Verify installation
command -v gemini || which gemini

# Check version
gemini --version  # Should show v0.22.0+

Authentication

bash

# Option 1: API Key
export GEMINI_API_KEY=your_key

# Option 2: OAuth (interactive, first run)
gemini  # Prompts for auth

Enable Gemini 3 (Free Tier)

In interactive mode:

code

/settings
# Toggle "Preview Features" to true

Core Commands

Basic Execution

bash

# Human-readable output
gemini "your prompt" --yolo -o text 2>&1

# JSON structured output
gemini "your prompt" --yolo -o json 2>&1

# Faster model for simple tasks
gemini "your prompt" -m gemini-2.5-flash -o text 2>&1

Key Flags

Flag	Short	Description
`--yolo`	`-y`	Auto-approve all tool calls
`--output-format`	`-o`	Output: `text`, `json`, `stream-json`
`--model`	`-m`	Model selection
`--resume`	`-r`	Resume session by index
`--sandbox`	`-s`	Run in isolated sandbox
`--debug`	`-d`	Enable debug output

Important Behavior Notes

YOLO Mode: Auto-approves tool calls but does NOT prevent planning prompts. Gemini may still ask "Does this plan look good?" Use forceful language:

•"Apply now"
•"Start immediately"
•"Do this without asking for confirmation"

Rate Limits: Free tier has 60 requests/min, 1000/day. CLI auto-retries with backoff.

Model Selection

Model	Use Case	Context
`gemini-3-pro`	Complex tasks (default)	1M tokens
`gemini-2.5-flash`	Quick tasks, lower latency	Large
`gemini-2.5-flash-lite`	Fastest, simplest tasks	Medium

bash

# Default (Gemini 3 Pro)
gemini "complex analysis" -o text

# Flash for speed
gemini "simple task" -m gemini-2.5-flash -o text

Unique Gemini Capabilities

1. google_web_search

Real-time internet search via Google:

bash

gemini "What are the latest React 19 features? Use Google Search." -o text

gemini "What's new in TypeScript 5.5? Use Google Search." -o text

gemini "Best practices for Next.js 15 as of December 2025." -o text

Best for:

•Current events and news
•Latest library versions
•Recent documentation updates
•Community opinions and benchmarks

2. codebase_investigator

Deep codebase analysis:

bash

gemini "Use the codebase_investigator tool to analyze this project" -o text

gemini "Use codebase_investigator to map the authentication flow" -o text

Output includes:

•Overall architecture description
•Key file purposes
•Component relationships
•Dependency chains
•Potential issues

3. save_memory

Cross-session persistence:

bash

gemini "Remember that this project uses Zustand. Save to memory." -o text

Extensions (v0.22.0+)

Conductor Extension

Planning++ with context-driven development:

bash

# Install
gemini extensions install https://github.com/gemini-cli-extensions/conductor

# Use for detailed planning
gemini "Use Conductor to plan the implementation of user authentication" -o text

Conductor workflow: Plan → Pull details → Create guardrails → Implement

Endor Labs Extension

Security analysis and dependency checks:

bash

# Install
gemini extensions install https://github.com/endorlabs/gemini-extension

# Use for security scanning
gemini "Use Endor Labs to check for vulnerabilities in this project" -o text

List Extensions

bash

gemini --list-extensions
# or
gemini -l

Integration Patterns

Pattern 1: Generate-Review-Fix Cycle

bash

# 1. Generate
gemini "Create a user auth module with bcrypt and JWT" --yolo -o text

# 2. Review (Gemini reviews its own work)
gemini "Review auth.js for security vulnerabilities" -o text

# 3. Fix identified issues
gemini "Fix in auth.js: XSS risk, add input validation. Apply now." --yolo -o text

Pattern 2: Background Execution

For long tasks, run in background:

bash

gemini "Generate comprehensive tests" --yolo -o text 2>&1 &
echo $!  # Get PID

# Multiple parallel tasks
gemini "Create frontend" --yolo -o text 2>&1 &
gemini "Create backend" --yolo -o text 2>&1 &
gemini "Create tests" --yolo -o text 2>&1 &
wait

Pattern 3: Cross-Validation with Claude

bash

# Claude generates → Gemini reviews
# (After Claude writes code)
gemini "Review this code for bugs and security issues: [paste code]" -o text

# Gemini generates → Claude reviews
gemini "Create [code]" --yolo -o text
# Then Claude reviews the output

Pattern 4: Session Continuity

bash

# Initial task
gemini "Analyze this codebase architecture" -o text

# List sessions
gemini --list-sessions

# Resume for follow-up
echo "What patterns did you find?" | gemini -r 1 -o text

# Further refinement
echo "Focus on authentication flow" | gemini -r 1 -o text

JSON Output Processing

bash

gemini "your prompt" -o json 2>&1

Response structure:

json

{
  "response": "The actual response content",
  "stats": {
    "models": {
      "gemini-3-pro": {
        "tokens": {
          "prompt": 1500,
          "candidates": 500,
          "total": 2000,
          "cached": 800
        }
      }
    },
    "tools": {
      "totalCalls": 2,
      "byName": {
        "google_web_search": {"count": 1, "success": 1}
      }
    }
  }
}

Configuration

Settings Location

Priority order:

•/etc/gemini-cli/settings.json (system)
•~/.gemini/settings.json (user)
•.gemini/settings.json (project)

Project Context (GEMINI.md)

Create .gemini/GEMINI.md in project root:

markdown

# Project Context

This is a TypeScript React app.

## Coding Standards
- Use functional components
- Prefer hooks over classes
- All functions need JSDoc

Ignore Files (.geminiignore)

code

node_modules/
dist/
*.log
.env

Quick Reference Commands

Task	Command
Basic query	`gemini "prompt" --yolo -o text`
Web search	`gemini "prompt. Use Google Search." -o text`
Architecture	`gemini "Use codebase_investigator..." -o text`
Fast model	`gemini "prompt" -m gemini-2.5-flash -o text`
JSON output	`gemini "prompt" -o json`
Resume session	`echo "follow-up" \| gemini -r 1 -o text`
List sessions	`gemini --list-sessions`
List extensions	`gemini --list-extensions`

Rate Limit Strategies

•Let auto-retry handle it: Default behavior with backoff
•Use Flash for lower priority: Different quota
•Batch operations: Combine into single prompts
•Add delays: sleep 2 between calls in scripts

Error Handling

Common Issues

Issue	Solution
"API key not found"	Set `GEMINI_API_KEY` env var
"Rate limit exceeded"	Wait for auto-retry or use Flash
"Context too large"	Use `.geminiignore` or be specific
"Tool call failed"	Check JSON stats for details

Debug Mode

bash

gemini "prompt" --debug -o text

Validation After Generation

Always verify Gemini's output:

•Check for security vulnerabilities (XSS, injection)
•Test functionality matches requirements
•Review code style consistency
•Verify dependencies are appropriate

Integration with Claude Code Task Primitive (v2.65.2)

Overview

Gemini CLI is now fully integrated with Claude Code Task Primitive. Every Gemini execution creates a traceable task in ~/.claude/tasks/<session>/tasks.json, making it visible in claude-task-viewer.

How It Works

code

User: /gemini-cli "Analyze authentication flow"
    ↓
Claude: TaskCreate → Task (subagent: gemini-cli)
    ↓
Hook: task-project-tracker.sh (PostToolUse)
    ↓
Task gets: project metadata, tool="gemini", session_id
    ↓
Global Sync: global-task-sync.sh → ~/.claude/tasks/<session>/tasks.json
    ↓
claude-task-viewer: Shows task with project filter

Automatic Task Creation

Tasks are created automatically via hooks when you invoke /gemini-cli:

Component	Role
`task-project-tracker.sh`	Adds `project` and `tool` fields to tasks
`global-task-sync.sh`	Syncs tasks to global `~/.claude/tasks/`
`project-backup-metadata.sh`	Tracks session by project

Task Metadata Structure

json

{
  "id": "1",
  "subject": "Gemini analysis: authentication flow",
  "description": "Use codebase_investigator to map auth dependencies",
  "activeForm": "Running Gemini analysis...",
  "status": "in_progress",
  "project": {
    "path": "/Users/.../my-repo",
    "repo": "owner/my-repo",
    "branch": "main"
  },
  "tool": "gemini",
  "metadata": {
    "model": "gemini-3-pro",
    "capabilities": ["google_web_search", "codebase_investigator"]
  }
}

Viewing Gemini Tasks

bash

# Open claude-task-viewer
npx claude-task-viewer --open

# Filter by project
# → Shows all gemini tasks with project metadata

# List tasks from CLI
ls -la ~/.claude/tasks/*/tasks.json
cat ~/.claude/tasks/ralph-*/tasks.json | jq '.tasks[] | select(.tool == "gemini")'

Integration with Adversarial Council

Gemini works seamlessly with adversarial:

bash

# 1. Create adversarial task
/adversarial --council "Design rate limiter"

# 2. Gemini runs as one of the council members
#    → Task shows: tool="adversarial", metadata.council_mode="council"

# 3. Both adversarial and gemini tasks are tracked
#    → Full visibility in claude-task-viewer

Cross-Validation Pattern

Gemini provides excellent second opinion when combined with Claude:

bash

# Claude writes code
# Then Gemini reviews
/gemini-cli "Review the auth module for security issues"

# Both executions tracked separately
# → Full audit trail in claude-task-viewer

Session Continuity

Gemini sessions are preserved across Claude Code sessions:

bash

# Session stored in: ~/.claude/tasks/<session>/tasks.json

# List previous sessions
gemini --list-sessions

# Resume with task update
echo "continue analysis" | gemini -r 1

# Task automatically updated with new session_id

Web Search Grounding

Gemini's web search is also tracked:

bash

/gemini-cli "What are the latest React 19 features? Use Google Search."

# Task includes:
#   metadata.capabilities: ["google_web_search"]
#   → Visible in task viewer

Troubleshooting

Issue	Solution
Task not appearing in viewer	Check `task-project-tracker.sh` is registered in settings.json
Missing project metadata	Verify `project-backup-metadata.sh` ran on session start
Task sync failed	Check `~/.ralph/logs/global-task-sync.log`
Gemini session not tracked	Ensure `tool: "gemini"` is added by hook

Gemini CLI Integration Skill

What's New in v0.22.0 (December 2025)

When to Use This Skill

Ideal Use Cases

When NOT to Use

Quick Start

Prerequisites

Authentication

Enable Gemini 3 (Free Tier)

Core Commands

Basic Execution

Key Flags

Important Behavior Notes

Model Selection

Unique Gemini Capabilities

1. google_web_search

2. codebase_investigator

3. save_memory

Extensions (v0.22.0+)

Conductor Extension

Endor Labs Extension

List Extensions

Integration Patterns

Pattern 1: Generate-Review-Fix Cycle

Pattern 2: Background Execution

Pattern 3: Cross-Validation with Claude

Pattern 4: Session Continuity

JSON Output Processing

Configuration

Settings Location

Project Context (GEMINI.md)

Ignore Files (.geminiignore)

Quick Reference Commands

Rate Limit Strategies

Error Handling

Common Issues

Debug Mode

Validation After Generation

See Also

Integration with Claude Code Task Primitive (v2.65.2)

Overview

How It Works

Automatic Task Creation

Task Metadata Structure

Viewing Gemini Tasks

Integration with Adversarial Council

Cross-Validation Pattern

Session Continuity

Web Search Grounding

Troubleshooting