---
name: agy
description: >
  Route a task to the official Google Gemini CLI for an independent second model — a
  sibling of the `grok` second-opinion router. Use for a different-vendor SECOND OPINION
  or adversarial VERIFICATION of a Claude finding/design, a Gemini code REVIEW of files /
  a git diff, and one-shot Gemini TEXT answers. Triggers: ask gemini, gemini verify,
  second opinion from gemini, gemini review, agy ... A second model, NOT a replacement
  for Claude's own codebase work.
---

# AGY — Gemini capability router

Claude shells out to the locally-installed **Google Gemini CLI** (`gemini`, npm
global, v0.45.2) for a genuinely independent, different-vendor second model.
AGY is the sibling of [`grok`](../grok/SKILL.md): both are second-opinion /
review routers. Use whichever you want a second model from (or both, to triangulate).
Verified working on this machine (2026-06-05; re-validated 2026-06-17 against the
CLI's bundled help/README — JSON schema, all flags, pinned model, and live search
all confirmed): text, verify, review (single file / file set / git diff),
image-analyze (vision input), search (live Google web search). All KEYLESS — they
work on Google OAuth, no API key.

**Auth:** Gemini uses **Google login (OAuth)** — **no API key**. Creds live at
`~/.gemini/oauth_creds.json`. If calls fail with an auth error, run `gemini`
interactively once and choose **"Login with Google"**, then retry.

## The wrapper

```
bash "$CLAUDETOOLS_ROOT/.claude/skills/agy/scripts/ask-gemini.sh" <mode> ...
```

| Mode | Usage | What it does |
|------|-------|--------------|
| `text` | `ask-gemini.sh text "<prompt>"` or `text --prompt-file <path>` | One-shot text answer from an independent model. `--prompt-file` for long content (review/summarize a doc). Default model routing. |
| `verify` | `ask-gemini.sh verify "<claim/finding>"` or `verify --prompt-file <path>` | Adversarial second opinion — Gemini tries to REFUTE / find gaps, returns a verdict + reasons. Pinned to the strong model. |
| `review` | `ask-gemini.sh review <file-path> ["<instructions>"]` | Gemini reads the file itself (its `read_file` tool, read-only `plan` mode) and reviews it. Path resolution: absolute, CWD-relative, or relative to `$CLAUDETOOLS_ROOT` — **see the path gotcha below**. Spaces OK. Works even on gitignored files. |
| `review-files` | `ask-gemini.sh review-files [-i "<instr>"] <f1> [f2 …]` | Review a **set** of files together (cross-file consistency, multi-file change). Same path resolution as `review` (**see gotcha below**); spaces OK. No code passed as a shell arg. |
| `review-diff` | `ask-gemini.sh review-diff [-C <repo-dir>] [-i "<instr>"] <gitref> [-- <pathspec>]` | Review a **git diff** (`git diff <gitref>` from `<repo-dir>`; default repo root, use `-C` for a submodule e.g. `-C projects/msp-tools/guru-rmm`). Diff goes via the prompt file; Gemini can `read_file` changed files for full context. |
| `image-analyze` | `ask-gemini.sh image-analyze <image-path> ["<question>"]` | **Vision** — Gemini `read_file`s the image and describes/answers about it. Pins the **pro vision model** (the default flash-lite router hallucinates image content). Path absolute or repo-relative; spaces OK. KEYLESS (works on OAuth). |
| `search` | `ask-gemini.sh search "<query>"` (or `search --prompt-file <path>`) | **Live Google web search** (sibling of `grok xsearch`) — Gemini uses its `google_web_search` tool and returns the answer **with source URLs**. KEYLESS (works on OAuth). |
| `raw` | `ask-gemini.sh raw <gemini args...>` | Escape hatch — passes args straight to `gemini`. |

The script runs Gemini headless with `-o json`, extracts the answer from
`.response` (parsing from the first `{` so the CLI's cosmetic warning lines are
ignored), and keeps stderr separate from the JSON so 429-backoff / warning noise
never corrupts the parse.

> [!WARNING]
> **Path gotcha for `review` / `review-files` (this has bitten us repeatedly).**
> A relative path is resolved against ONLY two roots: your **current directory**,
> and **`$CLAUDETOOLS_ROOT`** (`/d/claudetools`). It is NOT resolved against a
> submodule or any arbitrary subdir. So a path like `server/src/api/auth.rs` that
> is relative to a submodule (e.g. `projects/msp-tools/guru-connect/`) fails with
> `file not found` whenever your CWD isn't that submodule — even though the file
> obviously exists. **When reviewing files in a submodule or any non-root subtree,
> pass ABSOLUTE paths** (e.g. build the list with `find "$(pwd)/server/src" -name '*.rs'`
> from inside the submodule). Absolute paths always work regardless of CWD and
> tolerate spaces. (For `review-diff`, the analogous fix is `-C <submodule-dir>`.)

### Model

- `text` uses Gemini's **default routing** (currently a flash-tier model) — fast, cheap.
- `verify` / `review*` pin a **strong** model — `gemini-3.1-pro-preview` (verified
  available 2026-06-05, still valid 2026-06-17; the GA-looking `gemini-3.1-pro` and
  `gemini-3-pro` both `ModelNotFoundError`, so keep the `-preview` suffix).
