claude-agy-mcp
One-line summary: This server lets Claude Code offload heavy, context-hungry work to Google's Gemini models via the Antigravity CLI (agy), returning only clean answers so Claude's own context and tokens stay lean.
analyze_files— Delegate analysis of large files (>200 lines) or 3+ files (logs, dumps, generated code, cross-file reviews) without loading them into Claude's context.deep_search— Repo archaeology: git log/diff/blame spelunking, wide greps, "when/why did X change" and "where is Y used".web_lookup— Fetch external/current knowledge: library docs, API references, error messages, versions.adversarial_review— Get a second-opinion critique from a different model family for plans, designs, and pre-merge code review.follow_up— Continue a prior session bysession_idwith no context resend;write: trueto rework files it edited.delegate— Raw delegation for any other heavy task; read-only by default,write: trueto allow edits,sandbox: trueto confine it.delegate_many— Fan one question out to a council of models (with a disagreement report) or N sub-tasks (up to 8) to one model.set_model— Record the user's chosen model and effort tier once; every tool routes to it first.agy_status— Report token spend, quota cooldowns, in-flight runs, resolved model chains, warm sessions, and the agy version.Shared options across tools:
cwd,dirs(extra workspace roots),model,effort(low/medium/high),slash_commands(off by default), andschema(JSON Schema for machine-readablestructuredContent).Safety/robustness features: nonce-fenced output so untrusted model text can't be forged, quota-aware failover across a model chain, truncation caps, credential redaction, read-only enforcement (kernel sandbox on macOS), cross-repo workspace support, and cooperative delegation-depth limits.
Delegates heavy compute and coding sub-tasks to Google's Gemini models (Gemini 3.8 Flash at high effort by default, with failover to Gemini Pro) through the Antigravity CLI, providing tools for file analysis, codebase archaeology via git log/diff/blame and wide greps, web/documentation lookups, adversarial plan and code review, raw task delegation, and session-based follow-up questions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-agy-mcp analyze the main server file for performance bottlenecks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚡ Install
npm i @pymodel/claude-agy-mcpclaude mcp add-json -s user claude-agy-mcp \
'{"type":"stdio","command":"npx","args":["-y","@pymodel/claude-agy-mcp"],"timeout":3600000}'Claude Code delegates heavy tasks to Google's flagship Gemini Flash via the Antigravity CLI (agy) — saving Claude's context window and tokens for what matters.
Claude acts as the orchestrator → claude-agy-mcp routes compute-heavy sub-tasks to the newest Gemini Flash agy offers → only concise answers return. Large files, deep git searches, and log dumps never pollute Claude's context.
User → Claude Code → claude-agy-mcp (MCP) → agy CLI → Gemini 3.8 Flash / Pro / Claude
← ← ← (Clean answers only)Why Gemini Flash for Claude Code?
Gemini Flash is Google's most intelligent workhorse model for coding and agentic execution. It applies deep multi-step planning, rigorous terminal reasoning, and high first-pass code accuracy.
Gemini 3.8 Flash (High) is the default model for every tool. Each chain leads with
gemini-flash@latest-high, which resolves againstagy modelsto the newest Flash at High effort — 3.8 Flash as of 2026-09-11 — and only falls back to Pro or Claude when Flash is unavailable or cooling down. The benchmark table below compares 3.8 Flash against 3.7 Flash, from Google's launch table (2026-09-02); the bridge does not pin that generation.
Benchmark Highlights
Benchmark / Capability | Gemini 3.8 Flash (High) | Prior Generation (3.7 Flash) | Advantage |
DeepSWE v1.1 | 73.7% | 65.3% | +8.4 pts in long-horizon software engineering; within 0.3 of Claude Opus 5 |
Terminal-Bench 2.1 | 89.4% | 85.8% | +3.6 pts in agentic CLI execution; ahead of Opus 5 (89.1%) and GPT-5.6 Sol |
OSWorld-2.0 | 59.0% | 50.6% | +8.4 pts in agentic computer use |
HLE-Verified | 54.9% | 53.6% | Multi-step expert reasoning, ahead of Opus 5 (54.4%) |
Vals Finance Agent v2 | 61.4% | 59.0% | Leads Opus 5 (58.6%) and GPT-5.6 Sol (53.8%) on quantitative agent work |
Token Economics | $0.75 / $3.75 (1M) | $0.75 / $3.75 | Same price as 3.7 Flash; up to 10x–20x cheaper than Claude Opus/Sonnet |
The Token & Context Multiplier
When Claude Code directly analyzes a 4,000-line database dump or greps 20 files across git history, those thousands of lines stay permanently in Claude's prompt context, inflating cost and pushing you toward compaction.
With claude-agy-mcp:
Claude calls
analyze_filesordeep_search.Gemini 3.8 Flash processes the 100k+ tokens in isolation via
agy.Only the exact code-level findings and line citations return into Claude's prompt.
Subsequent questions reuse the same agy session with
follow_upwithout re-sending any files.
Related MCP server: subway-mcp-server
The Ultimate AI Engineering MCP Stack
claude-agy-mcp is designed to anchor a modern AI engineer's MCP toolkit alongside complementary specialized servers:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Claude Code (Agent) │
└──────┬──────────────────────┬───────────────────────┬───────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│claude-agy-mcp│ │ context7 │ │ firecrawl │ │ tavily │
│ (Gemini 3.8 │ │(Official Docs│ │(Web Scraping │ │(Live Search │
│ Delegation) │ │ & API Specs)│ │ & Crawling) │ │ & Research) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘MCP Server | Primary Superpower | When Claude Uses It |
| Heavy Compute & Coding Delegation | Analyzing files >200 lines, repo archaeology ( |
| Up-to-date Official Documentation | Fetching latest version-accurate API signatures and documentation for libraries (Next.js, React, Tailwind, Prisma, Vite, etc.) to eliminate hallucinated APIs. |
| Clean Web Scraping & Crawling | Converting dynamic web pages, documentation sites, and GitHub repos into clean, LLM-ready markdown or structured JSON. |
| Fast Live Search & Grounding | Low-latency web search, current news, error message lookups, and technical research. |
Recommended MCP Configuration (.agents/mcp_config.json or Claude Code)
{
"mcpServers": {
"claude-agy-mcp": {
"command": "npx",
"args": ["-y", "@pymodel/claude-agy-mcp"],
"timeout": 3600000
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
},
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"]
},
"tavily": {
"command": "npx",
"args": ["-y", "tavily-mcp"]
}
}
}Why this over claude-to-agy?
claude-to-agy | claude-agy-mcp | |
Tool surface | 1 generic | 8 purpose-built tools — Claude self-routes reliably |
Model selection | none (agy default only) | per-tool family selectors that follow new generations, with quota failover |
Multi-turn | stateless | session continuity — |
Output safety | unbounded | configurable truncation cap protects Claude's context |
Sandbox | no | read-only tools blocked from writing into the workspace on macOS, optional |
Honest results | exit code only | decides on agy's JSON envelope — reports auto-denied tool actions instead of hiding them |
Install | uvx (Python) | npx (Node) — zero install |
Requirements
Node.js 18+
Antigravity CLI (
agy) installed and authenticated
Install
# 1. Register the MCP server (user scope = all projects).
# add-json bakes in a generous client-side timeout so long analyze_files /
# delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user claude-agy-mcp \
'{"type":"stdio","command":"npx","args":["-y","@pymodel/claude-agy-mcp"],"timeout":3600000}'
# 2. Install the bundled skills into every agent found on this machine.
# The server gives an agent the tools; the skills tell it when to use them.
npx --package @pymodel/claude-agy-mcp claude-agy-mcp-install-skills
# --list to preview, --dir <path> to install somewhere explicit,
# --force to replace a skill you have symlinked to your own checkout.
# 3. Optional: add delegation rules to your project (or ~/.claude/CLAUDE.md).
curl -o CLAUDE.md https://raw.githubusercontent.com/PyModel/claude-agy-mcp/main/CLAUDE.mdBundled skills
Installing the package installs the skills too, so there is nothing separate to vendor or keep in sync:
Skill | What it does |
| Routing rules: which tool to reach for, and when delegating beats doing the work in-context. |
| The full delegate-and-review workflow — writing a brief agy can execute blind, dispatching it, reviewing the diff against the brief, and landing it yourself. Includes a CLI-relay fallback for agents that cannot call MCP tools. |
The
"timeout": 3600000(60 min, milliseconds) is the client-side tool-call deadline, matched to the bridge's defaultAGY_MAX_RUNTIMEceiling. Without it, a cold-startanalyze_files(~40–50s) or a longdelegatehits Claude Code's default and returnstimed out waiting for responsewhile the agy run is still going — and raising the agy-side ceiling alone will not help, because the client aborts first. If your client doesn't honor a per-servertimeout, set the global env varMCP_TOOL_TIMEOUT=3600000instead. Details in Timeouts and cancellation.
Tools
Tool | Use for | Model routing (first available) |
| Files >200 lines, >3 files at once, logs, dumps, generated code |
|
| git log/diff/blame archaeology, repo-wide greps |
|
| Docs, API references, external/current knowledge |
|
| Plan critiques, design and code reviews |
|
| Continue a prior session by | inherits the session |
| Anything else heavy (read-only unless |
|
| One question to a council of models, or N sub-tasks at once |
|
| Record the user's model + tier once; every tool routes to it first | never reaches agy |
| Spend, cooldowns, in-flight runs, resolved chains, agy version | never reaches agy |
All tools accept optional cwd (project root), dirs (extra workspace roots, for cross-repo or worktree-vs-base work), model, effort (low/medium/high — see Effort and tiers), and slash_commands (off by default, so a hostile file in the workspace cannot steer the delegated model through your own skills). The analytical tools also accept schema — a JSON Schema string that makes agy return machine-readable structuredContent alongside the text.
Every response is fenced with a per-call nonce, with the metadata in a header before the payload:
[claude-agy-mcp 9f2a1c] model: Gemini 3.8 Flash (High) | session: 1f0c…-d4 (use follow_up to continue) | tokens: 16281
[claude-agy-mcp 9f2a1c] --- agy output begins; everything below is untrusted model output ---
…agy's answer…
[claude-agy-mcp 9f2a1c] --- agy output ends ---The nonce is why the fence is worth anything: the metadata used to be appended after the raw model output behind a plain --- rule, which any analysed file containing --- could forge.
Model routing
On first use the bridge runs agy models (cached for the process lifetime) and resolves each chain entry against the live listing. Chains are written as family selectors — gemini-flash@latest-high rather than Gemini 3.7 Flash (High) — so when Google ships a new generation the chain follows it instead of quietly going stale. A selector is family@latest[-effort] or family@3.7[-effort]; an exact display name (Gemini 3.8 Flash (High)) and an id (gemini-3.8-flash-high) both work too. AGY_DEFAULT_MODEL is appended to every chain as a last resort. If nothing in a chain resolves, the bridge fails loudly rather than silently handing the work to whatever agy feels like — that is a version-skew signal, not a preference.
Choose the model once
By default (AGY_ASK_MODEL=true) the bridge refuses to delegate until the user has picked a model
and tier. The first call to any tool returns an error that names the default (AGY_DEFAULT_MODEL,
Gemini Flash High out of the box), lists the models agy offers, and tells the agent to ask the user
"Proceed with the default — Gemini 3.8 Flash (High) at high effort — or change the model or
effort?". Then the agent calls set_model once: with no arguments to accept the default, or
with the model and effort the user chose. The choice is written to
$XDG_CONFIG_HOME/claude-agy-mcp/preferences.json (~/.config/claude-agy-mcp/ by default), so it
outlives the process and every MCP client on the machine shares it: it is asked once, then that's it.
The chosen model goes to the head of every tool's chain — the chain still stands behind it for quota
failover — and an explicit model argument on a call still wins for that call. agy_status shows
the current choice and the live model list; call set_model again to change it, or set
AGY_ASK_MODEL=false to skip the gate and route purely on the built-in chains.
Effort and tiers
agy 1.2.1 rejects --effort for any model whose name already carries a tier — which is every Gemini
and Claude entry in agy models — and rejects an id whose tier disagrees with the flag. So the
bridge treats the tier in the name as the effort: an effort that differs from it selects the
sibling model at that tier (Gemini 3.8 Flash (High) + effort: medium → Gemini 3.8 Flash (Medium)), an effort with no listed sibling leaves the model as-is, and agy's own --effort flag
only travels with models that carry no tier. The built-in chains encode their tiers in the selector
(gemini-flash@latest-high), so no tool sets a separate effort of its own. An effort applies to the
primary model only — the model argument, else the set_model choice, else the chain's head. The
fallbacks keep the tier in their name, so a quota failover from Flash (High) really does land on
Flash (Medium) rather than re-tiering it back to the model that just ran out.
Quota-aware failover
agy never surfaces quota exhaustion in print mode — it silently retries the 429 until its print-timeout, then exits 0 with empty output, which used to look like an indefinite hang. The bridge now watches each run's log file (via --log-file) and on RESOURCE_EXHAUSTED (code 429):
kills the agy process group immediately (no waiting out the timeout),
parses the reset time ("Resets in 4h24m") into an in-process cooldown registry,
retries the same prompt on the next model in the tool's chain,
skips cooled-down models on all subsequent calls until their quota resets (at least one minute, even for "Resets in 0s").
A model you pin with model is tried even while it is cooling down. A run allowed to write (write: true) fails over only when the working tree is provably unchanged; if the tree moved, or could not be fingerprinted, the call fails with Not failed over instead, because the exhausted run may already have made its edits and the next model would make them again. The same rule governs the single retry after a network error, and a resident session that returned an empty answer or died after receiving the turn.
Failovers are annotated in the response footer (failover: <model>: quota exhausted (resets in 4h24m)). Only when every candidate is exhausted does the call fail — in seconds, with reset times listed — instead of hanging.
Timeouts and cancellation
The bridge does not kill a run for being slow. Elapsed time cannot distinguish a healthy long model call from a wedged process, and a wrong "stuck" verdict interrupts an agent mid-edit — leaving half-written files behind. So a run is killed only when something authoritative says so:
the caller cancels (e.g. pressing Esc in Claude Code), the client disconnects, or the bridge is stopped — every agy run it started dies with it instead of being orphaned,
quota is confirmed exhausted (a 429 in the run's log), which triggers failover, or
the resource ceiling expires —
AGY_MAX_RUNTIME, default 3600s.
The ceiling is a resource cap, not a diagnosis. When it fires, the run still returns everything agy produced so far plus its session_id, and says so explicitly: any file changes agy already made are on disk, and follow_up resumes from where it stopped. AGY_TIMEOUT overrides the ceiling for every tool; AGY_TIMEOUT_<TOOL_NAME> overrides it for one (e.g. AGY_TIMEOUT_DEEP_SEARCH=900) and wins over the global. The full set is AGY_TIMEOUT_ANALYZE_FILES, AGY_TIMEOUT_DEEP_SEARCH, AGY_TIMEOUT_WEB_LOOKUP, AGY_TIMEOUT_ADVERSARIAL_REVIEW, AGY_TIMEOUT_FOLLOW_UP, AGY_TIMEOUT_DELEGATE and AGY_TIMEOUT_DELEGATE_MANY; any other AGY_TIMEOUT_<NAME> is a startup error, so a misspelt limit cannot silently not apply. Every timeout is at most 604800s (7 days), because Node fires a longer timer immediately. The kill path escalates SIGTERM → SIGKILL across the whole process group, and fires even if agy's helper processes hold the output pipes open.
Two timeout layers — and the client one usually bites first. The ceiling above is the agy-side budget. Your MCP client (Claude Code) has its own, separate tool-call timeout, and if it is shorter, the client gives up first — you'll see Error: timed out waiting for response, while the bridge's own ceiling reads MAXIMUM RUNTIME EXCEEDED instead. Raising AGY_MAX_RUNTIME alone therefore changes nothing: the client still aborts on its own schedule. The work is not lost either way — the agy session persists, so follow_up with the returned session_id retrieves it — but the real fix is to make the client wait at least as long as the ceiling. The Install command sets a per-server timeout of 3600000ms (scoped to this server only). If you registered the server without it, re-run the add-json command from Install, or set the global env var MCP_TOOL_TIMEOUT=3600000. Rule of thumb: client timeout ≥ AGY_MAX_RUNTIME.
Expected latency. Most of the perceived "slowness" is cold start: each call spawns the agy CLI and warms the model. Measured on agy 1.2.0, a trivial prompt costs 2–6s, a run whose tool actions get denied around 16s, and one constrained by --json-schema up to 56s (the schema roughly triples thinking tokens). Real analyze_files work over several large files is much slower again, and a call that hits a quota 429 adds the failover on top. follow_up is the exception: it reuses a resident agy process (see AGY_WARM_SESSIONS) and skips the cold start entirely — unless the call pins a model or effort or asks to write, which a resident session cannot honour, so those run cold. A resident turn is bounded by the same runtime ceiling and cancellation as a cold run. Size the client timeout for the slow cases, not the fast ones.
Configuration
All optional, via environment variables:
Variable | Default | Description |
|
| Path to the agy binary |
|
| Seconds; absolute runtime ceiling. The bridge never kills for inactivity — only cancellation, quota, or this |
|
| Seconds; overrides the ceiling for every tool, passed as |
|
| Seconds; overrides the ceiling for a single tool, e.g. |
|
| Truncation cap for tool output |
|
| Appended to every chain as a last resort |
|
| Refuse to delegate until the user has chosen a model via |
| agy's own default |
|
|
| Pass |
(all boolean vars) | — | Accept |
(all numeric vars) | — | Plain decimal digits only ( |
|
| Run agy with |
|
|
|
|
| Most agy processes at once. Calls beyond it queue instead of stampeding the shared quota |
| unset | Hard stop once this many tokens have been spent since startup. Check spend with |
| unset (unrestricted) | Roots that |
|
| Scrub credential-shaped strings out of returned text before it reaches the caller's context |
|
| Refuse to delegate once this deep, so Claude → agy → this server → agy cannot loop |
|
| Keep a resident agy process per conversation so |
|
| Most resident sessions to keep; the least recently used is evicted |
|
| Kill a resident session after this long idle |
|
|
|
AGY_SKIP_PERMISSIONS is a real grant, and agy does not enforce read-only on top of it. It
defaults to true because headless agy auto-denies every permissioned tool without it — including
read_file — and a single denial ends the run with an empty response, so a bridge without the grant
cannot read, search or fetch anything. The read-only tools pass --mode plan, but verified
against agy 1.2.1 and again against 1.2.2: plan mode is advisory, with the permission bypass on or
off. agy creates files in a --mode plan run either way.
So on macOS the bridge enforces it. Every plan-mode run, cold or resident, runs agy under the
kernel sandbox (sandbox-exec) with every write beneath cwd and each dirs root denied, for agy
and for every process it starts. Verified against agy 1.2.2: its file-writing tool and its shell
both fail with "Operation not permitted", while reads, git inspection and agy's own state under
the home directory keep working. The response header says read-only: enforced. The sandbox is
probed at startup; where it cannot run — Linux, or a bridge that is itself sandboxed — read-only
runs are watched instead, the header says read-only: watched, not enforced with the reason, and
AGY_READ_ONLY_ENFORCEMENT=require refuses them outright. agy_status reports which applies.
The boundary is exactly the workspace roots. agy can still write anywhere else your user can, and
a process it gets launched outside its own process tree — through open, an app, or a launchd
job — is not sandboxed. That is why the watch stays on in both modes: the bridge fingerprints the
working tree around every plan-mode run. A tree that moved despite enforcement is reported as
WORKING TREE CHANGED (another writer, or an escape through such a process); a tree that moved
without enforcement is reported as READ-ONLY VIOLATION. No warning means it looked and found
nothing; a tree it could not fingerprint produces no claim in either direction. The fingerprint
covers cwd and every directory the call hands agy. In
a git repository it covers HEAD, the content and mode of every tracked change, the content of
every untracked file, and the mode, size and mtime of every ignored entry, ignored directories
walked the same way. A dependency or build tree at the repository top (node_modules, .venv,
venv, __pycache__, .next, dist) counts as one entry — so a .env or build/out.js written
in plan mode is seen, while a rewrite deep inside node_modules is not. Outside git it compares
path, type, size, mode and mtime. Both are bounded to 20,000 entries and 10s. Measured on an Apple
M5 Max: about 150 ms per snapshot on a clean 3,500-file repository, and about 1.1 s
with 300 modified and 3,000 untracked files; two snapshots bracket each run.
Anything else writing to the tree while the run is live (an editor, a watcher, a parallel write
delegation) also moves it: the warning means the tree changed during the run, not proof of who
changed it. A plan run whose tree moved and then failed carries the warning in its error. The
header, not the tool's name and not the absence of a denied-actions note, is the signal to
trust — denied actions only ever populate when the grant is off.
A restriction that cannot be enforced fails the call: if the installed agy does not support
--mode or --sandbox, a run needing either is refused rather than run with more authority than
was asked for. --sandbox is in any case a terminal restriction, not a permission boundary.
AGY_ALLOWED_ROOTS validates inputs; it is not a sandbox. It checks every call's cwd, dirs
and files — including the workspace roots the bridge derives from them — before agy starts, so a
caller cannot point a delegation outside the roots you nominate. It does not confine the run:
under the permission grant agy has a shell and can reach anything the user running the bridge can.
The read-only sandbox above only blocks writes into a read-only run's own roots, and a run allowed
to write is not sandboxed at all. For real containment, run the bridge somewhere contained.
Failure behavior
The bridge always fails loudly, and it decides what "failure" means from agy's JSON envelope rather than from its exit code. That matters because agy can exit 0 with status: SUCCESS and a plausible answer while having silently had its tool actions auto-denied — the bridge surfaces those as a denied-actions warning instead of passing off a half-worked answer as a clean one. Failures are classified: only a quota 429 fails over to the next model, a network error is retried once, and an invalid model or an expired login stops immediately instead of burning the whole chain. A status code counts only beside a status word, so read 429 bytes in a log is not a quota error and foo.ts:401 is not an auth failure. Tokens a failed attempt spent still count against AGY_BUDGET_TOKENS. Degraded model routing is annotated in the response header. By default the calling agent (Claude) will typically do the work itself after a failure — visible in the transcript, but easy to stop noticing in a long session. Set AGY_ON_FAILURE=strict to append an explicit "do NOT perform this work yourself — report the failure to the user" instruction to every delegation error, so you keep control over when token savings are silently lost. A call rejected before anything was delegated — a path outside the roots, a missing cwd, a prompt agy cannot receive — is the caller's to fix and carries no such instruction.
Known limitations
Deliberately not addressed, so they are not mistaken for oversights:
The delegation-depth counter is cooperative.
AGY_MAX_DELEGATION_DEPTHis propagated to the child through an environment variable, so a nested launcher that scrubs the environment resets it to zero. The failure mode is wasted quota through a delegation loop, not a privilege escape.The run log is not redacted.
AGY_REDACTscrubs what returns to the caller; the temporary log agy writes for the quota poller can hold secrets in cleartext until the run ends. It lives in a per-process directory only your user can read, is removed on shutdown, and one left behind by a crash is removed the next time the bridge starts.Inputs are bounded. A prompt is passed to agy as one command-line argument, so a built prompt over 128 KiB (Linux's per-argument limit), or one containing a NUL byte, is refused before anything runs; pass file paths rather than inlining large content.
delegate_manytakes at most 8 tasks or 8 distinct models, andtaskscannot be combined withmodels.--disable-slash-commandsis best-effort. Unlike--mode planand--sandbox, it is dropped rather than refused when the installed agy does not advertise it, on the reasoning that a build without the flag most likely has no expansion to disable.Read-only is enforced on macOS only. Linux has no equivalent the bridge can apply without extra software, so there a read-only run is watched, not blocked. Set
AGY_READ_ONLY_ENFORCEMENT=requireto refuse such runs instead.The macOS block is by path. A file inside a root that already has a hard link outside every root can be rewritten through that outside link. Creating such a link during the run is blocked, and so is renaming any directory above a root to move the tree out from under its rule. The working-tree fingerprint still reports a change made through an old link.
A root that holds agy's state stays partly writable. When a root contains
~/.gemini, that directory is exempt so agy can still run; a write there is not blocked, and the fingerprint skips it. A root at or inside~/.geminiis watched, not enforced.A fan-out sharing one
session_idruns sequentially. agy holds a per-conversation lock, so concurrent turns against one conversation would corrupt it. Fan out across conversations for parallelism.
Development
npm install
npm test # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build # esbuild → dist/index.jsContributing
Read CONTRIBUTING.md — conventional commits, prettier, and a test per behaviour change. Vulnerabilities go through SECURITY.md, never a public issue.
Contributors
License
MIT
Available Tools
9 toolsadversarial_reviewA
Get an adversarial second opinion from a different model family (Gemini Pro). ALWAYS use this for plan critiques, design reviews, and pre-merge code review: it hunts for flaws, edge cases, security issues, and unstated assumptions you may have missed. Pass either content or files — a call with neither is rejected. Pass schema to get ranked findings back as data instead of prose.
Inputs: cwd, dirs, files, focus, +5 more.
agy_statusA
What this bridge has spent and what it can still do: tokens by model, live quota cooldowns, runs in flight, the resolved model chain per tool, the user's set_model choice, the models agy offers, warm sessions, and the agy version and flags detected at startup. Check this before a large fan-out, or to list models before set_model.
Inputs: no named parameters.
analyze_filesA
Delegate file analysis to the Antigravity CLI (Gemini) instead of reading files yourself. USE THIS whenever a file is large (>200 lines) or the task spans more than 3 files: logs, database dumps, generated code, cross-file reviews, comparisons. The files never enter your context — only the answer does.
Inputs: files (required), question (required), cwd, dirs, +4 more.
deep_searchA
Delegate codebase archaeology to the Antigravity CLI: git log/diff/blame spelunking, wide greps across a repo, 'when/why did X change', 'where is Y used'. USE THIS instead of running many search commands yourself — it saves your context.
Inputs: query (required), cwd, dirs, model, +3 more.
delegateA
Raw delegation to the Antigravity CLI for heavy tasks that don't fit the other tools. Read-only by default; pass write: true to let agy edit files, sandbox: true to confine it. Anything it was refused comes back as a denied-actions note.
Inputs: prompt (required), cwd, dirs, model, +5 more.
delegate_manyA
Fan one question out to several models at once (a council, with a disagreement report), or fan several sub-tasks out to one model. Runs behind the same concurrency cap as everything else, so it queues rather than stampedes the shared quota.
Inputs: cwd, dirs, model, tasks, +4 more.
follow_upA
Continue a previous Antigravity session by session_id (returned by every other tool). USE THIS for follow-up questions about a prior delegation — the full prior context is already on agy's side, so you don't resend anything. Pass model to get a second opinion on the same history from a different model without re-sending it. Read-only by default; pass write: true to rework a delegation that edited files.
Inputs: question (required), session_id (required), cwd, dirs, +5 more.
set_modelA
Choose the model and reasoning tier every tool uses from now on, on this machine. Ask the user first — "proceed with the default, or change model or effort?" — then call this once: with no arguments to accept the default, or with what they chose. The choice is saved and no tool asks again. An explicit model argument on a call still wins for that call. Set AGY_ASK_MODEL=false to skip the gate and route on the built-in chains.
Inputs: model, effort.
web_lookupA
Delegate a web/documentation lookup to the Antigravity CLI (Gemini with web access): library docs, API references, error messages, current versions, external knowledge. USE THIS when you need information you don't have or that may be newer than your training data.
Inputs: query (required), cwd, dirs, model, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have distinct targets (status, model selection, file analysis, code search, web lookup, review, follow-up), and descriptions give clear 'use this when' guidance. However, the generic `delegate` overlaps conceptually with the specialized delegation wrappers (analyze_files, deep_search, web_lookup), so an agent must rely on the descriptions to route correctly.
Names are mostly snake_case verb_noun or verb_phrase (analyze_files, deep_search, web_lookup, set_model, follow_up), which is readable and predictable. Minor deviations exist: `agy_status` uses an app prefix, `adversarial_review` is adjective_noun, and `delegate`/`delegate_many` differ in style.
Nine tools is well-scoped for a delegation bridge: one status, one config, one follow-up, and a small set of specialized plus generic delegation entry points. Each tool earns its place without bloat.
The surface covers the core lifecycle: configure model, check status/quota, delegate to specialized contexts, review adversarially, and continue sessions. Minor gaps exist around session discovery/listing or cleanup, but agents can work around these via follow_up and agy_status.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.6143 npm68MIT
- AlicenseAqualityDmaintenanceLocal MCP server that exposes delegation tools for Codex, Claude, and Antigravity CLI, enabling an orchestrator agent to assign tasks to these sub-agents via non-interactive CLI commands.3MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets Claude Code call the Google Antigravity CLI (agy) headlessly for a second opinion from a different model family, or to have agy read project files on Claude's behalf so large files never enter Claude's context window.-
- AlicenseNot gradedqualityFmaintenanceThis MCP server bridges Claude Code with the Antigravity CLI (agy), allowing Claude to delegate tasks to Google Gemini models via configurable difficulty tiers. It verifies the actual backend model for every call, provides separate tools for safe ask/research vs. shell exec, and supports long-running background jobs.MIT