gemini

---
name: gemini
description: Use Gemini CLI from Codex for large-context codebase analysis, code review, multimodal file inspection, second-opinion investigations, and Gemini job management. Use when the user explicitly mentions Gemini, wants Gemini to review local changes, asks for a Gemini-powered architecture analysis, wants Gemini to inspect screenshots, images, audio, video, or PDF files, or needs setup, status, result, or cancel help for Gemini background jobs.
license: MIT
---

# Gemini

## Purpose

Use this skill to hand work to the local Gemini CLI without leaving Codex.

The skill supports:

- Gemini readiness checks and authentication guidance
- Large-context repository analysis
- Review of current git changes or a branch diff
- Screenshot and multimodal inspection
- Freeform delegation to Gemini
- Background job status, result lookup, and cancellation

## Core rule

Always route through the companion script:

```bash
node scripts/gemini-companion.mjs <subcommand> [options]
```

Do not call `gemini` directly for normal workflows. The only exception is telling the user to run `gemini` interactively when authentication is missing.

## Pick the right subcommand

- `setup`
  Use when the user asks whether Gemini is installed, authenticated, or ready.
- `review`
  Use when the user wants Gemini to review local code changes.
- `analyze`
  Use when the user wants a holistic architecture or codebase analysis.
- `ui-review`
  Use when the user wants Gemini to inspect screenshots or compare UI states against the implementation.
- `media`
  Use when the user wants Gemini to inspect an image, audio file, video, or PDF.
- `task`
  Use for freeform Gemini delegation that does not fit the dedicated subcommands.
- `status`
  Use when the user asks about running or recent Gemini jobs.
- `result`
  Use when the user asks for the stored output of a finished Gemini job.
- `cancel`
  Use when the user asks to stop a running Gemini job.

Detailed examples and subcommand selection notes live in [references/workflows.md](references/workflows.md).

## Execution rules

1. Check the request type and choose the narrowest matching subcommand.
2. Use foreground execution by default.
3. Use `--background` when the user explicitly asks for background execution, or when the request is obviously long-running:
   - broad codebase analysis
   - multi-file or branch-wide code review
   - large screenshot or multimodal investigations
4. Return the companion script output verbatim.
5. Do not paraphrase Gemini review findings before the user sees them.
6. Do not auto-fix problems reported by Gemini unless the user explicitly asks for fixes after the result is shown.

## Common command patterns

### Setup

```bash
node scripts/gemini-companion.mjs setup
```

If setup says Gemini CLI is missing, tell the user to install it:

```bash
npm install -g @google/gemini-cli
```

If setup says authentication is missing, tell the user to run:

```bash
gemini
```

or set `GEMINI_API_KEY`.

### Code review

Review the current working tree:

```bash
node scripts/gemini-companion.mjs review
```

Review against a base branch:

```bash
node scripts/gemini-companion.mjs review --base main
```

Background review:

```bash
node scripts/gemini-companion.mjs review --background --base main
```

### Codebase analysis

```bash
node scripts/gemini-companion.mjs analyze "Explain the service boundaries in this repository."
```

Limit analysis to one subtree:

```bash
node scripts/gemini-companion.mjs analyze --scope src/api "Review this API layer."
```

### UI review

Keep `@file` references in the Gemini prompt:

```bash
node scripts/gemini-companion.mjs ui-review "@screens/login.png review the login flow"
```

### Media inspection

```bash
node scripts/gemini-companion.mjs media "@demo.mp4 summarize the user flow"
```

### Freeform task delegation

```bash
node scripts/gemini-companion.mjs task "Investigate the retry logic in this repository."
```

Background task:

```bash
node scripts/gemini-companion.mjs task --background "Trace the authentication flow."
```

### Job management

```bash
node scripts/gemini-companion.mjs status
node scripts/gemini-companion.mjs result <job-id>
node scripts/gemini-companion.mjs cancel <job-id>
```

## Output handling

- Show stdout exactly as returned by the companion script.
- Preserve headings, bullet ordering, file paths, and code fences from Gemini output.
- If the command fails, show the full error output.
- For review workflows, keep the result read-only until the user explicitly asks you to act on it.

## Troubleshooting

If setup, auth, or job persistence fails, consult [references/troubleshooting.md](references/troubleshooting.md).