# sshahzaiib/agy-bridge [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/sshahzaiib/agy-bridge  
**GitHub Stars:** 61  
**npm Downloads (last month):** 391  
**Views:** 7  
**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 does

sshahzaiib/agy-bridge lets an MCP client send heavy work to the Antigravity CLI instead of handling every file read, search, or web lookup in the calling model's context. The bridge is designed for Claude Code, but its MCP tools can be invoked by other MCP clients.

Delegated work includes analyzing large files and multi-file sets, investigating a repository's history and usage patterns, looking up documentation or current external information, and reviewing plans or code from an adversarial perspective. A general-purpose delegation tool covers tasks that do not fit those categories.

## How it works

The client starts the package with `npx`, and the bridge invokes the authenticated `agy` command in the requested working directory. Each call can provide an optional `cwd` and model selection. The bridge checks models reported by `agy models`, chooses the first available model in the relevant preference chain, and falls back through other candidates when needed.

Routing is Gemini-first. The tool-specific chains select different Gemini families and tiers for analysis, search, web lookup, reviews, and general delegation; Claude Opus and GPT-OSS are appended as fallback choices when no Gemini model is available. A configured default model and then agy's own default provide further fallback behavior.

Responses include the selected model and a session identifier. `follow_up` uses that identifier to continue an earlier Antigravity conversation without resending its context. When a model reports quota exhaustion, the bridge stops the process, records the reset period, marks the model as temporarily unavailable, and retries on the next candidate.

## Setup and configuration

The runtime requires Node.js 18 or newer, an installed and authenticated Antigravity CLI, and an MCP client such as Claude Code. Claude Code can register the server with:

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

The client-side timeout should be long enough for delegated operations. The bridge also supports `MCP_TOOL_TIMEOUT` for clients that do not honor a per-server timeout. Its own operation budgets can be controlled globally with `AGY_TIMEOUT` or individually with `AGY_TIMEOUT_ANALYZE_FILES`, `AGY_TIMEOUT_DEEP_SEARCH`, `AGY_TIMEOUT_WEB_LOOKUP`, `AGY_TIMEOUT_ADVERSARIAL_REVIEW`, `AGY_TIMEOUT_FOLLOW_UP`, and `AGY_TIMEOUT_DELEGATE`. Per-tool values override the global value.

## Tools and capabilities

- `analyze_files` handles large files, file sets spanning more than three files, logs, database dumps, generated code, and cross-file comparisons.
- `deep_search` performs repository-wide searches and investigates Git history through log, diff, and blame information.
- `web_lookup` retrieves library documentation, API references, explanations for errors, and other external or current information.
- `adversarial_review` asks for a second opinion on plans, designs, and code, focusing on edge cases, security concerns, flaws, and assumptions.
- `follow_up` continues a prior delegation using its `session_id`.
- `delegate` sends other heavy tasks directly to Antigravity with access to the supplied working directory.

All tools accept optional working-directory and model parameters. Model names are validated before execution, and responses identify the model and session used.

## Limitations and notes

The Antigravity CLI must be installed and authenticated before the bridge can perform delegated work. The MCP client's tool-call deadline is separate from the bridge's own execution timeout; if the client deadline is shorter, it can stop waiting first. Cancelling a tool call terminates the Antigravity process group, and timed-out or cancelled work can be continued through the returned session when a session identifier is available.

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