Mike Swanson
e09ff5dc9b
Audited the Gemini wrapper against the CLI's bundled help/README (gemini 0.45.2),
same pass as the grok skill. Unlike grok, found NO functional bug:
- All flags correct and real: -p, --skip-trust, -o json, --approval-mode plan|yolo,
--include-directories, -m (verified against `gemini --help`).
- JSON schema {session_id, response, stats} -> .response confirmed via live probe.
- Pinned model gemini-3.1-pro-preview STILL VALID (live PONG); the GA-looking
gemini-3.1-pro and gemini-3-pro both ModelNotFoundError -> keep the -preview suffix.
- Default text model is gemini-3.1-flash-lite (by design; verify/review/search/image
pin pro). No thought-suppression flag exists in the CLI, so the gresponse() reasoning
-leak scrub stays (justified, signature-gated, byte-exact otherwise).
- Live `search` re-validated end-to-end through the wrapper (58s, grounded sources).
Only change: version 0.45.1 -> 0.45.2 in SKILL.md + wrapper header, and refreshed the
verified-date notes with the 2026-06-17 re-validation findings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
159 lines
10 KiB
Markdown
159 lines
10 KiB
Markdown
---
|
|
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: an
|
|
independent, different-vendor SECOND OPINION or adversarial VERIFICATION of a
|
|
Claude finding/design before acting on it, a Gemini code REVIEW of a file /
|
|
set of files / git diff, and one-shot Gemini TEXT answers. Invoke on:
|
|
"ask gemini", "gemini verify", "second opinion from gemini", "gemini review",
|
|
"agy ...". Gemini is an independent second model (and Google-ecosystem reach),
|
|
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).
|