sshahzaiib/agy-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**
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
> The "timeout": 600000 (10 min, milliseconds) is the **client-side** tool-call
> deadline — without it, a cold-start analyze_files (~40–50s) or a long
> delegate can hit Claude Code's default and return timed out waiting for
response while the agy run is still going. If your client doesn't honor a
> per-server timeout, set the global env var MCP_TOOL_TIMEOUT=600000 instead.
> 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 3.5 Flash (High) → Gemini 3.1 Pro (Low) |
| deep_search | git log/diff/blame archaeology, repo-wide greps | Gemini 3.5 Flash (Medium) → (High) |
| web_lookup | Docs, API references, external/current knowledge | Gemini 3.5 Flash (Medium) → (High) |
| adversarial_review | Plan critiques, design and code reviews | Gemini 3.1 Pro (High) → Claude Opus 4.6 (Thinking) → Flash (High) |
| follow_up | Continue a prior session by session_id — no context resend | inherits the session |
| delegate | Anything else heavy | Gemini 3.5 Flash (High) |
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:
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. 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):
1. kills the agy process group immediately (no waiting out the timeout),
2. parses the reset time ("Resets in 4h24m") into an in-process cooldown registry,