# sshahzaiib/agy-bridge [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/sshahzaiib/agy-bridge  
**GitHub Stars:** 50  
**npm Downloads (last month):** 461  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sshahzaiib-agy-bridge

## Description
Delegate heavy tasks from Claude Code (or any MCP client) to the Antigravity CLI (Gemini): file analysis, repo archaeology, web lookups, and adversarial second-opinion code reviews. Quota-aware model failover with cooldowns, per-tool timeouts, and multi-turn session continuity.

## Tools
Capabilities this server exposes over MCP:

- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agy-bridge": {
    "command": "npx",
    "args": ["-y","agy-bridge"]
  }
}
```

## Documentation

## What sshahzaiib/agy-bridge MCP server does

The sshahzaiib/agy-bridge MCP server lets an MCP client send demanding development tasks to the Antigravity CLI (`agy`) instead of processing all source material in the client context. The bridge returns the delegated answer, while large files, repository searches, and web lookup content remain on the agy side during the request.

Its six tools divide common tasks by intent:

- `analyze_files` handles large files, logs, database dumps, generated code, and reviews spanning multiple files.
- `deep_search` investigates git history, diffs, blame data, repository-wide references, and why or where code changed.
- `web_lookup` requests documentation, API references, error explanations, current versions, or other external information.
- `adversarial_review` asks a different model family to look for flaws, security issues, edge cases, and hidden assumptions in plans or code.
- `follow_up` continues an earlier session using its `session_id`.
- `delegate` provides a general route for heavy tasks that do not match the specialized tools.

## How it works

Each request can include an optional project directory through `cwd` and an optional exact model name. On its first use, the bridge queries `agy models`, caches the available models for the process lifetime, and selects the first available model in the relevant preference chain. If those choices are unavailable, it falls back to `AGY_DEFAULT_MODEL` and then to agy's own default.

The sshahzaiib/agy-bridge MCP server validates requested model names before execution. It also watches agy log output for quota exhaustion. When a model reports a 429 resource error, the bridge stops the process, records the reset period, and retries with the next eligible model. Responses include the selected model and session identifier, and may include failover details.

Sessions support multi-turn work without resending the original context. The `follow_up` tool uses the returned session identifier to continue the earlier Antigravity conversation.

## Setup and configuration

The documented setup requires Node.js 18 or newer, an installed and authenticated Antigravity CLI, and Claude Code. Register the npm package as an MCP server with:

```bash
claude mcp add-json -s user agy-bridge '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'
```

The repository also provides a `CLAUDE.md` file containing delegation rules that can be downloaded into a project or used globally. The client-side timeout in the example is separate from agy's execution timeout; clients with shorter deadlines can stop waiting before agy finishes.

By default, tool budgets are 120 seconds for web lookups, 180 seconds for deep searches, 300 seconds for file analysis, adversarial reviews, and follow-ups, and 600 seconds for general delegation. `AGY_TIMEOUT` changes the common budget, while variables such as `AGY_TIMEOUT_DEEP_SEARCH` override an individual tool. The per-tool setting takes precedence.

## Tools and capabilities

The bridge supports model failover, cooldown tracking after quota exhaustion, configurable output truncation, optional agy sandbox mode, and process-group cancellation. Cancelling an MCP call also terminates the agy run rather than leaving helper processes behind. The `agy-bridge` process can use Gemini, Claude, or GPT-OSS models when those models are available through the authenticated Antigravity CLI and match the routing rules.

## Limitations and notes

The Antigravity CLI must already be installed and authenticated; the bridge does not replace that prerequisite. Client and agy timeouts must be aligned for long-running requests. If the client deadline expires first, the session can still be continued with `follow_up` using the returned session identifier. Model availability and quota status depend on the configured agy account and currently available models.

_Full upstream README: https://allmcps.com/mcp/sshahzaiib-agy-bridge/readme_