Gemini CLI Development

Use the Gemini CLI as a complementary AI tool for large context review and image generation tasks, orchestrated from within Claude Code.

Prerequisites

Install Gemini CLI

npm install -g @google/gemini-cli

Or via npx (no install):

npx @google/gemini-cli

Authentication (choose one)

Option 1: API Key (simplest)

export GEMINI_API_KEY="your-api-key-here"

Option 2: Google OAuth

gemini auth login

Option 3: Vertex AI

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"

Install nano-banana Extension

gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

For nano-banana image generation, also set (if using a separate key):

export NANOBANANA_GEMINI_API_KEY="your-key"

Critical Rules

Gemini is Advisory Only

Gemini MUST NEVER modify source files, configuration, or any project content. Its role in this plugin is strictly:

1. Advisor — review code, analyze logs, provide recommendations
2. Image creator — generate images, icons, patterns via nano-banana

Gemini's output is always returned to Claude Code for the user to act on. Gemini does not implement fixes, refactor code, bump versions, or make any changes. If Gemini suggests a fix, Claude Code presents the suggestion — the user decides whether to apply it.

For reviews, always use --sandbox mode to enforce read-only access:

gemini --sandbox -m gemini-3-pro-preview -p "Review this code..."

Never use --yolo for reviews. The --yolo flag auto-approves all tool calls including file writes. It is ONLY permitted for image generation via nano-banana (which requires tool approval for the generate command).

Always Use the CLI

Every task in this plugin MUST execute the Gemini CLI via Bash. The entire purpose of this plugin is to delegate work to Gemini — not to do it with Claude. If you find yourself reading files with Read/Grep/Glob and analyzing them, you are doing it wrong. Instead, pipe content directly to gemini -p in a single Bash command.

Core Usage: Headless Mode

The key integration pattern is Gemini's headless mode (-p flag), which accepts a prompt and returns output non-interactively. All content gathering and the gemini call should be a single piped Bash command:

# Simple prompt
gemini -m gemini-3-pro-preview -p "Explain this error: ..."

# Pipe file content for review
cat large-file.ts | gemini -m gemini-3-pro-preview -p "Review this code for bugs and security issues" 2>&1

# Pipe a directory of files
find src/ -name "*.ts" -type f | sort | while read f; do echo "=== FILE: $f ==="; cat "$f"; done | gemini -m gemini-3-pro-preview -p "Review this codebase" 2>&1

# Use sandbox mode (default for all reviews — read-only, no file writes)
gemini --sandbox -m gemini-3-pro-preview -p "Analyze this codebase"

Model Policy

Always use the preferred model first. Only fallback if it returns an error (quota, unavailable, capacity).

Task	Preferred Model	Fallback Model
Text reviews	gemini-3-pro-preview	gemini-2.5-pro
Image generation	gemini-3-pro-image-preview	gemini-2.5-flash-image

For image generation, always prepend NANOBANANA_MODEL=gemini-3-pro-image-preview to gemini commands (unless the user has set NANOBANANA_MODEL in their environment). For text reviews, use -m gemini-3-pro-preview.

If a model returns an error, retry with the fallback and inform the user which model was used.

# Text review (default)
gemini -m gemini-3-pro-preview -p "Your prompt here"

# Text review (fallback)
gemini -m gemini-2.5-pro -p "Your prompt here"

# Image generation (default)
NANOBANANA_MODEL=gemini-3-pro-image-preview gemini --yolo -p '/generate "prompt"'

# Image generation (fallback)
NANOBANANA_MODEL=gemini-2.5-flash-image gemini --yolo -p '/generate "prompt"'

Configuration

Gemini CLI uses GEMINI.md files (similar to CLAUDE.md) for project context:

# Create project context file
echo "# Project: My App\nStack: React, TypeScript, Node.js" > GEMINI.md

Settings file location: ~/.gemini/settings.json

Recommended Settings for Gemini 3 Pro

Gemini 3 Pro requires Preview Features to be enabled. Without this setting, -m gemini-3-pro-preview will fail with a model not found error. The SessionStart hook checks for this automatically.

Enable via CLI: Run gemini, then use the /settings command and enable Preview Features.

Enable via settings.json (~/.gemini/settings.json):

{
  "general": {
    "previewFeatures": true
  }
}

Recommended settings for optimal plugin integration:

{
  "general": {
    "previewFeatures": true,
    "enableAutoUpdate": true
  },
  "tools": {
    "disableLLMCorrection": true
  }
}

Model selection modes:

Mode	Setting	Models Used
Auto (Gemini 3)	/model → Auto (Gemini 3)	gemini-3-pro-preview, gemini-3-flash-preview
Auto (Gemini 2.5)	/model → Auto (Gemini 2.5)	gemini-2.5-pro, gemini-2.5-flash
Manual	/model → Manual	Any available model

Note: The /model setting does NOT affect headless mode (-m flag). This plugin always uses -m gemini-3-pro-preview explicitly, so the /model setting only matters for interactive use.

Focused Skills

For specific tasks, use these focused skills:

Topic	Skill	Trigger Phrases
Large Context Review	gemini-cli:gemini-review	"review with gemini", "gemini code review", "analyze large file" (requires GEMINI_API_KEY or GOOGLE_API_KEY)
Image Generation	gemini-cli:gemini-images	"generate image", "create icon", "nano-banana", "gemini image"

Common Patterns

Delegating to Gemini for Large Context

When a task involves reviewing more context than is practical in the current session:

# Review an entire codebase directory (--sandbox ensures read-only)
find src/ -name "*.ts" -exec cat {} + | gemini --sandbox -m gemini-3-pro-preview -p "Review this TypeScript codebase for: 1) Security vulnerabilities 2) Performance issues 3) Code quality"

# Review a large log file
gemini --sandbox -m gemini-3-pro-preview -p "Summarize errors and patterns in this log" < /var/log/app.log

# Compare implementations
diff -u old.ts new.ts | gemini --sandbox -m gemini-3-pro-preview -p "Review this diff for correctness and potential regressions"

Using Gemini with File Context

# Pass specific files as context (--sandbox ensures read-only)
gemini --sandbox -m gemini-3-pro-preview -p "Given these files, suggest improvements" --file src/api.ts --file src/types.ts

# Review with project context
gemini --sandbox -m gemini-3-pro-preview -p "Review the architecture of this project" --file package.json --file tsconfig.json --file src/index.ts

Troubleshooting

For debugging issues, the gemini-troubleshoot agent can diagnose common problems:

• CLI not found
• Authentication failures
• Extension issues
• Model availability

Resources

• Gemini CLI docs: https://geminicli.com/docs/
• nano-banana extension: https://github.com/gemini-cli-extensions/nanobanana
• Gemini models: https://ai.google.dev/gemini-api/docs/models