agy-bridge is an MCP (Model Context Protocol) bridging tool that lets Claude Code delegate time-consuming or context-intensive tasks to the Antigravity CLI (command-line shorthand agy). Its design goal is to save Claude's context window and tokens—Claude only sends the task, the bridge layer routes it through agy to the best available model, and ultimately only the answer is returned to Claude; large files, deep git searches, and web queries never enter Claude's context.
Main capabilities
- Dedicated tools: provides a targeted set of task tools, covering file analysis (analyze_files), repository archaeology/deep search (deep_search), web lookup (web_lookup), adversarial code review (adversarial_review), follow-up questions (follow_up), and general delegation (delegate), among others.
- Model routing and fallback: on first use, the bridge runs agy models (cached for the process lifetime) and selects the first available model according to the tool's preference chain; if none are available, it falls back to AGY_DEFAULT_MODEL, and finally to agy's own default model. Because agy silently ignores unknown --model values, the bridge pre-validates model names to avoid requests landing on the wrong model.
- Quota-aware failover: in print mode agy does not expose quota exhaustion, but instead silently retries 429 until the print timeout, then returns empty output with exit code 0. The bridge monitors each run's log via --log-file and, upon encountering RESOURCE_EXHAUSTED (429): immediately terminates the agy process group (no longer waiting for the timeout), parses the reset time from the log (e.g. "Resets in 4h24m") and writes it to an in-process cooldown registry, retries the same prompt on the next model in the tool chain, and skips models in cooldown on subsequent calls until their quota resets. Failover is noted in the response footer (e.g. failover: <model>: quota exhausted (resets in 4h24m)); only when all candidate models are exhausted does the call fail within seconds and list the reset times, rather than hanging.
- Timeouts and cancellation: each tool has its own default timeout—web_lookup 120 seconds, deep_search 180 seconds, analyze_files / adversarial_review / follow_up 300 seconds, delegate 600 seconds. Setting AGY_TIMEOUT overrides all of them at once; to adjust an individual tool, use AGY_TIMEOUT_<TOOL_NAME> (for example AGY_TIMEOUT_DEEP_SEARCH=300), and the per-tool override takes precedence over the global AGY_TIMEOUT and the tool default. Available per-tool variables include AGY_TIMEOUT_ANALYZE_FILES, AGY_TIMEOUT_DEEP_SEARCH, AGY_TIMEOUT_WEB_LOOKUP, AGY_TIMEOUT_ADVERSARIAL_REVIEW, AGY_TIMEOUT_FOLLOW_UP, AGY_TIMEOUT_DELEGATE. The termination path escalates from SIGTERM to SIGKILL covering the entire process group, and the deadline triggers even if agy's helper processes still hold the output pipe. Canceling a tool call from the MCP client (for example pressing Esc in Claude Code) likewise terminates the agy run rather than orphaning it.
- Timeout layering must be aligned: the above timeouts are the agy-side budget; the MCP client (Claude Code) has its own independent tool-call timeout. If the client timeout is shorter than the agy budget, the client gives up first and shows Error: timed out waiting for response (note: agy-bridge's own timeout shows agy timed out after Ns). Work is not lost—the agy session persists, and the result can be retrieved via follow_up using the returned session_id. The recommended practice is to make the client wait at least as long as agy: the install command already sets a per-server timeout of 600000 milliseconds (i.e., 10 minutes) for the agy-bridge entry; if it was not included at registration, re-run the install command or set the global environment variable MCP_TOOL_TIMEOUT=600000. Rule of thumb: client timeout ≥ agy budget.
- Expected latency: most perceived "slowness" comes from cold start—the first call in a session starts the agy CLI and warms up the model. A simple analyze_files cold start on 3 files takes about 40–50 seconds (observed about 46 seconds), and subsequent calls in the same session decrease. If the first call also encounters a quota 429, it takes longer during bridge failover. Therefore, a client timeout below about 60 seconds may intermittently trigger cold-start timeouts, and even if the problem is "simple," it should be set more leniently.
- Response footer: each response ends with footer information, used to indicate statuses such as failover.
- Failure behavior: the bridge always fails explicitly—agy errors expose agy's actual stderr as MCP tool errors, and degraded model routing is noted in the response footer. By default, the calling agent (Claude) usually completes the work itself after a failure—this is visible in the logs but easy to overlook in long sessions. Setting AGY_ON_FAILURE=strict appends an explicit instruction after every delegation error: "Do not perform this work yourself—report the failure to the user," thereby giving you control over when token savings are quietly lost.
Usage Prerequisite is that the Antigravity CLI (agy) is installed and authenticated. The tools all accept optional parameters cwd (project root directory) and model (an ID or display name from agy models, which is validated; when the name does not match, available models are listed). The installation configuration needs to set "timeout": 600000 (10 minutes, in milliseconds) for the agy-bridge entry as the client tool call deadline; if the client does not support per-server timeouts, set the global environment variable MCP_TOOL_TIMEOUT=600000. All environment variables are optional.
Use cases Suitable for scenarios that need to offload heavy-load tasks such as large file analysis, deep git searches, web queries, and second-opinion-style code reviews from the Claude context, especially for developers who care about context windows and token consumption and want to leverage agy's multi-model fallback and quota-awareness capabilities.
Limitations Antigravity CLI (agy) must be installed and authenticated in advance; agy does not expose quota exhaustion in print mode, so log monitoring is required; there are two layers of timeouts (client and agy side), and if they are not aligned, the client may time out first; cold starts have a delay of tens of seconds; model names are pre-validated by the bridge, while agy itself silently ignores unknown --model values. Regarding contributions, the repository welcomes participation through issues or PR participation.
