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.

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

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:

{
  "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