Skip to main content
Glama

codex-antigravity-plugin

An Antigravity global plugin and MCP bridge that lets Antigravity delegate coding, debugging, refactoring, and code reviews to OpenAI Codex just like a native subagent.

Built on top of codex app-server (compatible with Codex CLI >= 0.154.0, tested on 0.162.0—note that legacy codex mcp-server was removed in 0.154.0).

中文说明

Architecture

Antigravity (Planner / Orchestrator)
  ├── invoke_subagent("codex")  ← agents/codex.md (isolated context, diff verification)
  ├── /codex-delegate           ← skills/codex-delegate/ (routing, workspace vs. worktree, XML prompt recipes)
  ├── /codex-review             ← skills/codex-review/ (standard & adversarial read-only review)
  └── MCP: codex_bridge         ← mcp_config.json → scripts/launch-mcp.sh → server.mjs
         └── persistent `codex app-server` JSON-RPC process (threads, approvals, diffs, worktrees)

What this builds on & improves

This project stands on the shoulders of two open-source foundations:

  • Goudu666/codex-app-server-mcp (MIT): persistent codex app-server bridge, multi-turn thread_id continuity, async wait_seconds, two-way codex_respond, codex_steer, codex_interrupt, codex_review, and isolated git worktrees.

  • openai/codex-plugin-cc (Apache-2.0): XML prompt contracts, result-handling discipline, and adversarial review workflow.

