clagy — a Claude Code → Antigravity (agy) bridge

An MCP server that exposes Google Antigravity's CLI as sub-agents you can invoke from Claude Code. Claude orchestrates; Gemini workers execute in parallel.

Claude Code
  └─ agy_fanout({tasks:[…]})
       ├─ agy.exe -p --output-format json  → worker 1  ┐
       ├─ agy.exe -p --output-format json  → worker 2  ├─ in parallel
       └─ agy.exe -p --output-format json  → worker 3  ┘

When it's worth using

The benefit here is not speed — a worker takes 20–130 s to return something Claude would write in half the time. The benefit is context that never enters Claude's window, which means a longer session. Hence the only rule that matters:

Delegate when the ratio between what the worker consumes and what it hands back is high.

The measured numbers, the reasoning behind each row, and the second axis of benefit — that workers fail differently than Claude, so they cover blind spots — are in docs/when-to-delegate.md.

Related MCP server: claude-mcp-bridge

Documentation

Requirements

• Node 18+

• Claude Code

• Google Antigravity's CLI (agy) installed and already authenticated. The bridge reuses the OAuth credentials in ~/.gemini/; it does not need GEMINI_API_KEY. If agy is not in %LOCALAPPDATA%\agy\bin\, set AGY_BIN to the executable's path.

Installation

In the examples below, C:\path\to\clagy is wherever you cloned this repo — substitute your own.

1. The bridge.

git clone https://github.com/mateo-cuello/orchestrator-claude--agy.git C:\path\to\clagy
cd C:\path\to\clagy
npm install
node mcp/agy-bridge.mjs --selftest    # must report 11/11 before you continue
claude mcp add --scope user agy -- node C:\path\to\clagy\mcp\agy-bridge.mjs

Scope user = available from every project, with nothing to install per repo.

2. The Stop hook, so async jobs report back on their own. In ~/.claude/settings.json:

"hooks": {
  "Stop": [
    { "hooks": [
      { "type": "command", "command": "node C:\\path\\to\\clagy\\hooks\\agy-stop-hook.mjs" }
    ] }
  ]
}

3. The skill, so Claude loads the orchestration playbook by itself: copy skills/agy-orchestration/ into ~/.claude/skills/ and replace the C:\path\to\clagy placeholders inside with your real path.

MCP servers and hooks are loaded at session startup: restart Claude Code after registering them. To use this from other repositories, see docs/other-repos.md.

Verification

node mcp/agy-bridge.mjs --selftest

Runs 11 checks: round trip, structured output, silent-failure detection, tool-contract effectiveness, the cwd regression (that writes land in your project and not in agy's scratch), the autonomous-mode guard, the full lifecycle of an async job, that the hook delivers a result and does not repeat it, that 21 consecutive registry writes lose none and leave no .tmp behind (this was a real bug: see async-and-autonomous.md), and that a hung job gets detected. It must report 11/11 checks OK.

Tools

agy_dispatch — a single task

agy_fanout — N in parallel

tasks[] + maxConcurrency (default 4). Returns {summary, results[]}.

agy_start / agy_result / agy_jobs — in the background

agy_start takes the same fields as agy_dispatch (plus label) but does not wait: it returns a jobId immediately while the worker keeps running. When it finishes, the Stop hook injects the result at the end of the next turn — no polling required. agy_result fetches it manually; agy_jobs lists everything.

Use it when you have something else to do meanwhile — the notification lands on a turn boundary, so launching one and immediately going idle buys you nothing. If your next step depends on the result, a blocking agy_dispatch is simpler. Details in docs/async-and-autonomous.md.

Modes

• read — read-only. This is the default and needs no extra permissions.

• write — also edits files. write_file(*) is already permitted in headless mode.

• verify — also runs allowlisted commands (npm test, pytest, ruff check, npx tsc --noEmit, make, git status|diff|log, …).

• autonomous — ⚠️ no permission system (--dangerously-skip-permissions): arbitrary commands, iterating on its own until tests pass. It exists so the write→test→fix cycle doesn't run through the orchestrator's context window. It requires an explicit cwd, rejects dangerous directories, and the contract forces the worker to paste raw test output. Run the tests yourself once anyway. Read docs/async-and-autonomous.md before using it.

The five agy traps this bridge solves

1. Silent failure on permissions. If a tool needs a permission it doesn't have, agy exits with code 0 and status:"SUCCESS" but an empty response, sending the notice to stderr. A naive orchestrator counts that as success. The bridge turns it into ok:false with denials[]. That's check #3 in the selftest.

2. Silent failure on quota, which looks just like it. agy never reports a 429 in print mode: it silently retries until --print-timeout runs out and exits equally empty. The bridge passes --log-file, looks for RESOURCE_EXHAUSTED and returns quotaExhausted: true with a different message — otherwise the diagnosis sends you off to fix permissions that were fine.

3. agy ignores the process cwd. Its default workspace is ~/.gemini/antigravity-cli/scratch, so a write_to_file with a relative path lands there instead of in your project — with no error at all. Measured across 4 variants: cwd alone fails; --add-dir <cwd> works; an absolute path in the prompt works. The bridge does both: it puts cwd in the workspace and forbids relative paths in the contract. That's check #5.

4. Unpredictable tool selection. The model may wander into run_command and die auto-denied. Every prompt is prefixed with a contract pinning the mode's toolset.

5. Shell escaping. An inline --json-schema breaks in PowerShell (the quotes get eaten). The bridge uses spawn with an argv array and passes the schema via file.

Also: -p does not accept stdin, so prompts longer than 8000 chars are written to a temporary BRIEF.md for the worker to read. And --agent is never used: a nonexistent name raises no error, it silently falls back to the default agent.

agy's permission model in headless mode

Config lives in ~/.gemini/antigravity-cli/settings.json (permissions.allow, which supports alternation: command(npm run (build|lint|test))) and ~/.gemini/config/config.json (userSettings.globalPermissionGrants, where the UI accumulates every "Always allow").

Sensitive paths (.env*, .git, .npmrc, .netrc, .git-credentials) are already in ask/denied by default — except in mode:"autonomous", which turns all of that off.

Review permissions.allow every so often: it grows on its own. agy's UI accumulates there every "Always allow" you accepted in an interactive session, and those grants also apply in headless mode. Which means mode:"verify" can run considerably more than the contract enumerates. command(git checkout), command(git add) and command(git commit) were removed from that list once — they let a non-autonomous worker discard uncommitted changes. Only read-only git remains.

Cost

A floor of ~18–26k input tokens per call (agy's system prompt), even for a "hello". A real research task measured 328k input + 1.4M cache-read + 10.5k output in 75s. Aggressive fan-out burns quota fast: use flash-high for broad sweeps and reserve gemini-3.1-pro-high for depth.

Quality

gemini-3.6-flash-low gave an incorrect answer on a trivial file-reading task during testing. Rule of thumb: schemas should always ask for files_read[] and confidence, and no claim about the code is accepted without opening the file it cites.

License

MIT — see LICENSE.