Antigravity CLI Bridge

A local Model Context Protocol (MCP) server that lets Claude Code control the Antigravity CLI (agy) via a PTY bridge — with async push notifications, multi-session orchestration, task contracts, and structured logging.

What it does

Instead of Claude Code doing all the work itself, it can delegate tasks to agy (which runs its own Gemini-powered AI loop). This means:

• Claude spawns agy sessions for heavy or parallel tasks
• Agy runs them in the background (image generation, code scaffolding, test writing, etc.)
• Claude monitors via push events and reacts to prompts — no polling

MCP Client Compatibility

The bridge is a standard MCP server — any MCP-capable client can use it:

Client	MCP Support	Notes
Claude Code	Full	CLAUDE.md + Monitor tool + slash commands all work
VS Code	Full (v1.102+, GA July 2025)	Configure via .vscode/mcp.json or Settings → MCP
Cursor	Yes	Works; use system prompt for workflow instructions
Windsurf	Yes	Works; use system prompt for workflow instructions
JetBrains IDEs	Yes (2025.2+)	Via AI Assistant MCP integration
Claude Desktop	Full	Add to claude_desktop_config.json

For non-Claude Code clients: the MCP tools (agy_start, agy_read, etc.) work as-is. The Claude-specific features (CLAUDE.md guidance, Monitor tool, slash commands) don't apply — paste the workflow guide into your client's system/rules prompt instead.

Prerequisites

• Node.js v18+
• Antigravity CLI (agy) installed and signed in
• Claude Code CLI

Installation

1. Clone and build:

git clone https://github.com/Dheerax/agy_mcp.git
cd agy_mcp
npm install
npm run build

2. Register with Claude Code:

claude mcp add -s user agy-mcp-bridge -- node /absolute/path/to/agy_mcp/dist/index.js

Replace /absolute/path/to/agy_mcp with the actual path where you cloned the repo.

3. Set up Claude's instructions (one time):

Open Claude Code, then ask it to run agy_setup. This writes the workflow guide and installs slash-command skills to ~/.claude/.

4. Verify:

claude mcp list
# → agy-mcp-bridge: … ✓ Connected

Feature Overview

Feature	What it does
PTY Bridge	Runs agy in a real pseudo-terminal; handles ConPTY on Windows
Async events	Appends JSONL events to ~/.agy-mcp-events.jsonl — no polling needed
Multi-session	Run up to 3 parallel agy sessions; batch start with dependency ordering
Context bucket	Tracks every file create/modify/delete in the session's workdir
Task contracts	Enforce max duration, allowed paths, file limits, success patterns
Interruption	Send Ctrl+C mid-task; returns final output buffer
Checkpoints	Auto-saved every 60s; retry failed sessions from any checkpoint
Usage monitor	Parse /usage output; route tasks to flash vs pro by remaining quota
Classifier	Score tasks to decide whether to delegate and which model to use
Stale detection	Detect hung sessions; attempt soft recovery before marking stale
Structured logs	JSON log file at ~/.agy-bridge/logs/bridge.log; per-session raw logs
Image generation	Agy can generate real PNG images via Google AI Pro — use dedicated sessions

Async Workflow

1. agy_start(task)             → { session_id, events_log_path }
2. Monitor(tail -n 0 -f <events_log_path>, persistent: true)
3. Do other work / start more sessions
4. [Monitor fires on each event]
5. agy_read(session_id)        → once, after notification
6. agy_kill(session_id)        → cleanup

Event format: {"session_id":"…","task":"…","status":"idle","timestamp":…}
Statuses: running · idle · waiting_input · stale · done · contract_violated

Important: Use the Claude Code Monitor tool (not PowerShell run_in_background) to watch the events log. Monitor fires on each new line and keeps Claude in the turn so it can react to agy's input prompts.

Slash Commands (installed by agy_setup)

Command	What it does
/agy_status	Show effort level, model preference, active sessions
/agy_mode	Set delegation aggressiveness (Lite / Balanced / Power)
/agy_pref	Set default model (Auto / Flash / Pro)
/agy_sessions	List all running sessions with uptime
/agy_quota	Check flash/pro quota remaining
/agy_kill	Interactively kill one or all sessions

Image Generation

Agy has a built-in GenerateImage tool (Google AI Pro). To use it correctly, give it a dedicated session with an explicit save path:

# Good — dedicated session, explicit path
agy_start("Generate an image of a cyberpunk city at night, save to /path/to/bg.png")

# Bad — bundled with other work (agy will use SVG/code instead)
agy_start("Build a website with a generated background image")

For HTML that needs a generated background, split into two sequential sessions:

1. Generate the image → wait for idle
2. Build the HTML referencing the saved PNG

All MCP Tools

Core Session Tools

Tool	Required args	Returns
agy_start	task	{ session_id, events_log_path }
agy_read	—	{ output, status }
agy_send	input	{ success }
agy_command	command	{ success }
agy_status	—	{ status, exitCode? }
agy_kill	—	{ success }
agy_list	—	{ sessions[] }
agy_switch	session_id	{ success }
agy_active	—	{ active_session_id, status }

agy_start optional args:

• workdir — working directory for the session
• model — "flash" | "pro" | "auto" (auto checks quota and picks best)
• contract — task guardrails object (see Contracts section)

Health & Context

Tool	Returns
agy_health(session_id?)	Full health report: uptime, last activity, recovery attempts, contract violations
agy_context(session_id?, last_n?)	{ operation_log[], file_changes[] } — every file event + command sent
agy_diff(filepath, session_id?)	{ path, tracked, change_type, change_timestamp, current_line_count }

Interruption & Checkpoints

Tool	Returns
agy_interrupt(reason, session_id?)	{ success, output, reason } — sends Ctrl+C, returns final buffer
agy_checkpoint(session_id?)	Saves snapshot → { checkpoint_id, elapsed_seconds, … }
agy_retry(checkpoint_id, hint?)	Spawns new session from checkpoint state
agy_list_checkpoints()	All saved checkpoints sorted by recency

Checkpoints auto-saved every 60s to ~/.agy-bridge/checkpoints/.

Usage & Model Routing

agy_usage(session_id?) → { flash: {used,remaining,limit}, pro: {…}, recommended_model, raw }

Cached 60s per session. Sends /usage to the running session.

Delegation Classifier

agy_classify(task) → {
  should_delegate: boolean,
  reason: string,
  recommended_model: "flash" | "pro",
  estimated_complexity: "low" | "medium" | "high",
  delegation_strategy: "single_session" | "multi_session" | "none"
}

Flash: scanning, reading, boilerplate, tests, summarisation, mechanical refactors.
Pro: architecture, debugging, security features, performance, multi-step workflows.
No-delegate: git ops, package management, single-line edits, shell commands.

Batch Orchestration

agy_batch(tasks[]) → { session_ids[], events_log_path }

Max 3 concurrent sessions. Supports dependency ordering:

[
  { "task": "Generate API spec", "workdir": "/project" },
  { "task": "Write tests for API", "workdir": "/project", "depends_on": "task_0" }
]

Configuration

agy_config(effort_level?)  → { mode, effort_level }   — get/set delegation aggressiveness
agy_setup()                → { status, path }          — one-time install of skills + CLAUDE.md

Logs

agy_logs(session_id?, last_n?) → { logs: LogEntry[] }

Set AGY_DEBUG=true to write raw PTY output to ~/.agy-bridge/logs/{session_id}.raw.log.

Task Contracts

{
  "max_duration_seconds": 300,
  "allowed_paths": ["/project/src"],
  "max_files_created": 10,
  "success_pattern": "done",
  "forbidden_commands": ["rm -rf", "DROP TABLE"]
}

When a contract is violated the session is interrupted and status becomes contract_violated. Check details with agy_health.

Session Statuses

Status	Meaning
starting	Session spawned; waiting for agy sign-in
running	agy is actively producing output
idle	No output for 5s; agy is at prompt
waiting_input	agy is blocking on a y/n or menu prompt
stale	No output for 45s; soft recovery attempted
done	Process exited
error	Process crashed
contract_violated	A task contract rule was broken

Special Keys in agy_send

<enter> <ctrl-c> <tab> <up> <down> <left> <right> <esc> <backspace>

File Layout

~/.agy-bridge/
├── logs/
│   ├── bridge.log              ← structured JSON log
│   └── {session_id}.raw.log    ← raw PTY (AGY_DEBUG=true only)
├── checkpoints/
│   └── {checkpoint_id}.json
└── config.json                 ← effort_level, default_model

~/.agy-mcp-events.jsonl         ← push notification events
~/.claude/skills/agy_*/         ← installed by agy_setup

License

MIT