Skip to main content
Glama
README.md
# codex-antigravity-plugin

An [Antigravity](https://antigravity.google) 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`](https://developers.openai.com/codex/) (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

```text
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](https://github.com/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](https://github.com/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.

## Prerequisites

- Node.js `>= 20`
- OpenAI Codex CLI installed and authenticated (`npm i -g @openai/codex && codex login`)

## Install as a Global Antigravity Plugin

```bash
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

```bash
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](LICENSE) and [NOTICE](NOTICE).

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