# agy-mcp

An MCP server that lets [Claude Code](https://claude.com/claude-code) drive [agy](https://antigravity.google/) (Google's Antigravity CLI) as a tool — for a second opinion, or to actually execute a plan.

## Why

Claude Code writes the plan; `agy` (a separate model/agent) either reviews it (`agy_ask`) or executes it (`agy_execute`) in its own isolated git worktree. Session state (which `agy` conversation maps to which of our sessions) is kept in a small SQLite database, so both tools support multi-turn conversations.

## Tools

- **`agy_ask(prompt, session_id?, conversation_id?, workspace?)`** — Read-only. Runs `agy` in `--mode plan` (it cannot edit files). Pass `session_id` to continue a conversation this server started, or `conversation_id` to adopt an existing `agy` CLI conversation (e.g. one you started in your own terminal — this does not work for Antigravity IDE conversations, which use a separate store).
- **`agy_execute(plan, session_id?, conversation_id?, workspace?)`** — Hands `agy` full write access (`--dangerously-skip-permissions`) inside a fresh git worktree, never the real working tree. Changes are auto-committed to a branch (`agy/<short-id>`) so they survive even if the worktree is later removed — unless the pre-commit secret scan blocks it (see below). **Disabled unless `AGY_MCP_ALLOW_EXECUTE=1`** is set in the server's environment.
- **`agy_list_sessions()`** — Lists all known sessions with status, workspace, and worktree path.
- **`agy_close_session(session_id, remove_worktree?)`** — Closes a session. By default the worktree/branch are left on disk for manual review; `remove_worktree: true` deletes the worktree (irreversible for anything not committed).

## Setup

```bash
npm install
npm run build
```

Register it with Claude Code (e.g. in `~/.claude.json`, alongside your other `mcpServers`):

```json
"agy-mcp": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/agy_mcp/dist/index.js"],
  "env": { "AGY_MCP_ALLOW_EXECUTE": "1" }
}
```

Omit `AGY_MCP_ALLOW_EXECUTE` to keep `agy_execute` disabled and only allow `agy_ask` (read-only).

## Safety notes

`agy_execute` isolates the *git working tree* (via a worktree) but does **not** sandbox the filesystem or network — see [PILOT_TEST_REPORT.md](./PILOT_TEST_REPORT.md) for the audit that drove the current mitigations:

- child process env is allowlisted (`PATH`, `HOME`, `TMPDIR`, `LANG`, `LC_ALL` only — no inherited secrets)
- a pre-commit scan blocks commits containing likely secrets (AWS/GitHub/Slack key shapes, private key headers, `.env`-style filenames) and leaves the worktree untouched for manual review
- new-conversation creation is serialized server-wide to avoid a conversation-id race
- `ask` and `execute` sessions can't be resumed across each other
- a timed-out `agy` process (and its subprocess tree) is killed, not left orphaned

None of this replaces running `agy_execute` in a disposable, credential-free, egress-restricted environment for anything beyond low-stakes local use — see the report's "Conditional pilot controls" for the full checklist.

## Requirements

- Node.js ≥ 22.5 (uses the built-in `node:sqlite`)
- The `agy` CLI on `PATH` (override with `AGY_BIN`), already authenticated
- Git (for `agy_execute`'s worktree isolation)