# agy-bridge
[](https://github.com/sshahzaiib/agy-bridge/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/agy-bridge)
[](https://www.npmjs.com/package/agy-bridge)
[](https://nodejs.org)
[](LICENSE)
[](https://glama.ai/mcp/servers/sshahzaiib/agy-bridge)
[](https://mseep.ai/app/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**
[](https://glama.ai/mcp/servers/sshahzaiib/agy-bridge)
[](https://mcpmarket.com/server/agy-bridge)
[](https://www.pulsemcp.com/servers/sshahzaiib-agy-bridge)
[](https://mcp.so/server/agy-bridge/sshahzaiib)
[](https://mcpservers.org/servers/sshahzaiib/agy-bridge)
[](https://mseep.ai/app/2f439062-d211-4a6c-b41b-3a603f490a32)
```
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](https://antigravity.google/docs/cli-getting-started) (`agy`) installed and authenticated
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
## Install
```bash
# 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-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](#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:
```
---
[agy-bridge] model: Gemini 3.5 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. 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,
3. retries the same prompt on the next model in the tool's chain,
4. skips cooled-down models on all subsequent calls until their quota resets.
Failovers are annotated in the response footer (`failover: