# agy-subagent-mcp

> Run **Google Antigravity (Gemini)** as an autonomous subagent inside **Claude Code**.

`agy-subagent-mcp` is a Model Context Protocol (MCP) server that exposes Google Antigravity (`agy` CLI) as callable tools for Claude Code. Claude can delegate tasks—such as codebase exploration, architecture analysis, second opinions, and multi-file code generation—to Gemini without needing external API keys or cloud credentials.

---

## Why Use This?

- **Zero API Keys Required**: Leverages your existing local `agy` authentication.
- **Access to Gemini Models**: Use Gemini 3.8 Flash, Gemini 3.1 Pro, and other models alongside Claude.
- **Safety First**:
  - `agy_research` runs **sandboxed** (read-only against real files; edits redirected to scratch).
  - `agy_generate` is **opt-in** (`AGY_ALLOW_WRITES=1`) to prevent unsupervised file modifications.
- **Standard MCP Protocol**: Compatible with Claude Code, Claude Desktop, and any other MCP-compliant client.

---

## Tools Exposed

| Tool | Mode | Description |
| :--- | :--- | :--- |
| **`agy_research`** | Sandboxed (Read-only) | Explores the codebase, searches files, reads implementations, and traces architecture. Cannot modify your working tree. |
| **`agy_generate`** | Unsandboxed (Write access) | Performs multi-step code generation, writes files, and runs shell commands. Disabled by default unless `AGY_ALLOW_WRITES=1`. |
| **`agy_ask`** | Sandboxed | Ask Gemini general technical questions, brainstorm solutions, or get a second opinion. |

---

## Prerequisites

1. **Antigravity CLI (`agy`)**:
   ```bash
   curl -fsSL https://antigravity.google/cli/install.sh | bash
   ```
   Verify with:
   ```bash
   agy --version
   ```

2. **Python 3.10+** (tested on macOS / Linux).

---

## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/naren-m/agy-subagent-mcp.git ~/Projects/agy-subagent-mcp
cd ~/Projects/agy-subagent-mcp
```

### 2. Create Virtual Environment & Install Dependencies

```bash
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
```

### 3. Register with Claude Code

Add the server to your user-wide Claude Code configuration:

```bash
claude mcp add --scope user agy-subagent -- \
  /Users/$USER/Projects/agy-subagent-mcp/.venv/bin/python3 \
  /Users/$USER/Projects/agy-subagent-mcp/server.py
```

Verify that the server is connected:

```bash
claude mcp list
```

---

## Configuration

You can configure options via environment variables using `claude mcp set-env`:

```bash
# Change default model
claude mcp set-env agy-subagent AGY_MODEL=gemini-3.1-pro-high

# Increase timeout (seconds)
claude mcp set-env agy-subagent AGY_TIMEOUT=600

# Enable unsupervised code generation (agy_generate)
claude mcp set-env agy-subagent AGY_ALLOW_WRITES=1
```

### Available Environment Variables

| Variable | Default | Description |
| :--- | :--- | :--- |
| `AGY_BIN` | `~/.local/bin/agy` | Path to the Antigravity CLI binary |
| `AGY_MODEL` | `gemini-3.8-flash-high` | Default Gemini model to invoke |
| `AGY_TIMEOUT` | `300` | Execution timeout in seconds |
| `AGY_ALLOW_WRITES`| `""` (disabled) | Set to `1` to allow `agy_generate` to write files |

---

## Example Usage in Claude Code

Once registered, you can prompt Claude naturally:

> "Use `agy_research` to analyze how authentication and sessions are handled in this repository."

> "Ask `agy_ask` to compare CRDTs and Operational Transformation for collaborative text editing."

> "Use `agy_generate` to implement unit tests for the parser module." *(requires `AGY_ALLOW_WRITES=1`)*

---

## License

MIT © [Naren Mudivarthy](https://github.com/naren-m)