---
name: gemini
description: Use when the user asks to run Gemini CLI for code review, plan review, or big context (>200k) processing. Ideal for comprehensive analysis requiring large context windows. Uses Gemini 3 Pro by default for state-of-the-art reasoning and coding.
title: gemini
canonical_url: https://skilld.dev/gh/davila7/claude-code-templates/gemini
last_updated: 2026-11-20T02:05:34.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [README.md](https://skilld.dev/api/skills-raw/davila7/claude-code-templates/gemini/README.md).
>
> If the user asked to install this Skill, run `npx skilld install davila7/claude-code-templates/gemini`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/gemini`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/davila7/claude-code-templates/gemini) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/gemini`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/gemini --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/gemini --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Gemini Skill Guide

## When to Use Gemini
- WHEN ASKED TO BE ACTIVATED
- **Code Review**: Comprehensive code reviews across multiple files
- **Plan Review**: Analyzing architectural plans, technical specifications, or project roadmaps
- **Big Context Processing**: Tasks requiring >200k tokens of context (entire codebases, documentation sets)
- **Multi-file Analysis**: Understanding relationships and patterns across many files

## ⚠️ Critical: Background/Non-Interactive Mode Warning

**NEVER use `--approval-mode default` in background or non-interactive shells** (like Claude Code tool calls). It will hang indefinitely waiting for approval prompts that cannot be provided.

**For automated/background reviews:**
- ✅ Use `--approval-mode yolo` for fully automated execution
- ✅ OR wrap with timeout: `timeout 300 gemini ...`
- ❌ NEVER use `--approval-mode default` without interactive terminal

**Symptoms of hung Gemini:**
- Process running 20+ minutes with 0% CPU usage
- No network activity
- Process state shows 'S' (sleeping)

**Fix hung process:**
```bash
# Check if hung
ps aux | grep gemini | grep -v grep

# Kill if necessary
pkill -9 -f "gemini.*gemini-3-pro-preview"
```

## Running a Task

1. Ask the user (via `AskUserQuestion`) which model to use in a **single prompt**. Available models:
   - `gemini-3-pro-preview` ⭐ (flagship model, best for coding & complex reasoning, 35% better at software engineering than 2.5 Pro)
   - `gemini-3-flash` (sub-second latency, distilled from 3 Pro, best for speed-critical tasks)
   - `gemini-2.5-pro` (legacy option, strong all-around performance)
   - `gemini-2.5-flash` (legacy option, cost-efficient with thinking capabilities)
   - `gemini-2.5-flash-lite` (legacy option, fastest processing)

2. Select the approval mode based on the task:
   - `default`: Prompt for approval (⚠️ ONLY for interactive terminal sessions)
   - `auto_edit`: Auto-approve edit tools only (for code reviews with suggestions)
   - `yolo`: Auto-approve all tools (✅ REQUIRED for background/automated tasks)

3. Assemble the command with appropriate options:
   - `-m, --model <MODEL>` - Model selection
   - `--approval-mode <default|auto_edit|yolo>` - Control tool approval
   - `-y, --yolo` - Alternative to `--approval-mode yolo`
   - `-i, --prompt-interactive "prompt"` - Execute prompt and continue interactively
   - `--include-directories <DIR>` - Additional directories to include in workspace
   - `-s, --sandbox` - Run in sandbox mode for isolation

4. **For background/automated tasks, ALWAYS use `--approval-mode yolo`** or add timeout wrapper. NEVER use `default` in non-interactive shells.

5. Run the command and capture the output. For background/automated mode:
   ```bash
   # Recommended: Use yolo for background tasks
   gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase for security issues"

   # Or with timeout (5 min limit)
   timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase"
   ```

6. For interactive sessions with an initial prompt:
   ```bash
   gemini -m gemini-3-pro-preview -i "Review the authentication system" --approval-mode auto_edit
   ```

7. **After Gemini completes**, inform the user: "The Gemini analysis is complete. You can start a new Gemini session for follow-up analysis or continue exploring the findings."

### Quick Reference

| Use case | Approval mode | Key flags |
| --- | --- | --- |
| Background code review | `yolo` ✅ | `-m gemini-3-pro-preview --approval-mode yolo` |
| Background analysis | `yolo` ✅ | `-m gemini-3-pro-preview --approval-mode yolo` |
| Background with timeout | `yolo` ✅ | `timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo` |
| Interactive code review | `default` | `-m gemini-3-pro-preview --approval-mode default` (interactive terminal only) |
| Code review with auto-edits | `auto_edit` | `-m gemini-3-pro-preview --approval-mode auto_edit` |
| Automated refactoring | `yolo` | `-m gemini-3-pro-preview --approval-mode yolo` |
| Speed-critical background | `yolo` ✅ | `-m gemini-3-flash --approval-mode yolo` |
| Cost-optimized background | `yolo` ✅ | `-m gemini-2.5-flash --approval-mode yolo` |
| Multi-directory analysis | `yolo` (if background) | `--include-directories <DIR1> --include-directories <DIR2>` |
| Interactive with prompt | `auto_edit` or `default` | `-i "prompt" --approval-mode <mode>` |

### Model Selection Guide

| Model | Best for | Context window | Key features |
| --- | --- | --- | --- |
| `gemini-3-pro-preview` ⭐ | **Flagship model**: Complex reasoning, coding, agentic tasks | 1M input / 64k output | Vibe coding, 76.2% SWE-bench, USD 2-4/M input |
| `gemini-3-flash` | Sub-second latency, speed-critical applications | 1M input / 64k output | Distilled from 3 Pro, TPU-optimized |
| `gemini-2.5-pro` | Legacy: Strong all-around performance | 1M input / 65k output | Thinking mode, mature stability |
| `gemini-2.5-flash` | Legacy: Cost-efficient, high-volume tasks | 1M input / 65k output | Best price (USD 0.15/M), thinking mode |
| `gemini-2.5-flash-lite` | Legacy: Fastest processing, high throughput | 1M input / 65k output | Maximum speed, minimal latency |

**Gemini 3 Advantages**: 35% higher accuracy in software engineering, state-of-the-art on SWE-bench (76.2%), GPQA Diamond (91.9%), and WebDev Arena (1487 Elo). Knowledge cutoff: January 2025.

**Coming Soon**: `gemini-3-deep-think` for ultra-complex reasoning with enhanced thinking capabilities.

## Common Use Cases

### Code Review (Background/Automated)
```bash
# For background execution (Claude Code, CI/CD, etc.)
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review focusing on:
   1. Security vulnerabilities
   2. Performance issues
   3. Code quality and maintainability
   4. Best practices violations"

# With timeout safety (5 minutes)
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review..."
```

### Plan Review (Background/Automated)
```bash
# For background execution
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Review this architectural plan for:
   1. Scalability concerns
   2. Missing components
   3. Integration challenges
   4. Alternative approaches"
```

### Big Context Analysis (Background/Automated)
```bash
# For background execution
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analyze the entire codebase to understand:
   1. Overall architecture
   2. Key patterns and conventions
   3. Potential technical debt
   4. Refactoring opportunities"
```

### Interactive Code Review (Terminal Only)
```bash
# ONLY use default mode in interactive terminal
gemini -m gemini-3-pro-preview --approval-mode default \
  "Review the authentication flow for security issues"
```

## Following Up

- Gemini CLI sessions are typically one-shot or interactive. Unlike Codex, there's no built-in resume functionality.
- For follow-up analysis, start a new Gemini session with context from previous findings.
- When proposing follow-up actions, restate the chosen model and approval mode.
- Use `AskUserQuestion` after each Gemini command to confirm next steps or gather clarifications.

## Error Handling

- Stop and report failures whenever `gemini --version` or a Gemini command exits non-zero.
- Request direction before retrying failed commands.
- Before using high-impact flags (`--approval-mode yolo`, `-y`, `--sandbox`), ask the user for permission using `AskUserQuestion` unless already granted.
- When output includes warnings or partial results, summarize them and ask how to adjust using `AskUserQuestion`.

## Troubleshooting Hung Gemini Processes

### Detection
```bash
# Check for hung processes
ps aux | grep -E "gemini.*gemini-3" | grep -v grep

# Look for these symptoms:
# - Process running 20+ minutes
# - CPU usage at 0%
# - Process state 'S' (sleeping)
# - No network connections
```

### Diagnosis
```bash
# Get detailed process info
ps -o pid,etime,pcpu,stat,command -p <PID>

# Check network activity
lsof -p <PID> 2>/dev/null | grep -E "(TCP|ESTABLISHED)" | wc -l
# If result is 0, process is hung
```

### Resolution
```bash
# Kill hung Gemini processes
pkill -9 -f "gemini.*gemini-3-pro-preview"

# Or kill specific PID
kill -9 <PID>

# Verify cleanup
ps aux | grep gemini | grep -v grep
```

### Prevention
- **ALWAYS use `--approval-mode yolo` for background/automated tasks**
- Add timeout wrapper for safety: `timeout 300 gemini ...`
- Never use `--approval-mode default` in non-interactive shells
- Monitor first run with `ps` to ensure process completes

## Tips for Large Context Processing

1. **Be specific**: Provide clear, structured prompts for what to analyze
2. **Use include-directories**: Explicitly specify all relevant directories
3. **Choose the right model**:
   - Use `gemini-3-pro-preview` for complex reasoning, coding tasks, and maximum analysis quality (recommended default)
   - Use `gemini-3-flash` for speed-critical tasks requiring sub-second response times
   - Use `gemini-2.5-flash` for cost-optimized high-volume processing
4. **Leverage Gemini 3's strengths**: 35% better at software engineering tasks, exceptional at agentic workflows and vibe coding
5. **Break down complex tasks**: Even with large context, structured analysis is more effective
6. **Save findings**: Ask Gemini to output structured reports that can be saved for reference

## CLI Version

Requires Gemini CLI v0.16.0 or later for Gemini 3 model support. Check version: `gemini --version`
