Delegates heavy computational tasks from Claude Code to the Antigravity CLI with automated model routing and quota-aware failover.
Also known as sshahzaiib/agy-bridge
- Stars
- 67
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- 0.3.1
- Last commit
- Oct 28, 2026
- License
- MIT
What is agy-bridge MCP?
agy-bridge delegates heavy computational tasks from Claude Code to the Antigravity CLI with automated model routing and quota-aware failover. It exposes 6 tools, such as analyze_files, deep_search, web_lookup.
Summary generated from the project's README
About agy-bridge MCP server
agy-bridge acts as a connection between Claude Code and the Antigravity CLI to handle intensive computational workloads. By offloading heavy tasks to the agy tool, developers can preserve the context window and token limits of their primary AI client. The server uses specialized tools to route requests to various models like Gemini Flash, Gemini Pro, or GPT-OSS based on the specific task requirements.
This bridge is designed for local use with Node.js 18+ and requires the Antigravity CLI to be installed and authenticated on the machine. It provides six distinct tools including analyze_files, deep_search, web_lookup, adversarial_review, follow_up, and a general delegate tool. It features an automated model routing system and a quota-aware failover mechanism that detects resource exhaustion and automatically retries the task using the next available model in the preference chain.
What you can do with it
- 1Analyze large codebasesA developer can request an analysis of multiple large files or logs without filling the Claude context window.
- 2Perform deep repository searchesYou can instruct the AI to conduct extensive git history searches or repository-wide greps.
- 3Conduct external researchThe client can look up API references or current documentation via web searches.
- 4Resume interrupted sessionsDevelopers can continue a previous conversation using a session ID to avoid resending context.
Written from the project's README. Every use case is checked against a quote from it.
How to install agy-bridge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall agy-bridge MCP in Claude Code
$ claude mcp add agy-bridge -- npx -y agy-bridgeInstall agy-bridge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agy-bridge": {
"command": "npx",
"args": [
"-y",
"agy-bridge"
]
}
}
}Install agy-bridge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agy-bridge": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agy-bridge"
]
}
}
}Install agy-bridge MCP in VS Code CLI
$ code --add-mcp '{"name":"agy-bridge","type":"stdio","command":"npx","args":["-y","agy-bridge"]}'Install agy-bridge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agy-bridge": {
"command": "npx",
"args": [
"-y",
"agy-bridge"
]
}
}
}Install agy-bridge MCP in Codex
$ codex mcp add agy-bridge -- npx -y agy-bridgeInstall agy-bridge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agy-bridge] command = "npx" args = ["-y", "agy-bridge"]
Install agy-bridge MCP in Gemini CLI
$ gemini mcp add -s user agy-bridge npx -- -y agy-bridgeInstall agy-bridge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agy-bridge": {
"command": "npx",
"args": [
"-y",
"agy-bridge"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for agy-bridge 0.3.1 in an isolated container with no network and no keys. It answered and listed 6 tools.
agy-bridge MCP tools 6
Read from the server with tools/listanalyze_filesDelegate 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.
deep_searchDelegate 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.
web_lookupDelegate 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.
adversarial_reviewGet 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.
follow_upContinue 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.
delegateRaw delegation to the Antigravity CLI for heavy tasks that don't fit the other tools. agy has full tool access (shell, file reads, web) in the given cwd.
| analyze_files | 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. | |
| deep_search | 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. | |
| web_lookup | 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. | |
| adversarial_review | 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. | |
| follow_up | 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. | |
| delegate | Raw delegation to the Antigravity CLI for heavy tasks that don't fit the other tools. agy has full tool access (shell, file reads, web) in the given cwd. |
Configuration
AGY_DEFAULT_MODELFallback model when no chain entry is available
AGY_MAX_OUTPUT_CHARSTruncation cap for tool output, in characters (default 50000)
AGY_ON_FAILURESet to `strict` to instruct the calling agent not to absorb failed delegations (default `fallback`)
AGY_PATHPath to the agy binary (defaults to `agy` on PATH)
AGY_TIMEOUTOverride the per-tool timeouts, in seconds
| Name | Description | |
|---|---|---|
| AGY_DEFAULT_MODEL | Fallback model when no chain entry is available | |
| AGY_MAX_OUTPUT_CHARS | Truncation cap for tool output, in characters (default 50000) | |
| AGY_ON_FAILURE | Set to `strict` to instruct the calling agent not to absorb failed delegations (default `fallback`) | |
| AGY_PATH | Path to the agy binary (defaults to `agy` on PATH) | |
| AGY_TIMEOUT | Override the per-tool timeouts, in seconds |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesshahzaiib/agy-bridge is public and reachablegithub.com/sshahzaiib/agy-bridge ↗Pass
- Package names this repository as its sourceagy-bridge names sshahzaiib/agy-bridge as sourcenpmjs.com/package/agy-bridge ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/sshahzaiib/agy-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agy-bridgePass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagy-bridge
An MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — saving Claude's context window and tokens for what matters.
Claude sends a task → the bridge routes it to the best available model via agy → only the answer comes back. Large files, deep git searches, and web lookups never touch Claude's context.
Listed on
User → Claude Code → agy-bridge (MCP) → agy CLI → Gemini / Claude / GPT-OSS
← ← ←
Why this over claude-to-agy?
| claude-to-agy | agy-bridge | |
|---|---|---|
| Tool surface | 1 generic delegate_to_agy |
6 purpose-built tools — Claude self-routes reliably |
| Model selection | none (agy default only) | per-tool routing across all agy models, with availability detection and fallback |
| Multi-turn | stateless | session continuity — follow_up resumes agy conversations without resending context |
| Output safety | unbounded | configurable truncation cap protects Claude's context |
| Sandbox | no | optional --sandbox mode |
| Install | uvx (Python) | npx (Node) — zero install |
Requirements
- Node.js 18+
- Antigravity CLI (
agy) installed and authenticated - Claude Code
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 agy-bridge \
'{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'
# 2. Add delegation rules to your project (or ~/.claude/CLAUDE.md for global)
curl -o CLAUDE.md https://raw.githubusercontent.com/sshahzaiib/agy-bridge/main/CLAUDE.md
The
"timeout": 600000(10 min, milliseconds) is the client-side tool-call deadline — without it, a cold-startanalyze_files(~40–50s) or a longdelegatecan hit Claude Code's default and returntimed out waiting for responsewhile the agy run is still going. If your client doesn't honor a per-servertimeout, set the global env varMCP_TOOL_TIMEOUT=600000instead. Details and the agy-side budgets are in Timeouts and cancellation.
Tools
| Tool | Use for | Model routing (first available) |
|---|---|---|
analyze_files |
Files >200 lines, >3 files at once, logs, dumps, generated code | Gemini Flash (High) → Gemini Pro (Low) → fallback |
deep_search |
git log/diff/blame archaeology, repo-wide greps | Gemini Flash (Medium) → (High) → fallback |
web_lookup |
Docs, API references, external/current knowledge | Gemini Flash (Medium) → (High) → fallback |
adversarial_review |
Plan critiques, design and code reviews | Gemini Pro (High) → Gemini Flash (High) → fallback |
follow_up |
Continue a prior session by session_id — no context resend |
inherits the session |
delegate |
Anything else heavy | Gemini Flash (High) → fallback |
All tools accept optional cwd (project root) and model (an id or display name from agy models; validated, with available models listed on mismatch).
Every response ends with a footer:
---
[agy-bridge] model: Gemini Flash (High) | session: 1f0c…-d4 (use follow_up to continue)
Model routing
On first use the bridge runs agy models (cached for the process lifetime) and picks the first available model in the tool's preference chain. Chain entries name a family and tier rather than a version (Gemini * Flash (High)), and * resolves to the newest version agy currently lists, so a Gemini release never silently breaks routing. Chains are Gemini-first; Claude Opus and GPT-OSS are appended as a last resort and only used when no Gemini model is listed. If none is available it falls back to AGY_DEFAULT_MODEL, and finally to agy's own default. agy silently ignores unknown --model values, so the bridge validates names up front instead of letting requests land on the wrong model.
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.
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
Each tool has its own default timeout sized to its job: web_lookup 120s, deep_search 180s, analyze_files / adversarial_review / follow_up 300s, delegate 600s. Setting AGY_TIMEOUT explicitly overrides all of them at once. To change a single tool, set AGY_TIMEOUT_<TOOL_NAME> instead (e.g. AGY_TIMEOUT_DEEP_SEARCH=300); a per-tool override takes precedence over the global AGY_TIMEOUT and the tool's default. The full set of per-tool variables is AGY_TIMEOUT_ANALYZE_FILES, AGY_TIMEOUT_DEEP_SEARCH, AGY_TIMEOUT_WEB_LOOKUP, AGY_TIMEOUT_ADVERSARIAL_REVIEW, AGY_TIMEOUT_FOLLOW_UP, and AGY_TIMEOUT_DELEGATE. The kill path escalates SIGTERM → SIGKILL across the whole process group, and the deadline fires even if agy's helper processes hold the output pipes open. Cancelling the tool call from the MCP client (e.g. pressing Esc in Claude Code) also kills the agy run instead of orphaning it.
Two timeout layers — align them. The timeouts above are the agy-side budget. Your MCP client (Claude Code) has its own, separate tool-call timeout, and if it is shorter than the agy budget the client gives up first — you'll see Error: timed out waiting for response (note: agy-bridge's own timeout reads agy timed out after Ns instead). The work is not lost: the agy session persists, so follow_up with the returned session_id retrieves the result. But the real fix is to make the client wait at least as long as agy: the Install command already sets a per-server timeout of 600000ms (scoped to the agy-bridge entry 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=600000. Rule of thumb: client timeout ≥ agy budget.
Expected latency. Most of the perceived "slowness" is cold start: the first call in a session spawns the agy CLI and warms the model. A simple analyze_files over 3 files measures around 40–50s cold (≈46s observed), dropping on subsequent same-session calls. A first call that also hits a quota 429 takes longer while the bridge fails over. So a client timeout below ~60s will intermittently trip on cold starts even for "simple" questions — size it generously.
Configuration
All optional, via environment variables:
| Variable | Default | Description |
|---|---|---|
AGY_PATH |
agy |
Path to the agy binary |
AGY_TIMEOUT |
per-tool | Seconds; overrides all per-tool timeouts at once (see above), passed as --print-timeout, enforced with a 15s kill grace |
AGY_TIMEOUT_<TOOL> |
per-tool | Seconds; overrides the timeout for a single tool only, e.g. AGY_TIMEOUT_DEEP_SEARCH=300. Wins over AGY_TIMEOUT |
AGY_MAX_OUTPUT_CHARS |
50000 |
Truncation cap for tool output |
AGY_DEFAULT_MODEL |
unset | Fallback model when no chain entry is available (name, id, or * pattern) |
AGY_SKIP_PERMISSIONS |
true |
Pass --dangerously-skip-permissions to agy |
AGY_SANDBOX |
false |
Run agy with --sandbox |
AGY_ON_FAILURE |
fallback |
strict appends an instruction to failed-tool errors telling the calling agent not to absorb the work itself |
Failure behavior
The bridge always fails loudly: agy errors surface as MCP tool errors with agy's actual stderr, and degraded model routing is annotated in the response footer. 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.
Development
npm install
npm test # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build # tsup → dist/index.js
Support
agy-bridge is free and MIT-licensed. If it saves you tokens every day, Ko-fi keeps it maintained.
Contributors
Contributions are welcome — open an issue or PR.
Star History
License
MIT
agy-bridge MCP questions
How do I add agy-bridge MCP to Claude Code?
Run claude mcp add agy-bridge -- npx -y agy-bridge in your terminal. Add --scope user to make it available in every project.
How do I add agy-bridge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does agy-bridge MCP provide?
It exposes 6 tools, including analyze_files, deep_search, web_lookup, adversarial_review, follow_up.
What does agy-bridge do for Claude Code?
It allows Claude Code to delegate heavy tasks like large file analysis, deep git searches, and web lookups to the Antigravity CLI, saving Claude's context window and tokens.
How does the bridge handle model quota exhaustion?
The bridge monitors for 429 resource exhausted errors, parses the reset time, and automatically retries the prompt using the next available model in the tool's routing chain.
