gh-robbyt-claude-skills-plugins-gemini/skills/cli/SKILL.md

name, description

name	description
cli	Orchestrate Gemini CLI (v0.17.0+) for tasks requiring current web information via Google Search, deep codebase analysis with codebase_investigator, second AI opinions on code quality/security, or parallel task processing. Trigger when user explicitly requests Gemini ("use Gemini", "ask Gemini") or when needing capabilities unique to Gemini.

Gemini CLI Integration

Leverage Gemini CLI for alternative AI perspectives and unique tools (Google Search, codebase_investigator).

Prerequisites

⚠️ This skill assumes Gemini CLI is already installed and authenticated.

If you haven't completed setup:

1. See references/commands.md for installation and authentication instructions
2. Complete the manual authentication setup (API key or OAuth)
3. Verify with: gemini "test" -o text

Claude Code will NOT configure authentication for you. This must be done manually before using this skill.

Quick Start

Verify installation:

command -v gemini

Basic pattern:

gemini "[prompt]" -o text 2>&1

⏱️ Response Time: Gemini may take several minutes to respond, especially for complex tasks involving file analysis, web search, or codebase investigation. Allow up to 10 minutes for responses before assuming a timeout. The CLI will show no output while processing.

Key flags:

• -o text: Human-readable output
• -o json: Structured output with token/tool stats
• -m [model]: Model selection (e.g., gemini-2.5-flash for faster tasks)

Troubleshooting

Command Approval Issue

Problem: Gemini hangs with no output when asked to execute commands.

Cause: Gemini requires explicit user permission for any command it runs. When Claude asks Gemini to "run X command", Gemini waits for user approval and appears to hang.

Solution: Run commands via Claude's Bash tool first, then pass the output or file paths to Gemini.

Bad Pattern (hangs waiting for approval):

gemini "Run git diff --cached and review the changes" -o text

Good Pattern (runs commands first, then passes to Gemini):

# 1. Get the diff using Bash tool
git diff --cached > /tmp/claude/changes.diff

# 2. Pass file path to Gemini
gemini "Review the git diff at /tmp/claude/changes.diff and provide feedback" -o text

Alternative (pass content directly):

# 1. Get output via Bash
diff_output=$(git diff --cached)

# 2. Save to file and reference it
echo "$diff_output" > /tmp/claude/diff.txt
gemini "Review /tmp/claude/diff.txt for code quality issues" -o text

Sandbox Permission Error (EPERM)

Problem: Error when running gemini commands from Claude Code:

Error: EPERM: operation not permitted, mkdir '/Users/[user]/.gemini/tmp/...'

Cause: Gemini CLI needs write access to ~/.gemini/tmp/ for chat recording. Claude Code's sandbox blocks this by default.

Solution 1 (Recommended): Use dangerouslyDisableSandbox: true when calling gemini via Bash tool:

# In Claude Code, when using Bash tool to run gemini:
dangerouslyDisableSandbox: true

Solution 2: Add ~/.gemini/tmp to sandbox allowlist:

1. Run /sandbox command in Claude Code
2. Add ~/.gemini/tmp to the filesystem write allowlist
3. Restart Claude Code

Note: This error only affects Claude Code's sandboxed execution. Running gemini directly from your terminal works without these workarounds.

Working with Files

Gemini can read files directly from disk. Tell Gemini the file path instead of embedding file content in the prompt.

Preferred Pattern (File Path)

gemini "Please review the bash script at path/to/file.sh for syntax errors" -o text

Avoid This Pattern (Embedding Content)

# DON'T: Shell escaping can corrupt file content
gemini "Review this script: $(cat path/to/file.sh)" -o text

Why file paths are better:

• Avoids shell escaping issues (spaces in [@] become [ @], quotes get mangled)
• Preserves exact file content without interpretation
• More efficient for large files
• Clearer intent in prompts

File Operation Examples

Single file review:

gemini "Review plugins/foo/test.sh for bash best practices" -o text

Multi-file analysis:

gemini "Compare the test patterns in plugins/python-formatter-black/tests/test.sh and plugins/go-formatter/tests/test.sh" -o text

Directory analysis:

gemini "Analyze all Python files in src/ directory for security issues" -o text

Core Workflows

1. Code Generation

gemini "Create [description] with [features]. Output complete file content." -o text

2. Code Review

# Provide file path - Gemini will read it directly
gemini "Review path/to/file.js for: 1) features, 2) bugs/security issues, 3) improvements" -o text

3. Test Generation

gemini "Generate [Jest/pytest] tests for [file]. Focus on [areas]." -o text

4. Architecture Analysis (Unique to Gemini)

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

5. Web Research (Unique to Gemini)

gemini "What are the latest [topic]? Use Google Search." -o text

Gemini's Unique Capabilities

These tools are only available through Gemini:

• google_web_search: Real-time Google Search for current info
• codebase_investigator: Deep architectural analysis and dependency mapping
• save_memory: Cross-session persistent memory

Rate Limits

Free tier: 60 requests/min, 1000/day. CLI auto-retries with backoff. Use -m gemini-2.5-flash for lower-priority tasks.

Validation

Always verify Gemini's output:

• Security vulnerabilities (XSS, injection)
• Functionality matches requirements
• Code style consistency
• Appropriate dependencies

JSON Output Parsing

When using -o json, parse structured response:

{
  "response": "actual content",
  "stats": {
    "models": { "tokens": {...} },
    "tools": { "byName": {...} }
  }
}

Configuration

Optional: Create .gemini/GEMINI.md in project root for persistent context Gemini auto-reads.

Session management:

gemini --list-sessions               # List sessions
echo "follow-up" | gemini -r 1 -o text   # Resume by index

Reference Documentation

For detailed guidance, see:

• references/commands.md: Complete CLI flags and options reference
• references/patterns.md: Advanced integration patterns (Generate-Review-Fix, background execution, model selection, validation pipelines)
• references/templates.md: Reusable prompt templates for common operations
• references/tools.md: Gemini's built-in tools documentation and comparison with Claude Code

Load these references when you need deeper knowledge about specific aspects of Gemini CLI usage.