Targeted improvements for Antigravity (v0.2.0):

  1. Native Antigravity Subagent (agents/codex.md): Call invoke_subagent(TypeName="codex") (and follow up via send_message) so Codex work stays isolated from the main conversation context and runs cleanly in parallel.

  2. macOS/Linux GUI PATH & Sandbox Resilience: scripts/launch-mcp.sh and lib/app-server.mjs append Homebrew, nvm (preferring ~/.nvm/alias/default or newest version), fnm, volta, and standard fallback paths after the user's PATH so GUI-spawned MCP servers work without overriding user-chosen binaries.

  3. Antigravity Timeout & RPC Recovery: Default wait_seconds is 90 (CODEX_WAIT_SECONDS), timeoutSeconds: 600 in mcp_config.json, and CODEX_RPC_TIMEOUT_MS (default 60000 ms, initialize capped at 45000 ms) kills wedged app-server children and respawns cleanly on timeout.

  4. Hardened Worktree Lifecycle: Metadata sidecars under ~/.codex-mcp/meta keep worktree git status clean, capture baseHead so codex_worktree(action="diff") surfaces both committed-on-branch and uncommitted edits with UTF-8 byte-exact truncation, and enforce strict ownership checks (~/.codex-mcp/worktrees + linked worktree + sidecar/codex/*) before removal, with atomic rollback if thread/start fails.

  5. Concurrency & Bounded Memory: Per-thread turn-start guards (startingTurn) and thread/resume deduplication (loadingPromise), plus automatic pruning of prior-turn items/diffs, 64 KiB diff caps, and eviction of settled threads beyond 100.

  6. Multimodal Input: codex_run accepts images (localImage paths, validated before starting a thread/turn) for screenshots or UI mockups.

Related MCP server: antigravity-workers

Prerequisites

  • Node.js >= 20

  • OpenAI Codex CLI installed and authenticated (npm i -g @openai/codex && codex login)

Install as a Global Antigravity Plugin

git clone https://github.com/liizhuoo/codex-antigravity-plugin.git ~/.gemini/config/plugins/codex
cd ~/.gemini/config/plugins/codex
npm install --omit=dev

Antigravity automatically discovers ~/.gemini/config/plugins/codex.

Workspace vs. Worktree Guide

Scenario

Recommended Mode

Sequential bugfix/feature in active branch, or builds on uncommitted edits

Current workspace (worktree: false, sandbox: "workspace-write")

Parallel tasks (2+ workers), broad/risky refactor, or diff-before-merge

Isolated worktree (worktree: true, sandbox: "workspace-write")

Code review, architecture challenge, or diagnosis without edits

Read-only (codex_review or sandbox: "read-only")

Note: Git worktrees branch from HEAD, so uncommitted edits in the parent workspace are not included in a new worktree (parent_dirty: true warns when detected).

MCP Tools (codex_bridge)

  • codex_run — Start or continue (thread_id) a Codex task (cwd, worktree, sandbox, approval, model, effort, images, web_search, output_schema, wait_seconds)

  • codex_wait — Wait on one or multiple threads (mode: "all" | "any")

  • codex_status — Non-blocking progress peek

  • codex_respond — Answer pending approvals or user-input questions (request_id)

  • codex_steer / codex_interrupt — Steer or stop a running turn

  • codex_review — Native read-only or adversarial: true code review

  • codex_worktree — list, diff, or safely remove managed worktrees under ~/.codex-mcp/worktrees

  • codex_compact / codex_models / codex_threads — Thread compaction, available models, and thread history (compatible with Codex App/CLI via codex resume <thread_id>)

Tests

npm test                                               # offline unit + MCP protocol suite (zero quota)
node test/e2e.mjs /tmp/codex-scratch --model gpt-6-luna --effort low

中文说明

让 Antigravity 像调用原生 Subagent 一样调度本地 OpenAI Codex CLI(codex app-server,兼容 >= 0.154.0),并同时提供直接 MCP 调用与 /codex-review、/codex-delegate 工作流。

  • 安装:克隆本仓库到 ~/.gemini/config/plugins/codex 并执行 npm install --omit=dev 即可全局生效。

  • 使用方式:

    • 直接在对话里让 Antigravity「让 codex 实现/修复/重构…」或「让 codex review 一下代码」,会自动通过 codex Subagent 或 codex_* MCP 工具调度。

    • 工作区 vs. Worktree:单线局部修改/依赖未提交改动时直接改当前工作区;并发多任务或大重构时启用 worktree: true 隔离开发,完成后通过 codex_worktree(action="diff") 验收再合并清理。

    • 人工接管:每次返回均附带 thread_id,随时可在终端运行 codex resume <thread_id> 继续同一会话。

License

MIT — see LICENSE and NOTICE.

Available Tools

11 tools
codex_compactCompact a Codex threadB

Summarize a long Codex thread's history to free up its context window. Runs in the background.

Inputs: thread_id (required).

codex_interruptInterrupt a Codex turnC

Stop the running turn on a Codex thread.

Inputs: thread_id (required).

codex_modelsList Codex modelsB

Models available to this Codex login, with supported reasoning efforts.

Inputs: include_hidden.

codex_respondAnswer CodexA

Answer a request Codex is blocked on (listed in pending_requests). Approvals take decision: accept | acceptForSession | decline | cancel. Questions take answers: { : "answer" }. Ask the user first for risky/destructive actions or architectural choices.

Inputs: request_id (required), answers, decision, wait_seconds.

codex_reviewCodex code reviewA

Run Codex's native code review (read-only) in a git repo. The review text comes back in the "review" field. Pass focus and/or adversarial: true for a steerable review that challenges assumptions and edge cases.

Inputs: cwd (required), focus, model, effort, +5 more.

codex_runRun a Codex taskA

Give Codex (OpenAI coding agent) a task. Starts a new thread, or continues an existing one when thread_id is given. Blocks up to wait_seconds, then returns status, Codex's latest message, files changed, diff preview, and commands run. status "inProgress" → codex_wait; "waitingForInput" → answer pending_requests with codex_respond. Run several threads in parallel by calling codex_run with wait_seconds: 0 (prefer worktree: true), then codex_wait with all thread_ids. Verify Codex's diff/changes before reporting them as done.

Inputs: prompt (required), cwd, model, effort, +8 more.

codex_statusPeek at CodexA

Non-blocking snapshot of Codex threads in this session: status, what Codex is doing right now, pending requests.

Inputs: thread_ids.

codex_steerSteer a running Codex turnB

Add instructions to the turn Codex is currently working on, without stopping it.

Inputs: prompt (required), thread_id (required), wait_seconds.

codex_threadsList Codex threadsA

List recent Codex threads (including ones from the Codex app/CLI), newest first. Continue one with codex_run + thread_id.

Inputs: cwd, limit.

codex_waitWait for CodexB

Wait for turns on one or more Codex threads, then return their reports. mode "all" (default) returns when every thread is done or blocked on a request; "any" returns as soon as one is.

Inputs: mode, thread_id, thread_ids, wait_seconds.

codex_worktreeInspect or clean up Codex worktreesB

List managed Codex worktrees (~/.codex-mcp/worktrees), inspect git status & diff inside a worktree, or remove a finished worktree.

Inputs: action (required), cwd, path, force, +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Each tool has a distinct role in the Codex lifecycle (run, wait, status, respond, steer, interrupt, review, worktree, compact, models, threads). The only real overlap risk is codex_status vs codex_wait vs codex_threads, but the descriptions sharply delineate blocking vs non-blocking vs listing behavior.

    Naming Consistency5/5

    Every tool follows the same codex_<verb|noun> snake_case pattern with no deviations. Names are short, predictable, and immediately readable.

    Tool Count5/5

    11 tools is well within the sweet spot, and each maps to a necessary operation (start, observe, interact, control, inspect). No redundant or filler tools are present.

    Completeness4/5

    The surface covers the full interaction lifecycle: launch, wait, snapshot, respond to approvals/questions, steer, interrupt, review, compact, and worktree cleanup, plus discovery of models and prior threads. Minor gaps: no explicit thread close/delete or fork operation, and worktree management is limited to list/inspect/remove.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables a local Codex chat to ask a second opinion, review staged, unstaged, or revision-based diffs, and delegate coding tasks to the Antigravity CLI running in isolated or disposable workspaces. Supports starting, polling, retrieving, and cancelling tasks with returned answers, diffs, changed-file lists, exit codes, and time/output limits, while never auto-applying returned patches.
      8
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude Code or any MCP client to delegate hands-on coding work to OpenAI Codex over a persistent app-server process, keeping long-lived threads with follow-ups, async polling, approvals, steering, and interrupts. Supports native code review, resuming existing sessions, structured output, and parallel worktree-isolated tasks.
      10
      34 npm
      1
      MIT