@joeytheman/gemini-mcp-tool 1.3.0 → 2.3.0

package/README.md

@@ -15,7 +15,7 @@
 
 > **Fork Notice:** This project is a fork of [jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool), originally created by [jamubc](https://github.com/jamubc). We are grateful to the original author for their foundational work.
 
-This is a simple Model Context Protocol (MCP) server that allows AI assistants to interact with the [Gemini CLI](https://github.com/google-gemini/gemini-cli). It enables the AI to leverage the power of Gemini's massive token window for large analysis, especially with large files and codebases using the `@` syntax for direction.
+This is a simple Model Context Protocol (MCP) server that lets AI assistants ask Gemini through Google's Antigravity CLI (`agy`). The primary use case is giving Codex, Claude Code, and other MCP clients a second opinion from Gemini on plans, implementations, code reviews, architecture tradeoffs, and large files using the `@` syntax.
 
 - Ask gemini natural questions, through claude or Brainstorm new ideas in a party of 3!
 
@@ -23,28 +23,66 @@ This is a simple Model Context Protocol (MCP) server that allows AI assistants t
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@joeytheman/gemini-mcp-tool/badge" alt="Gemini Tool MCP server" />
 </a>
 
-## TLDR: [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff)](#) + [![Google Gemini](https://img.shields.io/badge/Google%20Gemini-886FBF?logo=googlegemini&logoColor=fff)](#)
+## TLDR: [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff)](#) + [![Google Gemini](https://img.shields.io/badge/Google%20Gemini-886FBF?logo=googlegemini&logoColor=fff)](#) + [![Antigravity (agy)](https://img.shields.io/badge/Antigravity%20%28agy%29-4285F4?logo=google&logoColor=fff)](#)
 
 
-**Goal**: Use Gemini's powerful analysis capabilities directly in Claude Code to save tokens and analyze large files.
+**Goal**: Use Gemini's analysis capabilities directly from Codex or Claude Code for reviews, critiques, and large-file questions.
+
+## What's New in 2.2
+
+- **Gemini 4 Argon support** — `ask-gemini` and `brainstorm` now default to **Gemini 4 Argon (High)**. Argon Low and Medium are available as explicit overrides when listed by `agy models`. `live-pass` and `screen-review` continue to default to **Gemini 3.8 Flash (Medium)**.
+
+## What's New in 2.1
+
+- **`live-pass`** — hand a live UI verification to Gemini. It drives its own Playwright (web) or Maestro (iOS simulator) MCP server, captures each requested screen/state/viewport into an artifact directory inside the worktree under test, opens every PNG itself, and returns a PASS/FAIL/BLOCKED verdict with a sentence per frame. The caller never opens an image. The verdict is derived in code from the requested targets, so a frame Gemini forgot, a stale PNG, or an uncovered target fails the pass even when Gemini says PASS.
+- **`screen-review`** — a second pair of eyes on frames someone else captured (`mode: "review"`), or an action inventory of a route file before anything is built (`mode: "plan"`). Also text only.
+- **JSON envelopes for `ask-gemini`** — `outputFormat: "json"` returns agy's envelope: the conversation ID line, the response (or `structured_output` when you pass a `jsonSchema`), and a token-usage line. `conversationId` resumes an exact conversation and **errors** if agy silently started a different one.
+
+## What's New in 2.0.2
+
+- **Gemini 3.8 Flash support** — the default model is now **Gemini 3.8 Flash (High)** for strong coding and complex-analysis performance. Pass `model: "Gemini 3.8 Flash (Low)"` or `model: "Gemini 3.8 Flash (Medium)"` when latency matters more than the High reasoning budget. Gemini 3.1 Pro (Low/High) remains available as an explicit alternative when exposed by `agy models`.
+
+## What's New in 2.0
+
+Version 2.0 moves the Gemini backend from the retired Gemini CLI/API path to Google's **Antigravity CLI (`agy`)** and brings the MCP-facing `ask-gemini` workflow along with several capabilities:
+
+- **Antigravity backend** — Gemini is reached through `agy --print`.
+- **Opt-in response caching** — LRU cache (30-minute TTL, 10 MB max) for repeated queries, enabled with `AGY_CACHE_ENABLED=true`.
+- **Conversation resume** — continue the latest `agy` conversation or resume a specific one via the `resume` option (`--continue` / `--conversation <id>`).
+- **Extra workspace directories** — add directories to the Antigravity workspace with `includeDirectories` (maps to repeated `--add-dir`).
+- **Configurable print timeout** — bound long-running calls with `printTimeout` (for example `5m` or `90s`; maps to `--print-timeout`).
+- **Working directory control** — run `agy` from a chosen directory (or a drive root on Windows) via `workingDirectory`, supported by both `ask-gemini` and `brainstorm`.
+- **Structured change mode** — `OLD/NEW` edit suggestions Claude can apply directly, with automatic chunking and a `fetch-chunk` tool for large edit sets.
+
+**Removed:** there is no longer a Pro→Flash quota fallback, and legacy Gemini CLI flags (`outputFormat`, `extensions`, `debug`, `promptInteractive`, and `approvalMode` other than `yolo`) now return explicit unsupported-option errors.
 
 ## Prerequisites
 
 Before using this tool, ensure you have:
 
-1. **[Node.js](https://nodejs.org/)** (v18.0.0 or higher)
-2. **[Google Gemini CLI](https://github.com/google-gemini/gemini-cli)** installed and configured
+1. **[Node.js](https://nodejs.org/)** (v20.12.0 or higher)
+2. **Antigravity CLI (`agy`)** installed and configured
+
+Verify `agy` before adding the MCP server:
+
+```bash
+agy --version
+agy install
+agy models
+```
+
+The `ask-gemini` and `brainstorm` default requires `Gemini 4 Argon (High)` to appear in `agy models` (verified with agy 1.3.4). Google currently lists Argon access in Antigravity for **Google AI Ultra and Enterprise** accounts; see [model availability](https://antigravity.google/docs/models/). If Argon is missing, update Antigravity CLI and check your account's access. You can explicitly select an available Flash tier, such as `model: "Gemini 3.8 Flash (High)"`. The MCP server does not automatically fall back. `live-pass` and `screen-review` continue to require `Gemini 3.8 Flash (Medium)` for their default requests.
 
 
 ### One-Line Setup
 
 ```bash
-claude mcp add gemini-cli -- npx -y @joeytheman/gemini-mcp-tool
+claude mcp add gemini-feedback -- npx -y @joeytheman/gemini-mcp-tool
 ```
 
 ### Verify Installation
 
-Type `/mcp` inside Claude Code to verify the gemini-cli MCP is active.
+Type `/mcp` inside Claude Code to verify the gemini-feedback MCP is active.
 
 ---
 
@@ -54,7 +92,7 @@ If you already have it configured in Claude Desktop:
 
 1. Add to your Claude Desktop config:
 ```json
-"gemini-cli": {
+"gemini-feedback": {
   "command": "npx",
   "args": ["-y", "@joeytheman/gemini-mcp-tool"]
 }
@@ -76,7 +114,7 @@ Add this configuration to your Claude Desktop config file:
 ```json
 {
   "mcpServers": {
-    "gemini-cli": {
+    "gemini-feedback": {
       "command": "npx",
       "args": ["-y", "@joeytheman/gemini-mcp-tool"]
     }
@@ -91,7 +129,7 @@ If you installed globally, use this configuration instead:
 ```json
 {
   "mcpServers": {
-    "gemini-cli": {
+    "gemini-feedback": {
       "command": "gemini-mcp"
     }
   }
@@ -100,16 +138,16 @@ If you installed globally, use this configuration instead:
 
 ### Optional: Enable Response Caching
 
-To enable the LRU response cache for near-instant repeated queries, add the `GEMINI_CACHE_ENABLED` environment variable:
+To enable the LRU response cache for near-instant repeated queries, add the `AGY_CACHE_ENABLED` environment variable:
 
 ```json
 {
   "mcpServers": {
-    "gemini-cli": {
+    "gemini-feedback": {
       "command": "npx",
       "args": ["-y", "@joeytheman/gemini-mcp-tool"],
       "env": {
-        "GEMINI_CACHE_ENABLED": "true"
+        "AGY_CACHE_ENABLED": "true"
       }
     }
   }
@@ -127,10 +165,27 @@ Caching is disabled by default. When enabled, responses are cached with a 30-min
 
 After updating the configuration, restart your terminal session.
 
+## Live UI passes (setup)
+
+`live-pass` needs Gemini to have its own MCP servers registered with Antigravity CLI. Register them once:
+
+```bash
+agy mcp add playwright -- npx -y @playwright/mcp@latest --browser chromium --headless --isolated \
+  --codegen none --allow-unrestricted-file-access   # artifact dirs live inside each worktree, so no fixed --output-dir
+agy mcp add maestro /path/to/maestro mcp
+agy mcp list                         # playwright + maestro
+```
+
+`--allow-unrestricted-file-access` is what lets `browser_run_code_unsafe` read each target's capture file and `browser_evaluate` write its layout file in a worktree-local artifact directory; the capture file's `page.screenshot` writes the PNG itself. `--codegen none` keeps `@playwright/mcp` from echoing each capture file's code back into Gemini's history under "Ran Playwright code", which would add about 5.5k characters per frame. A web pass needs a `@playwright/mcp` with `browser_run_code_unsafe` (0.0.84 has it). The tool compensates: `artifactDir` must be inside `workingDirectory`, every frame is checked on disk (matching PNG or JPEG filename and file signature, fresh, non-empty, inside the artifact dir), and the working tree is diffed before and after the run.
+
+Add `.live-pass/` to the repository's `.gitignore` so frames never land in a commit; deleting the worktree then removes them. Add `.playwright-mcp/` too — the Playwright MCP server creates that directory in whatever it runs from, which the working-tree guard will otherwise report as a WARNING on every pass.
+
+A full pass can run for many minutes inside one MCP call. The server sends keepalive progress notifications every 25 seconds when the client passes a `progressToken`; raise your client's `MCP_TIMEOUT` if a pass outlives it, and consider calling `live-pass` from a small relay sub-agent so the orchestrating session stays free.
+
 ## Example Workflow
 
 - **Natural language**: "use gemini to explain index.html", "understand the massive project using gemini", "ask gemini to search for latest news"
-- **Claude Code**: Type `/gemini-cli` and commands will populate in Claude Code's interface.
+- **Claude Code**: Use `/ask-gemini` directly, or ask naturally for Gemini feedback.
 
 ## Usage Examples
 
@@ -146,9 +201,9 @@ After updating the configuration, restart your terminal session.
 - `use gemini to explain div centering`
 - `ask gemini about best practices for React development related to @file_im_confused_about`
 
-### Using Gemini CLI's Sandbox Mode (-s)
+### Using Antigravity Sandbox Mode
 
-The sandbox mode allows you to safely test code changes, run scripts, or execute potentially risky operations in an isolated environment.
+The sandbox mode maps to `agy --sandbox`, which runs with terminal restrictions enabled.
 
 - `use gemini sandbox to create and run a Python script that processes data`
 - `ask gemini to safely test @script.py and explain what it does`
@@ -159,29 +214,57 @@ The sandbox mode allows you to safely test code changes, run scripts, or execute
 
 These tools are designed to be used by the AI assistant.
 
-- **`ask-gemini`**: Execute Gemini CLI with full feature support including advanced flags, caching, and change mode.
-  - **`prompt`** (required): The analysis request. Use the `@` syntax to include file or directory references (e.g., `@src/main.js explain this code`) or ask general questions (e.g., `Please use a web search to find the latest news stories`).
-  - **`model`** (optional): The Gemini model to use. Defaults to `gemini-3-pro-preview`. Use `gemini-3-flash-preview` for faster responses.
-  - **`sandbox`** (optional): Set to `true` to run in sandbox mode for safe code execution.
+- **`ask-gemini`**: Ask Gemini through Antigravity CLI (`agy`) for plan review, implementation critique, code review, architecture feedback, debugging, and tradeoff analysis.
+  - **`prompt`** (required): The analysis request. Use the `@` syntax to include file or directory references (e.g., `@src/main.js review this implementation`) or ask general questions.
+  - **`model`** (optional): The Antigravity model to use. Defaults to `Gemini 4 Argon (High)`. Other verified options include `Gemini 4 Argon (Low)`, `Gemini 4 Argon (Medium)`, and `Gemini 3.8 Flash (Low/Medium/High)` (use the exact tier name, such as `Gemini 3.8 Flash (High)`). Availability depends on your CLI version and account; check `agy models`. Some accounts also expose `Gemini 3.1 Pro (Low)` and `Gemini 3.1 Pro (High)`.
+  - **`sandbox`** (optional): Set to `true` to pass `--sandbox`.
   - **`changeMode`** (optional): Enable structured change mode for edit suggestions that Claude can apply directly.
-  - **`yolo`** (optional): Auto-accept all actions (YOLO mode). Use with caution.
-  - **`approvalMode`** (optional): Fine-grained approval control: `default`, `auto_edit`, or `yolo`.
-  - **`outputFormat`** (optional): Control output format: `text`, `json`, or `stream-json`.
-  - **`includeDirectories`** (optional): Additional directories to include in workspace.
-  - **`debug`** (optional): Enable verbose logging for troubleshooting.
-  - **`promptInteractive`** (optional): Execute prompt and continue in interactive mode.
-  - **`extensions`** (optional): Filter specific file extensions.
-  - **`resume`** (optional): Resume previous session (use `latest` or session number).
-  - **`workingDirectory`** (optional): Working directory to run Gemini from. Use drive root (e.g., 'C:/' or 'D:/') on Windows to access files across drives.
+  - **`yolo`** (optional): Pass `--dangerously-skip-permissions`. Use with caution.
+  - **`includeDirectories`** (optional): Additional directories to include in the Antigravity workspace; maps to repeated `--add-dir`.
+  - **`printTimeout`** (optional): Pass `--print-timeout`: a duration such as `90s`, `15m`, `2h30m` or `2.5h`, or `0` for no limit; other values are rejected. The server stops agy 2 minutes after this limit, or after 2 hours when no limit is given.
+  - **`resume`** (optional): `true`, `latest`, or `continue` maps to `--continue`; any other string maps to `--conversation <id>`.
+  - **`conversationId`** (optional): Resume this exact conversation (`--conversation <id>`); wins over `resume`. The call fails with `CONVERSATION_NOT_RESUMED` when agy silently starts a different conversation — a stale ID only warns on stderr and would otherwise return an unrelated answer. IDs come from the `[GEMINI_CONVERSATION_ID=...]` line of a previous json call; a text call reports its ID only when it fails with an empty answer.
+  - **`outputFormat`** (optional): `"text"` (default) or `"json"`. `"json"` returns agy's envelope rendered as the conversation line, the answer, and a usage line. `"stream-json"` is unsupported.
+  - **`jsonSchema`** (optional): Inline JSON Schema passed to `--json-schema`, constraining the answer to `structured_output`. Requires `outputFormat: "json"`.
+  - **`effort`** (optional): `low`, `medium`, or `high`, passed to `--effort`. Tiered Gemini names already encode effort in the name, and agy rejects `--effort` for them — the rejection is surfaced verbatim.
+  - **`workingDirectory`** (optional): Working directory to run `agy` from. Use drive root (e.g., 'C:/' or 'D:/') on Windows to access files across drives.
+  - **Unsupported legacy options**: `extensions`, `debug`, `promptInteractive`, `outputFormat: "stream-json"`, and `approvalMode` except `approvalMode: "yolo"`.
+
+- **`live-pass`**: Delegate a live UI verification to Gemini. It drives its own Playwright or Maestro MCP server, captures the requested frames, looks at them, and returns text.
+  - **`targets`** (required): One `{screen, state, viewport, expected}` per frame the pass must produce; for `playwright`, `viewport` must be `WxH`, such as `390x844`. `expected` is what that state must show — for an intentional error/empty/offline state, name the reason text and the recovery affordance. The effective verdict is derived from this list: **any target that produced no frame fails the pass**, whether Gemini skipped it with a reason or never reported it at all. A skip explains missing evidence; it does not excuse it. Each target's screenshot filename is derived in code from its `screen`/`state`/`viewport`, so two targets can never be answered by one image — a reused file is reported as `DUPLICATE` and fails the pass.
+  - **`brief`** (required): Every fact Gemini needs, because the pass forbids it to read product code, tests, docs, tool schemas or the database, or to run git: the app's start URL or app id, any link a user arrives by (an invite, email or share link) with where it comes from, the served-branch marker, and per target the user path, the labels or testIDs on it, the seed account and ids, and how long toasts and pending states stay on screen. App specifics belong here, not in the tool. The pass opens the app once, at its start URL (or by launching it on a device). A target may begin at a link of its own only when the brief says the user arrives by that link and names where it comes from; that frame quotes the source in `link_source`, and the report prints it. Every other target is reached by taps from the previous screen (sign-in form, navigation taps, form submits; no scripted shortcuts), and any other URL in the brief is context, never a navigation target. A reload opens the current URL, and only where the brief makes it part of the path. A target whose path breaks is skipped with the step where it broke, and one whose fact is missing is skipped with `brief missing: <fact>`; either fails the pass. The branch and HEAD of `workingDirectory` are read in code and printed in the prompt as context: the pass is BLOCKED only when the app's served-branch marker contradicts them (a detached HEAD never contradicts a branch name).
+  - **`workingDirectory`** (required): Absolute path to the worktree under test. Used as agy's cwd and workspace root.
+  - **`driver`** (required): `playwright` or `maestro`.
+  - **`artifactDir`** (optional): Absolute path, strictly inside `workingDirectory`. Defaults to `<workingDirectory>/.live-pass/<timestamp>`, so deleting the worktree cleans up the frames. Add `.live-pass/` to the repo's `.gitignore`.
+  - **`publishCommand`** (optional): Shell command run **in code** after validation, with `{files}` replaced by the shell-quoted paths of the frames that validated OK; its stdout is returned as PR markdown. Never run on a BLOCKED pass.
+  - **`conversationId`** (optional): Resume the previous pass so Gemini reports deltas (`resolved`, `regressions`, `changes`) instead of a bare snapshot. The browser or simulator still starts fresh — resume only changes what Gemini remembers. Start fresh when the brief changed materially, after a BLOCKED pass, or after about three rounds (each resumed round roughly doubles input tokens).
+  - **`yolo`** (optional, default **true**): Without `--dangerously-skip-permissions`, headless agy denies the MCP tool calls and the pass is BLOCKED. The tool snapshots the working tree before and after — status lines *and* content hashes of every dirty file, since a file Gemini rewrites in a PR worktree was already modified before the run — and reports any change as a WARNING, including when the agy call itself fails.
+  - **`model`** (optional, default `Gemini 3.8 Flash (Medium)`), **`printTimeout`** (optional, default `15m`).
+  - **Capture files and layout checks** (`playwright` only): before agy starts, the tool writes one capture file per target next to its frame, `<frame>.capture.js`, and Gemini runs it with `browser_run_code_unsafe {filename}` once the state has settled. In one call it sets the target's viewport, measures how far the page or its largest shown scroller overflows (only scrollers inside an open `aria-modal` sheet count while one shows, and textareas never do), grows the viewport by that much and measures again, a few times at most, while the overflow keeps shrinking and up to 4000 px tall (a screen that still scrolls after that is shot as it stands), saves the PNG, runs a fixed layout snippet in the page at the shot's size, and restores the viewport. A failed restore is noted in the call's answer and never hides the capture's own result or error. Gemini then saves that snippet's result next to the frame as `<frame>.layout.json` with a one-line `browser_evaluate`. Neither snippet is in Gemini's prompt. A failed screenshot fails the capture, so Gemini skips the target; a failed layout step still keeps the frame and leaves the layout file "not run". The layout check lists horizontal page scroll, text spilling its box, clipped text, controls covered by something else (hit-testing only the part of a control its scroll containers show, and skipping controls under an open `aria-modal` sheet, and a control in a horizontal scroller only when what covers it belongs to that scroller's row: a sibling, or the row's edge control within the row's height), and controls cut off at the screen edge, each as `{kind, text, testID, rect}` (at most 50). A framework dev overlay (Expo's `#error-overlay` / `#error-toast`) is kept out of every check and reported once as `dev-overlay` when its host or anything inside it shows, including inside the host's shadow root as Expo draws it, with the largest shown box and its text, marking the frame as polluted. Text capped with `-webkit-line-clamp` or `text-overflow: ellipsis` (React Native Web's `numberOfLines`) is listed separately as "capped (line clamp / ellipsis)". The report's "Layout checks (measured in the page)" section shows each frame's entries, or "not run" when the file is missing, stale, outside `artifactDir`, malformed, or measured at another width than the frame. The snippet's readable source is `src/layout-check.snippet.js`; `npm run snippet:build` regenerates the minified constant, and `npm test` and the CI Chromium step fail when the two drift. The caller judges the entries; they never change the verdict.
+  - The usage line is followed by Gemini's model steps, read from agy's conversation store (`~/.gemini/antigravity-cli/conversations/<id>.db`), and per frame for a live pass. It prints `?` when the store can't be read.
+
+- **`screen-review`**: Have Gemini judge captured screens, or inventory a route before it is built.
+  - **`mode`** (required): `review` judges PNGs after a live pass; `plan` inventories a route file and returns no verdict.
+  - **`instructions`** (required): The caller's reviewer prompt, passed through verbatim so rule citations stay exact.
+  - **`workingDirectory`** (required): The checkout the instructions cite; used as agy's cwd so repository-relative rule paths resolve.
+  - **`images`** (review mode, required): Absolute PNG/JPEG paths that must exist. **`routeFile`** (plan mode, required): absolute path inside `workingDirectory`. Neither may contain whitespace — agy resolves an `@reference` up to the first space, so a spaced path would hang until `printTimeout`; the tool rejects it up front instead.
+  - **`context`** (optional): Composition contract, issue text, anything else the reviewer prompt cites.
+  - **`changedRoutes`** (optional, review mode): Repo-relative files the diff touched (from `git diff --name-only`). Gemini maps each image to the route file it shows, and a changed screen (under an `app/` directory) that no image shows makes the review REQUEST_CHANGES — partial screenshot coverage is as unreviewed as none. A changed file under `components/` only warns. The report prints a route → image coverage table.
+  - **`baseRef`** (optional, review mode): The git ref the diff is based on, such as `origin/main`. The tool resolves its merge base with HEAD in code and fails before calling Gemini when it does not resolve. Gemini may then run read-only `git diff <merge-base>...HEAD` (optionally `--name-only`, `-- <paths>`) and `git show <merge-base>:<path>`, so severity follows the branch's own diff (set `yolo: true`, since headless agy denies the shell otherwise); without it Gemini runs no git. Both modes bound Gemini's reads to the route file each image shows (or the plan's route file) and the components and primitives it renders, the changed files, the producer lines a capability check needs, and the cited rule files, READMEs and boards, and forbid running tests or npm and reading `node_modules` or release notes.
+  - **`conversationId`** (optional): Round 2 keeps round 1's visual analysis.
+  - **`model`** (optional, default `Gemini 3.8 Flash (Medium)`), **`printTimeout`** (optional, default `10m`).
+  - **`yolo`** (optional, default **false**): a review only reads. Set it to `true` when the instructions ask Gemini to read repository files that are not among the images — it reaches for a shell to do that, headless agy denies the shell, and the call fails naming the denied action.
 
 - **`brainstorm`**: Generate creative ideas with structured methodologies and domain context.
   - **`prompt`** (required): Brainstorming challenge or question to explore.
-  - **`model`** (optional): The Gemini model to use.
+  - **`model`** (optional): The Antigravity model to use. Defaults to `Gemini 4 Argon (High)`. Pass an exact model listed by `agy models` to override it.
   - **`methodology`** (optional): Framework to use: `divergent`, `convergent`, `scamper`, `design-thinking`, `lateral`, or `auto` (default).
   - **`domain`** (optional): Domain context (e.g., 'software', 'business', 'creative', 'research').
   - **`constraints`** (optional): Known limitations or requirements.
+  - **`existingContext`** (optional): Background information, previous attempts, or current state to build upon.
   - **`ideaCount`** (optional): Number of ideas to generate (default: 12).
   - **`includeAnalysis`** (optional): Include feasibility and impact analysis (default: true).
+  - **`workingDirectory`** (optional): Working directory to run `agy` from.
 
 - **`fetch-chunk`**: Retrieve cached chunks from large changeMode responses.
   - **`cacheKey`** (required): Cache key from initial changeMode response.
@@ -190,26 +273,35 @@ These tools are designed to be used by the AI assistant.
 - **`ping`**: Echo test message to verify server connection.
   - **`prompt`** (optional): Message to echo back.
 
-- **`Help`**: Display Gemini CLI help information.
+- **`Help`**: Display Antigravity CLI (`agy`) help information.
 
 ### Slash Commands (for the User)
 
 You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).
 
-- **/ask-gemini**: Execute Gemini CLI with advanced features and caching.
+- **/ask-gemini**: Ask Gemini through Antigravity CLI with caching and change mode.
   - **Example**: `/ask-gemini prompt:@src/ summarize this directory`
   - **With sandbox**: `/ask-gemini prompt:@script.py test this safely sandbox:true`
   - **With change mode**: `/ask-gemini prompt:Refactor this code changeMode:true`
-  - **Supports all flags**: yolo, approvalMode, outputFormat, debug, etc.
+  - **Supported backend flags**: model, sandbox, yolo, includeDirectories, printTimeout, resume, workingDirectory.
 
 - **/brainstorm**: Generate structured ideas with creative methodologies.
   - **Example**: `/brainstorm prompt:How can we improve user onboarding? methodology:design-thinking domain:software`
   - **Quick use**: `/brainstorm prompt:Ideas for a mobile app feature`
+  - **Supported flags**: model, methodology, domain, constraints, existingContext, ideaCount, includeAnalysis, workingDirectory.
+
+- **/live-pass**: Walk a running app with Gemini and get a text verdict with per-frame observations.
+  - **Example**: `/live-pass driver:playwright workingDirectory:/path/to/worktree brief:"Base URL http://localhost:8081; marker: footer BRANCH: my-branch" targets:[{"screen":"home","state":"default","viewport":"390x844","expected":"order list with one seeded order"}]`
+  - **Supported flags**: targets, brief, workingDirectory, driver, artifactDir, model, printTimeout, yolo, publishCommand, conversationId.
+
+- **/screen-review**: Judge captured frames, or inventory a route file before building it.
+  - **Example**: `/screen-review mode:review workingDirectory:/path/to/worktree images:["/path/to/.live-pass/run/home-default-390x844.png"] instructions:"<reviewer prompt>"`
+  - **Plan mode**: `/screen-review mode:plan workingDirectory:/path/to/worktree routeFile:/path/to/app/orders.tsx instructions:"<action inventory rules>"`
 
 - **/fetch-chunk**: Retrieve next chunk of a large changeMode response.
   - **Example**: `/fetch-chunk cacheKey:abc123 chunkIndex:2`
 
-- **/Help**: Display Gemini CLI help information.
+- **/Help**: Display Antigravity CLI help information.
   - **Example**: `/Help`
 
 - **/ping**: Test the MCP server connection.
@@ -219,7 +311,7 @@ You can use these commands directly in Claude Code's interface (compatibility wi
 
 This MCP server includes several performance optimizations:
 
-- **LRU Response Cache** (opt-in): Near-instant responses for repeated queries with 30-minute TTL and 10MB max size. Enable via `GEMINI_CACHE_ENABLED=true` env var.
+- **LRU Response Cache** (opt-in): Near-instant responses for repeated queries with 30-minute TTL and 10MB max size. Enable via `AGY_CACHE_ENABLED=true` env var.
 - **Efficient Command Execution**: O(n) array buffer performance for large outputs
 - **Smart Chunking**: Large changeMode responses are automatically chunked for better handling
 - **Progress Notifications**: Real-time progress updates during long-running operations

package/dist/__tests__/agyModelSteps.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agyModelSteps.test.d.ts.map

package/dist/__tests__/agyModelSteps.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agyModelSteps.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/agyModelSteps.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/agyModelSteps.test.js

@@ -0,0 +1,58 @@
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { agyConversationStore, countAgyModelSteps, formatModelSteps } from '../utils/agyModelSteps.js';
+const CONVERSATION = '6a157307-cd13-4652-8725-f3500c103f2b';
+const roots = [];
+function storeWithSteps(stepTypes) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agy-steps-'));
+    roots.push(root);
+    const store = agyConversationStore(CONVERSATION, root);
+    fs.mkdirSync(path.dirname(store), { recursive: true });
+    const rows = stepTypes.map((type, idx) => `insert into steps (idx, step_type) values (${idx}, ${type});`).join('');
+    execFileSync('sqlite3', [store, `pragma journal_mode=wal;create table steps (idx integer primary key, step_type integer not null default 0);${rows}pragma wal_checkpoint(truncate);`]);
+    for (const side of ['-wal', '-shm'])
+        fs.rmSync(`${store}${side}`, { force: true });
+    return root;
+}
+afterEach(() => {
+    for (const root of roots.splice(0))
+        fs.rmSync(root, { recursive: true, force: true });
+});
+describe('countAgyModelSteps', () => {
+    it("counts only agy's model steps (step_type 15), not the user turn or tool results", async () => {
+        const root = storeWithSteps([14, 15, 132, 15, 132, 15]);
+        await expect(countAgyModelSteps(CONVERSATION, root)).resolves.toBe(3);
+    });
+    it("reads agy's write-ahead-log store without leaving side files next to it", async () => {
+        const root = storeWithSteps([15, 15]);
+        const store = agyConversationStore(CONVERSATION, root);
+        await expect(countAgyModelSteps(CONVERSATION, root)).resolves.toBe(2);
+        expect(fs.readdirSync(path.dirname(store))).toEqual([path.basename(store)]);
+    });
+    it('is null when the conversation has no step store', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agy-steps-'));
+        roots.push(root);
+        await expect(countAgyModelSteps(CONVERSATION, root)).resolves.toBeNull();
+    });
+    it('is null for a conversation id that is not a uuid, without touching the filesystem', async () => {
+        await expect(countAgyModelSteps('../../etc/passwd')).resolves.toBeNull();
+    });
+});
+describe('formatModelSteps', () => {
+    it('divides the steps by the reported frames, to one decimal', () => {
+        expect(formatModelSteps(81, 6)).toBe('Gemini steps: 81 (13.5 per frame, 6 frames)');
+    });
+    it('says so when no frame was reported', () => {
+        expect(formatModelSteps(12, 0)).toBe('Gemini steps: 12, no frames');
+    });
+    it('prints the bare count for a review, which has no frames', () => {
+        expect(formatModelSteps(9)).toBe('Gemini steps: 9');
+    });
+    it("marks an unreadable step store with ?", () => {
+        expect(formatModelSteps(null, 3)).toBe("Gemini steps: ? (agy's step store was unreadable)");
+    });
+});
+//# sourceMappingURL=agyModelSteps.test.js.map

package/dist/__tests__/agyModelSteps.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agyModelSteps.test.js","sourceRoot":"","sources":["../../src/__tests__/agyModelSteps.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/ask-gemini.test.js

@@ -1,47 +1,58 @@
-import { describe, it, expect } from 'vitest';
-import { z } from 'zod';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+const mockExecuteAgyCLI = vi.fn();
+const mockExecuteAgyJson = vi.fn();
+vi.mock('../utils/agyExecutor.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        executeAgyCLI: (...args) => mockExecuteAgyCLI(...args),
+        executeAgyJson: (...args) => mockExecuteAgyJson(...args),
+    };
+});
+import { askGeminiArgsSchema, askGeminiTool } from '../tools/ask-gemini.tool.js';
 describe('ask-gemini Tool', () => {
     describe('Argument Schema Validation', () => {
-        const askGeminiArgsSchema = z.object({
-            prompt: z.string().min(1),
-            model: z.string().optional(),
-            sandbox: z.boolean().default(false),
-            changeMode: z.boolean().default(false),
-            chunkIndex: z.union([z.number(), z.string()]).optional(),
-            chunkCacheKey: z.string().optional(),
-            yolo: z.boolean().default(false),
-            approvalMode: z.enum(['default', 'auto_edit', 'yolo']).optional(),
-            outputFormat: z.enum(['text', 'json', 'stream-json']).optional(),
-            includeDirectories: z.union([z.string(), z.array(z.string())]).optional(),
-            debug: z.boolean().default(false),
-            promptInteractive: z.string().optional(),
-            extensions: z.union([z.string(), z.array(z.string())]).optional(),
-            resume: z.string().optional(),
-        });
         it('should accept valid minimal arguments', () => {
             const result = askGeminiArgsSchema.parse({ prompt: 'test prompt' });
             expect(result.prompt).toBe('test prompt');
             expect(result.sandbox).toBe(false);
             expect(result.changeMode).toBe(false);
         });
-        it('should accept all optional flags', () => {
+        it('should accept supported agy optional flags', () => {
             const result = askGeminiArgsSchema.parse({
                 prompt: 'test prompt',
-                model: 'gemini-3-flash-preview',
+                model: 'Gemini 3.8 Flash (Medium)',
                 sandbox: true,
                 changeMode: true,
                 yolo: true,
-                approvalMode: 'auto_edit',
-                outputFormat: 'json',
-                debug: true,
+                includeDirectories: ['src', 'tests'],
+                printTimeout: '10m',
+                resume: true,
+                workingDirectory: '/tmp/project',
             });
-            expect(result.model).toBe('gemini-3-flash-preview');
+            expect(result.model).toBe('Gemini 3.8 Flash (Medium)');
             expect(result.sandbox).toBe(true);
             expect(result.changeMode).toBe(true);
             expect(result.yolo).toBe(true);
+            expect(result.includeDirectories).toEqual(['src', 'tests']);
+            expect(result.printTimeout).toBe('10m');
+            expect(result.resume).toBe(true);
+            expect(result.workingDirectory).toBe('/tmp/project');
+        });
+        it('should accept legacy fields so implementation can return explicit unsupported errors', () => {
+            const result = askGeminiArgsSchema.parse({
+                prompt: 'test prompt',
+                approvalMode: 'auto_edit',
+                outputFormat: 'json',
+                debug: true,
+                extensions: ['ts', 'js'],
+                promptInteractive: 'continue after this',
+            });
             expect(result.approvalMode).toBe('auto_edit');
             expect(result.outputFormat).toBe('json');
             expect(result.debug).toBe(true);
+            expect(result.extensions).toEqual(['ts', 'js']);
+            expect(result.promptInteractive).toBe('continue after this');
         });
         it('should reject missing prompt', () => {
             expect(() => askGeminiArgsSchema.parse({})).toThrow();
@@ -89,6 +100,22 @@ describe('ask-gemini Tool', () => {
             });
             expect(result.extensions).toEqual(['ts', 'js']);
         });
+        it('should accept the json envelope arguments', () => {
+            const result = askGeminiArgsSchema.parse({
+                prompt: 'test',
+                outputFormat: 'json',
+                jsonSchema: '{"type":"object"}',
+                effort: 'medium',
+                conversationId: 'conv-abc',
+            });
+            expect(result.outputFormat).toBe('json');
+            expect(result.jsonSchema).toBe('{"type":"object"}');
+            expect(result.effort).toBe('medium');
+            expect(result.conversationId).toBe('conv-abc');
+        });
+        it('should reject an effort level agy does not accept', () => {
+            expect(() => askGeminiArgsSchema.parse({ prompt: 'test', effort: 'extreme' })).toThrow();
+        });
         it('should accept resume parameter', () => {
             const result = askGeminiArgsSchema.parse({
                 prompt: 'test',
@@ -96,6 +123,13 @@ describe('ask-gemini Tool', () => {
             });
             expect(result.resume).toBe('latest');
         });
+        it('should accept boolean resume parameter', () => {
+            const result = askGeminiArgsSchema.parse({
+                prompt: 'test',
+                resume: true,
+            });
+            expect(result.resume).toBe(true);
+        });
         it('should accept chunkIndex as number', () => {
             const result = askGeminiArgsSchema.parse({
                 prompt: 'test',
@@ -112,12 +146,6 @@ describe('ask-gemini Tool', () => {
         });
     });
     describe('Flag Combinations', () => {
-        const askGeminiArgsSchema = z.object({
-            prompt: z.string().min(1),
-            sandbox: z.boolean().default(false),
-            yolo: z.boolean().default(false),
-            approvalMode: z.enum(['default', 'auto_edit', 'yolo']).optional(),
-        });
         it('should allow sandbox with yolo', () => {
             const result = askGeminiArgsSchema.parse({
                 prompt: 'test',
@@ -127,7 +155,7 @@ describe('ask-gemini Tool', () => {
             expect(result.sandbox).toBe(true);
             expect(result.yolo).toBe(true);
         });
-        it('should allow approvalMode to override yolo', () => {
+        it('should allow legacy approvalMode through schema for executor validation', () => {
             const result = askGeminiArgsSchema.parse({
                 prompt: 'test',
                 yolo: true,
@@ -135,20 +163,54 @@ describe('ask-gemini Tool', () => {
             });
             expect(result.yolo).toBe(true);
             expect(result.approvalMode).toBe('auto_edit');
-            // Note: In actual implementation, approvalMode should take precedence
         });
     });
-    describe('Error Messages', () => {
-        const askGeminiArgsSchema = z.object({
-            prompt: z.string().min(1),
+    describe('json output', () => {
+        beforeEach(() => {
+            vi.clearAllMocks();
+            mockExecuteAgyJson.mockResolvedValue({
+                conversation_id: 'conv-abc',
+                status: 'SUCCESS',
+                response: 'plain answer',
+                structured_output: { ok: true },
+                num_turns: 1,
+                duration_seconds: 3,
+                usage: { input_tokens: 10, output_tokens: 2, total_tokens: 12 },
+            });
+        });
+        it('starts with the conversation line and renders structured output under a schema', async () => {
+            const result = await askGeminiTool.execute({
+                prompt: 'Return ok true',
+                outputFormat: 'json',
+                jsonSchema: '{"type":"object"}',
+                conversationId: 'conv-abc',
+            });
+            expect(result.startsWith('[GEMINI_CONVERSATION_ID=conv-abc]')).toBe(true);
+            expect(result).toContain('"ok": true');
+            expect(result).toContain('Usage:');
+            expect(mockExecuteAgyJson).toHaveBeenCalledWith('Return ok true', expect.objectContaining({ conversationId: 'conv-abc', jsonSchema: '{"type":"object"}' }), undefined);
+            expect(mockExecuteAgyCLI).not.toHaveBeenCalled();
+        });
+        it('renders the plain response when no schema was passed', async () => {
+            const result = await askGeminiTool.execute({ prompt: 'hi', outputFormat: 'json' });
+            expect(result).toContain('plain answer');
+            expect(result).not.toContain('"ok"');
+        });
+        it('uses the text path for the default output format', async () => {
+            mockExecuteAgyCLI.mockResolvedValue('text answer');
+            const result = await askGeminiTool.execute({ prompt: 'hi' });
+            expect(result).toContain('text answer');
+            expect(mockExecuteAgyJson).not.toHaveBeenCalled();
         });
+    });
+    describe('Error Messages', () => {
         it('should provide clear error for missing prompt', () => {
             try {
                 askGeminiArgsSchema.parse({});
             }
             catch (error) {
                 expect(error.issues[0].path).toContain('prompt');
-                expect(error.issues[0].message).toMatch(/required/i);
+                expect(error.issues[0].message).toMatch(/required|expected string/i);
             }
         });
         it('should provide clear error for empty prompt', () => {
@@ -157,7 +219,7 @@ describe('ask-gemini Tool', () => {
             }
             catch (error) {
                 expect(error.issues[0].path).toContain('prompt');
-                expect(error.issues[0].message).toMatch(/at least 1/i);
+                expect(error.issues[0].message).toMatch(/at least 1|>=1/i);
             }
         });
     });