Skip to main content
Glama
Antigravity OpenCode Delegate

Antigravity OpenCode Delegate

Antigravity OpenCode Delegate (agy-opencode-mcp)

English | 简体中文

An Antigravity (agy) native plugin and stdio MCP bridge that delegates read-only codebase analysis and bounded development tasks to local OpenCode 2 (opencode), while Antigravity retains specification, planning, git diff review, and independent verification.

Ported from liuxiaofengone/opencode-mcp (originally forked from yuriisamohvalov-creator/opencode-mcp, preserving the MIT license and upstream attribution in NOTICE.md) specifically for Antigravity.

Key Characteristics

  • Clear Responsibility Split: Antigravity acts as planner, reviewer, and verifier; local OpenCode 2 runs as a bounded executor inside an isolated session (--format json) and returns structured results with Git context (diffStat, statusShort).

  • Native Antigravity Plugin (plugins/opencode-delegate/): Ships plugin.json, mcp_config.json (${PLUGIN_ROOT}/mcp/server.mjs, timeoutSeconds: 3660), assets/logo.svg, and the opencode-delegate skill with reference.md.

  • Zero-Install Single-File Bundle: build-plugin.mjs bundles server.mjs and src/ with esbuild into plugins/opencode-delegate/mcp/server.mjs (tracked in Git), so the plugin runs offline without npm install.

  • Eager / Lazy Tool Split & Gemini Schema Compatibility: Read-only diagnostic and status tools (opencode_doctor, opencode_models, opencode_status) are marked "eager": true in mcp_config.json. Execution and cancellation tools (opencode_execute, opencode_start, opencode_cancel) stay lazy-loaded for call_mcp_tool, and all integer schema bounds stay within 32-bit signed limits.

  • Mandatory Explicit Model Gate: Every opencode_execute and opencode_start call requires a complete provider/model[#variant] ID (MODEL_REQUIRED / MODEL_INVALID rejects missing or malformed IDs before spawning). Use opencode_models to inspect configured models first—there is no silent default or fallback model selection.

  • Read-Only & Isolation Defaults: Defaults to readOnly: true, standalone: true, and autoApprove: false, injecting an isolated agy-mcp-reader agent via OPENCODE_CONFIG_CONTENT (overriding both legacy and native permission fields to deny edit, write, patch, bash, shell, task, external_directory, webfetch, and websearch). Session continuation (sessionId, continueSession: true) is rejected so cwd and permissions remain authoritative. (Note: OpenCode permissions are application-level controls, not an OS sandbox; exclude sensitive files such as .env or private keys in task briefs.)

  • Shell-Free Execution, Redaction & Process-Tree Cleanup: Never spawns OpenCode through a shell (shell: false) and rejects .cmd/.bat/.ps1 wrappers for OPENCODE_BIN. Redacts common credentials (server password, Bearer tokens, API keys/passwords) from output and errors, caps stdout line/text/stderr buffers, and terminates owned process trees (taskkill.exe /T /F on Windows; process-group SIGTERM/SIGKILL on POSIX) on timeout, cancellation, or MCP disconnect.

  • Async Background Job Lifecycle: opencode_start, opencode_status, and opencode_cancel support up to 4 concurrent background jobs (retaining up to 50 terminal results in memory) with live elapsedMs and lastEventAgeMs progress tracking to distinguish long thinking/tool calls from hangs.

  • Portable Validator & Cross-Platform Test Suite: validate-plugin.mjs runs with zero third-party dependencies to verify manifest semver, UTF-8 BOM hygiene, ${PLUGIN_ROOT} relative paths, symlink/junction escapes, and absence of leaked user paths, backed by 49 automated tests and a Linux/Windows/macOS CI matrix (Node 22 & 24).

Related MCP server: zcode-mcp

MCP Tools Overview

Tool

Loading

Purpose

Key Notes

opencode_doctor

Eager

Verify native OpenCode binary, --version, and optional deep: true model catalog probe

Read-only; rejects .cmd/.bat/.ps1 wrappers

opencode_models

Eager

List deduplicated provider/model IDs via opencode models --standalone

Supports provider prefix filter; invokes no LLM

opencode_status

Eager

Poll async job state (running, cancelling, completed, failed, cancelled) and live progress

Reports elapsedMs and lastEventAgeMs

opencode_execute

Lazy

Run a bounded task synchronously in a fresh session

Requires task, cwd, model; default timeoutMs: 900000 (max 3600000)

opencode_start

Lazy

Start an async background job and return jobId immediately

Max 4 active jobs; poll opencode_status

opencode_cancel

Lazy

Abort an active job and terminate its owned process tree

Poll opencode_status until cancelled

Prerequisites

  • Node.js >= 22

  • Antigravity (agy CLI)

  • Local OpenCode 2 installed with at least one configured model provider (verify with opencode --version and opencode models)

Install From Git

git clone https://github.com/liuxiaofengone/agy-opencode-mcp.git
Set-Location agy-opencode-mcp
agy plugin validate ./plugins/opencode-delegate --strict
agy plugin install ./plugins/opencode-delegate
agy plugin list --json

Windows directory junction note: If the repository checkout sits under a directory junction (causing agy plugin install to fail with path/rename errors), copy plugins/opencode-delegate directly to ~/.gemini/config/plugins/opencode-delegate and verify with agy plugin validate ~/.gemini/config/plugins/opencode-delegate --strict.

If OpenCode is not discovered automatically, set OPENCODE_BIN in the installed plugin's mcp_config.json (env.OPENCODE_BIN) to the native executable absolute path (never a .cmd, .bat, or .ps1 wrapper).

After installing or updating mcp_config.json, refresh MCP servers (or restart Antigravity) and open a new Antigravity chat, then run opencode_doctor({ deep: true }) to verify the OpenCode binary and model catalog.

Repository Structure

agy-opencode-mcp/
├── server.mjs                          # Canonical stdio MCP server entrypoint
├── src/
│   ├── runner.mjs                      # Executable discovery, read-only config injection, process & git runner
│   ├── jobs.mjs                        # Bounded async job manager (start/status/cancel/prune)
│   ├── events.mjs                      # Streaming NDJSON event parser with line/text overflow bounds
│   └── version.mjs                     # Package/plugin version resolver
├── plugins/opencode-delegate/
│   ├── plugin.json                     # Antigravity plugin manifest
│   ├── mcp_config.json                 # MCP config (${PLUGIN_ROOT}/mcp/server.mjs, eager/lazy split)
│   ├── mcp/server.mjs                  # Tracked single-file esbuild bundle
│   ├── assets/logo.svg                 # Plugin icon
│   └── skills/opencode-delegate/       # Delegation rules (SKILL.md) & reference (reference.md)
├── scripts/
│   ├── build-plugin.mjs                # esbuild bundler for plugins/opencode-delegate/mcp/server.mjs
│   ├── validate-plugin.mjs             # Zero-dependency Antigravity plugin contract validator
│   └── smoke.mjs                       # Opt-in live smoke test against a temporary fixture directory
└── test/                               # Node built-in test suite (49 tests)

Development & Verification

npm install
npm run build:plugin
npm test
npm run validate:plugin
agy plugin validate ./plugins/opencode-delegate --strict --json

Optional live smoke test (uses an explicitly authorized model and only touches a temporary fixture directory):

npm run test:live -- your-provider/your-model

Troubleshooting

  • MODEL_REQUIRED / MODEL_INVALID: Always pass a full provider/model (or provider/model#variant) ID without whitespace. Call opencode_models if unsure which models are configured locally.

  • agent.found: false in opencode_doctor: OpenCode native binary was not found, or OPENCODE_BIN points to a .cmd/.bat/.ps1 script. Set OPENCODE_BIN to the native opencode.exe (or opencode on POSIX) path.

  • New/updated tools not visible in Antigravity: Check plugin tool toggles in Antigravity, refresh MCP servers, and start a new chat session so the updated mcp_config.json and schemas load.

  • Long-running tasks timing out: Prefer opencode_start + opencode_status instead of synchronous opencode_execute, and check git status / git diff before retrying any interrupted run.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients such as Claude Code, Codex CLI, and Cursor-agent to delegate bounded coding tasks to a local OpenCode v2.x installation via a single opencode_execute tool, returning the model's response, git diff/status summary, exit code, and session ID.
      1
      20 npm
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Enables a DeepSeek Harness agent to delegate bounded coding tasks to a local ZCode runtime, follow their progress through events, and review the resulting diffs before accepting or continuing the work. It also exposes model catalog, default-model, and setup-diagnostics tools for managing those delegated tasks.
      12
      Apache 2.0