---
name: agy
description: "Route a task to the Google Antigravity CLI (agy) for an independent second model (sibling of grok): different-vendor second opinion, adversarial verification, code review of files/diffs, vision, live web search, one-shot text answers. Triggers: ask gemini, ask agy, agy verify, agy review, agy."
---

# AGY — Antigravity CLI capability router

Claude shells out to the locally-installed **Google Antigravity CLI** (`agy`, a
native Go binary at `~/AppData/Local/agy/bin/agy`, v1.0.16) 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). Modes verified on this
machine (2026-07-02): text, verify, review (single file / file set / git diff),
image-analyze (vision), search (live web search + source URLs).

> **REWIRED 2026-07-02 — `agy` replaces the old `gemini` npm CLI.** The former
> Google `gemini` CLI (npm `@google/gemini-cli`) stopped working on this account
> with a Cloud-project eligibility error (`throwIneligibleOrProjectIdError` — it
> demanded a `GOOGLE_CLOUD_PROJECT` the personal account couldn't provide). The
> Antigravity CLI (`agy`) uses Antigravity's OWN auth and works headless with no
> project ID. The wrapper is `scripts/ask-agy.sh`; `scripts/ask-gemini.sh` is kept
> as a thin **deprecated shim** that `exec`s ask-agy.sh so old references still work.

**Backend models (multi-vendor, `--model`):** `agy models` lists them — Gemini 3.5
Flash (Low/Medium/High), Gemini 3.1 Pro (Low/High), Claude Sonnet 4.6 (Thinking),
Claude Opus 4.6 (Thinking), GPT-OSS 120B. `text` uses the CLI default (Flash, fast);
`verify`/`review*`/`image-analyze`/`search` pin the strong model
`Gemini 3.1 Pro (High)`. Override any mode with `AGY_MODEL="<friendly name>"`.

**Auth:** Antigravity's own login (`~/.gemini/antigravity-cli/`) — **no API key, no
`GOOGLE_CLOUD_PROJECT`**. If a call fails with an auth error, run `agy` interactively
once to sign in, then retry.

## The wrapper

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

Authoritative headless flags (from `agy --help`, Go flag package — the web docs at
antigravity.google/docs/cli are JS-rendered SPAs and unreadable by fetch tools, so
`--help` is the source of truth): `-p/--print/--prompt` runs one prompt and prints
the response (**the prompt is the flag's VALUE and MUST be last** — a bare `-p --model`
makes "--model" the prompt); `--model "<name>"`; `--add-dir <dir>` (repeatable, gives
the file tools access to a review/vision target); `--dangerously-skip-permissions`
(auto-approve tool calls — without it print mode HANGS on an approval prompt);
`--print-timeout <dur>` (default 5m). There is **no JSON output flag** — stdout is
plain text/markdown, so the wrapper does no JSON parsing.

| Mode | Usage | What it does |
|------|-------|--------------|
| `text` | `ask-agy.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-agy.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-agy.sh review <file-path> ["<instructions>"]` | agy reads the file itself (copied into an `--add-dir` workspace) 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-agy.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-agy.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-agy.sh image-analyze <image-path> ["<question>"]` | **Vision** — agy reads the image (via `--add-dir`) and describes/answers about it. Pinned to the strong model. Path absolute or repo-relative; spaces OK. |
| `search` | `ask-agy.sh search "<query>"` (or `search --prompt-file <path>`) | **Live web search** (sibling of `grok xsearch`) — agy searches the web and returns the answer **with source URLs**. |
| `raw` | `ask-agy.sh raw <agy args...>` | Escape hatch — passes args straight to `agy`. |

The script runs `agy` headless (`--dangerously-skip-permissions ... -p "<prompt>"`),
captures plain-text stdout (no JSON — agy has no structured-output mode), keeps stderr
separate for diagnostics, and retries a couple times with backoff on an empty turn.
For review/vision it copies the target into a temp dir and `--add-dir`s it so agy's
file tools can read it regardless of location/spaces.

> [!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 the CLI **default** (Gemini 3.5 Flash) — fast, cheap.
- `verify` / `review*` / `image-analyze` / `search` pin the strong model
  **`Gemini 3.1 Pro (High)`** via `--model`.
- Override any mode with `AGY_MODEL="<friendly name>"` (exact strings from
  `agy models`, e.g. `AGY_MODEL="Claude Opus 4.6 (Thinking)"`).

### Vision

`image-analyze` copies the image into an `--add-dir` workspace and asks agy to read
and describe it (pinned to the strong model). Report-only — describes an image you
give it. Image/video **generation** stays [GROK](../grok/SKILL.md)'s lane
(`grok image` / `grok video`).

## Machine availability (fleet)

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

```json
"agy": { "installed": true,
         "binary": "C:/Users/guru/AppData/Local/agy/bin/agy",
         "auth": "antigravity", "is_fleet_host": true,
         "capabilities": ["text","verify","review","review-files","review-diff","image-analyze","search"] }
```

- If `agy.installed` is `false` (or the block is absent), `ask-agy.sh` exits **3**
  with routing guidance instead of failing obscurely. Claude on such a machine
  should NOT attempt local agy. (The wrapper falls back to the legacy `.gemini`
  block if `.agy` is absent, for machines mid-migration.)
- **Fleet host: `GURU-5070`** (agy installed + Antigravity-authed). When others get
  it, install the Antigravity CLI, run `agy` once to sign in, then set their
  `identity.json` `agy` block (and update this line).

**Remote routing (NOT yet wired):** a non-host machine cannot run agy locally. Route
the request to the host (`GURU-5070`) — same pending channels as Grok (GuruRMM agent
exec, a relay, or a coord-API job queue). Until built, AGY requests originate on the host.

## When to route to AGY

- **Independent verification** — a different vendor/model to red-team a Claude
  finding or design before acting on it. (`verify`)
- **Second-model code review** — agy reads and critiques a file, a set, or a diff
  independently of Claude. (`review`, `review-files`, `review-diff`)
- **Diverse drafts / second opinion** — alternative phrasing or approach. (`text`)
- **Live web facts** — current info past Claude's cutoff, with source URLs. (`search`)

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. The wrapper
  runs agy read-only in intent (review prompts say "do not modify anything"); do not
  point it at write tasks in this repo.
- Image / video **generation** → GROK's lane. AGY vision is read/analyze only.
- **Never** delegate unsupervised destructive / production actions to agy. Always
  review its output before acting — like Grok, it can over-claim.

## Safety / operational notes

- `--dangerously-skip-permissions` is passed so print mode never HANGS on a tool
  approval prompt (headless). It only lets agy run its own read/search tools inside
  its sandbox to answer — the wrapper never asks it to write to this repo.
- The prompt is passed as the VALUE of `-p` and MUST be last on the command line;
  all other flags (`--model`, `--add-dir`, `--print-timeout`) come before it.
- Prompts are built in a temp file and read with `-p "$(cat <file>)"` (avoids
  quote hell); stdin is closed (`</dev/null`) so `-p` never waits on stdin.
- Output is plain text/markdown. Tool-using turns (review/search/vision) may emit a
  line or two of tool narration before the answer; the prompts ask agy to suppress
  it, and residual narration is harmless.

## Reference
- Binary: native Go `agy` (`C:/Users/guru/AppData/Local/agy/bin/agy`; on PATH). The
  wrapper auto-locates it, honors `AGY=`, or reads `identity.json` `agy.binary`.
- Version 1.0.16. Auth: Antigravity login (`~/.gemini/antigravity-cli/`), no API key,
  no `GOOGLE_CLOUD_PROJECT`.
- Headless contract: `agy [--model "<name>"] [--add-dir <dir>] --dangerously-skip-permissions -p "<prompt>"` → plain-text answer on stdout (no JSON).
- Migration: replaced the `gemini` npm CLI 2026-07-02 (that CLI hit
  `throwIneligibleOrProjectIdError`). `ask-gemini.sh` is a deprecated shim → `ask-agy.sh`.
- Sibling router: [`grok`](../grok/SKILL.md) (image/video/live-data + second opinion).