- Override either with `GEMINI_MODEL=<id>` (e.g. `GEMINI_MODEL=gemini-2.5-pro`).
- `image-analyze` and `search` also pin the strong model (`GEMINI_MODEL` still honored).

### Multimodal: image INPUT works, image GENERATION does not

- **Image INPUT (vision) works on OAuth** — `image-analyze` reads an image with the
  pinned **pro vision model** and describes it correctly. The default flash-lite
  router HALLUCINATES image content, which is why the pro model is pinned.
- **Image GENERATION (nano-banana) does NOT work on OAuth** — it needs a Google AI
  Studio `NANOBANANA_API_KEY` plus the `nanobanana` extension. **Deferred** for now.
  Image/video **generation** stays [GROK](../grok/SKILL.md)'s lane (`grok image` /
  `grok video`); AGY's multimodal support is read/analyze only.

## Machine availability (fleet)

AGY is **per-machine** — the skill syncs fleet-wide but the `gemini` binary does
not. Availability is gated by `identity.json` (per-machine, gitignored):

```json
"gemini": { "installed": true,
            "binary": "C:/Users/guru/AppData/Roaming/npm/gemini",
            "auth": "oauth", "is_fleet_host": true,
            "capabilities": ["text","verify","review","image-analyze","search"] }
```

- If `gemini.installed` is `false` (or the block is absent), `ask-gemini.sh` exits
  **3** with routing guidance instead of failing obscurely. Claude on such a
  machine should NOT attempt local Gemini.
- **Fleet Gemini hosts: `GURU-5070`, `GURU-BEAST-ROG`** — machines with the Gemini
  CLI installed and Google-OAuth'd. When others get it, install
  `@google/gemini-cli`, run `gemini` once to log in with Google, then set their
  `identity.json` `gemini` block (and update this line).

**Remote routing (NOT yet wired):** a non-host machine cannot run Gemini locally.
To fulfill an AGY request from elsewhere, route it to the host (`GURU-5070`) —
same pending channels as Grok (GuruRMM agent exec, a relay, or a coord-API job
queue). Until that's built, AGY requests originate on the host machine.

## When to route to Gemini (AGY)

- **Independent verification** — a genuinely different vendor/model to red-team a
  Claude finding or design before acting on it. (`verify`)
- **Second-model code review** — have Gemini read and critique a file, a set of
  files, or a diff independently of Claude. (`review`, `review-files`, `review-diff`)
- **Diverse drafts / second opinion** — alternative phrasing or approach to
  compare. (`text`)
- **Google-ecosystem reach** — when a Google-side model/behavior is specifically
  wanted as the comparison point.

AGY and [GROK](../grok/SKILL.md) are sibling second-opinion routers. Pick one, or
run both and compare — disagreement between them is a strong signal to slow down.

## When NOT to

- Pure classify / extract / summarize → cheaper via Tier-0 Ollama (`.claude/OLLAMA.md`).
- Editing this repo's code → Claude's own agents own the codebase work. Gemini's
  `review*` modes are read-only (`--approval-mode plan`) by design; do not give
  Gemini write access to this repo.
- Image / video **generation** → that's GROK's lane (`grok image` / `grok video`),
  not Gemini here (nano-banana needs an API key — deferred). Gemini CAN analyze an
  image you give it (`image-analyze`, vision input on OAuth).
- **Never** delegate unsupervised destructive / production actions to Gemini.
  Always review Gemini output before acting on it — like Grok, it can over-claim.

## Safety / operational notes

- `--skip-trust` is REQUIRED for headless runs (the CWD isn't a Gemini "trusted
  folder"). Equivalent env: `GEMINI_CLI_TRUST_WORKSPACE=true`. The wrapper passes it.
- `review*` runs under `--approval-mode plan` (read-only): Gemini can read files
  but cannot modify anything. Do not change this to `auto_edit`/`yolo`.
- Gemini's `read_file` honors `.gitignore` **and** a workspace sandbox (only files
  inside the workspace are readable). The wrapper sidesteps both by copying each
  review target into a temp dir added via `--include-directories` — so review
  works for tracked, gitignored, and spaced-path files alike.
- Prompts are passed via `-p "$(cat <prompt-file>)"` built from a temp file, not
  inline shell args (avoids quote hell with long/structured content).
- stdin is always closed (`</dev/null`) so `-p` never hangs waiting on stdin.
- stdout carries two cosmetic warning lines ("True color (24-bit) support not
  detected", "Ripgrep is not available...") before output; JSON extraction from
  the first `{` ignores them. A transient `429 No capacity` backoff may appear on
  **stderr** and self-recovers — it does not affect the parsed answer.

## Reference
- Binary: npm global `gemini` (`C:/Users/guru/AppData/Roaming/npm/gemini` on the
  host; the npm global dir is on PATH). The wrapper auto-locates it or honors `GEMINI=`.
- Version 0.45.2. Auth: Google OAuth (`~/.gemini/oauth_creds.json`), no API key.
- Headless contract: `gemini -p "<prompt>" -o json --skip-trust </dev/null` →
  `{session_id, response, stats}`; answer is `.response`.
- Sibling router: [`grok`](../grok/SKILL.md) (image/video/live-data + second opinion).