Antigravity Subagent Sidecar

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

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

Related MCP server: MCP Server with Google ADK

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.

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

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

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

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:

node dist/src/commands/manage.js snippet

Or configure the bundled server directly:

{
  "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 as an agent instruction or skill when the host supports skills.

Delegation lifecycle

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:

OpenCode model translation can be configured in the bridge-owned file %LOCALAPPDATA%\codex-antigravity-bridge\state\adapter-config.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

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

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

Uninstall only bridge-owned registrations and files:

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