# Antigravity Subagent Sidecar

Use native Google Antigravity subagents as parallel workers for Codex, OpenCode, or any MCP-capable coding agent.

> [!WARNING]
> The AGY 1.1.2 CLI backend currently fails its live feasibility probe. AGY loads the bridge hook but rejects the documented injected `toolCall` before creating a child. Release 0.3.4 therefore fails closed before launching a controller or worker; it does not advertise working delegation. A compliant replacement backend requires the official Antigravity SDK with an AI Studio or Vertex API key.

The orchestrator keeps planning and final decisions. The sidecar sends delegated tasks to thin Antigravity children and returns compact results without copying raw terminal output, reasoning, or tool logs into the host context.

## What you get

- Portable stdio MCP contract for spawn, status, steering, cancellation, and health tools
- Codex plugin with the MCP server and a transport skill
- Transparent OpenCode `task` replacement with the native task schema
- Up to eight parallel children per spawn request once a live-compatible backend is available
- Messages in both directions while a child is running once a live-compatible backend is available
- Fail-closed compatibility reporting for the currently unavailable CLI backend
- Windows-safe hook execution and explicit controller hook discovery
- No changes to Antigravity prompts, MCP configuration, skills, plugins, or authentication

## Requirements

The initial tested environment is:

- Windows
- Node.js 20 or newer
- Antigravity CLI (`agy`) 1.1.2 (known incompatible with the injected-tool controller backend)
- Codex 0.144.3 and/or OpenCode 1.17.20

Do not use the package to route a consumer Antigravity login through third-party coding agents. Google's current FAQ directs third-party integrations to Vertex or AI Studio credentials.

```powershell
agy --version
node --version
```

No Antigravity-side plugin is installed. Existing Antigravity MCP servers are available to a child only when that job enables MCP tools.

## Quick start

```powershell
git clone https://github.com/khanra17/antigravity-subagent-sidecar.git
cd antigravity-subagent-sidecar
npm ci
npm run test:all
```

`test:all` builds the self-contained distribution in `dist/bundle` and runs the contract suite.

### Codex

```powershell
node dist/src/commands/manage.js install codex --dry-run
node dist/src/commands/manage.js install codex
```

Restart Codex. The plugin adds the `antigravity-subagents` MCP server and transport skill. Codex still decides *when* delegation is useful; the skill changes only *where* that delegated work runs.

### OpenCode

```powershell
node dist/src/commands/manage.js install opencode --dry-run
node dist/src/commands/manage.js install opencode
```

Restart OpenCode. The adapter shadows its native `task` tool, keeps the same arguments and permission check, and routes the task to Antigravity. It does not expose duplicate `antigravity_*` tools to the OpenCode model.

### Other MCP clients

Generate a ready-to-copy configuration:

```powershell
node dist/src/commands/manage.js snippet
```

Or configure the bundled server directly:

```json
{
  "mcpServers": {
    "antigravity-subagents": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\antigravity-subagent-sidecar\\dist\\bundle\\mcp\\server.mjs"]
    }
  }
}
```

For generic MCP clients, include [`assets/skills/antigravity-subagents/SKILL.md`](assets/skills/antigravity-subagents/SKILL.md) as an agent instruction or skill when the host supports skills.

## Delegation lifecycle

| MCP tool | Purpose |
| --- | --- |
| `antigravity_spawn_agents` | Start 1–8 children; optionally wait for start, a message, or completion |
| `antigravity_get_agents` | Poll compact status, messages, and results using message cursors |
| `antigravity_send_message` | Steer a running child or continue an idle child |
| `antigravity_cancel_agents` | Stop children and their descendants |
| `antigravity_info` | Check versions, compatibility, models, controllers, and MCP server names |

Independent children run concurrently. Controller transcript mutations are briefly serialized per workspace/model, but active child work is not serialized.

The three capability switches map directly to Antigravity's native groups:

- `enable_write_tools`: file modification and terminal tools
- `enable_mcp_tools`: MCP tools from the user's existing Antigravity configuration
- `enable_subagent_tools`: nested child delegation

Read/search tools remain the native baseline. Individual built-in tools or MCP servers cannot currently be allowlisted through Antigravity's documented subagent schema.

## Configuration

All settings are optional:

| Environment variable | Meaning |
| --- | --- |
| `AGY_PATH` | Path to `agy.exe` |
| `AG_BRIDGE_STATE_DIR` | Sidecar-owned controllers, requests, handles, and logs |
| `AG_BRIDGE_DEFAULT_MODEL` | Default Antigravity model |
| `AG_BRIDGE_TIMEOUT_SECONDS` | Operation timeout |
| `AG_BRIDGE_MAX_BATCH` | Maximum jobs per spawn request, capped at 8 |
| `AG_BRIDGE_LOG_LEVEL` | `error`, `warn`, `info`, or `debug` |

OpenCode model translation can be configured in the bridge-owned file `%LOCALAPPDATA%\codex-antigravity-bridge\state\adapter-config.json`:

```json
{
  "schemaVersion": 1,
  "opencode": {
    "defaultModel": "ANTIGRAVITY_MODEL",
    "modelMap": {
      "explore": "ANTIGRAVITY_MODEL",
      "provider/source-model": "ANTIGRAVITY_MODEL"
    }
  }
}
```

Agent-name mappings win over source-model mappings, followed by the OpenCode default and then `AG_BRIDGE_DEFAULT_MODEL`.

## Permission and isolation model

Every Antigravity process is launched with `--dangerously-skip-permissions`; this is enforced and cannot be disabled through MCP input. The sidecar aborts when AGY does not report `toolPermission=always-proceed`.

This bypasses Antigravity approval prompts. It does **not** bypass Windows ACLs, MCP authentication, unavailable tools, network failures, or hook denials. Enable write, MCP, and nested-agent capability groups only when the delegated task needs them.

Task text is stored in sidecar state and injected into native child calls. Controller prompts contain only signed, one-use opaque request markers. Raw AGY stdout, stderr, reasoning, and tool logs stay local.

## Project structure

```text
src/
├── bridge/              # Contracts, configuration, state, request security
├── antigravity/         # CLI runtime, process control, hooks, transcripts
├── application/         # Host-neutral delegation lifecycle
├── integrations/mcp/    # Portable MCP transport
├── adapters/opencode/   # OpenCode task adapter
└── commands/            # Installer and live verifier
```

## Maintenance

```powershell
npm run test:all
node dist/src/commands/manage.js status
```

Uninstall only bridge-owned registrations and files:

```powershell
node dist/src/commands/manage.js uninstall codex
node dist/src/commands/manage.js uninstall opencode
```

Live verification creates Antigravity history and a native child, so it is explicitly opt-in. See the `verify-live` script and use only a disposable workspace.

## Compatibility

The bridge fails closed when the AGY or OpenCode contract changes. It never silently falls back to a host-native subagent or a terminal-steered Antigravity main-agent session.

## License

[MIT](LICENSE)