codex_bridge
Integrates with OpenAI Codex through the Codex app-server to delegate coding, debugging, refactoring, and code review tasks, with support for persistent threads, approvals, steering, interruption, model selection, and isolated worktree-based runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex_bridge refactor the auth module and run the tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serverbridge, multi-turnthread_idcontinuity, asyncwait_seconds, two-waycodex_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):
Native Antigravity Subagent (
agents/codex.md): Callinvoke_subagent(TypeName="codex")(and follow up viasend_message) so Codex work stays isolated from the main conversation context and runs cleanly in parallel.macOS/Linux GUI
PATH& Sandbox Resilience:scripts/launch-mcp.shandlib/app-server.mjsappend Homebrew, nvm (preferring~/.nvm/alias/defaultor newest version), fnm, volta, and standard fallback paths after the user'sPATHso GUI-spawned MCP servers work without overriding user-chosen binaries.Antigravity Timeout & RPC Recovery: Default
wait_secondsis90(CODEX_WAIT_SECONDS),timeoutSeconds: 600inmcp_config.json, andCODEX_RPC_TIMEOUT_MS(default60000ms,initializecapped at45000ms) kills wedged app-server children and respawns cleanly on timeout.Hardened Worktree Lifecycle: Metadata sidecars under
~/.codex-mcp/metakeep worktreegit statusclean, capturebaseHeadsocodex_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 ifthread/startfails.Concurrency & Bounded Memory: Per-thread turn-start guards (
startingTurn) andthread/resumededuplication (loadingPromise), plus automatic pruning of prior-turn items/diffs,64 KiBdiff caps, and eviction of settled threads beyond100.Multimodal Input:
codex_runacceptsimages(localImagepaths, validated before starting a thread/turn) for screenshots or UI mockups.
Related MCP server: antigravity-workers
Prerequisites
Node.js
>= 20OpenAI 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=devAntigravity 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 ( |
Parallel tasks ( | Isolated worktree ( |
Code review, architecture challenge, or diagnosis without edits | Read-only ( |
Note: Git worktrees branch from
HEAD, so uncommitted edits in the parent workspace are not included in a new worktree (parent_dirty: truewarns 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 peekcodex_respond— Answer pending approvals or user-input questions (request_id)codex_steer/codex_interrupt— Steer or stop a running turncodex_review— Native read-only oradversarial: truecode reviewcodex_worktree—list,diff, or safelyremovemanaged worktrees under~/.codex-mcp/worktreescodex_compact/codex_models/codex_threads— Thread compaction, available models, and thread history (compatible with Codex App/CLI viacodex 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 一下代码」,会自动通过
codexSubagent 或codex_*MCP 工具调度。工作区 vs. Worktree:单线局部修改/依赖未提交改动时直接改当前工作区;并发多任务或大重构时启用
worktree: true隔离开发,完成后通过codex_worktree(action="diff")验收再合并清理。人工接管:每次返回均附带
thread_id,随时可在终端运行codex resume <thread_id>继续同一会话。
License
Available Tools
11 toolscodex_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
Scored across 11 tools
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.
Every tool follows the same codex_<verb|noun> snake_case pattern with no deviations. Names are short, predictable, and immediately readable.
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.
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
Related MCP Connectors
Shared long-term memory & Stop-hook task handoff across Claude Code, Codex, Cursor, and mobile.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables Claude Code and Claude Desktop to delegate token-heavy tasks to Antigravity headless subagents, offloading file edits, test runs, and exploration while preserving Claude's context window.121MIT
- AlicenseAqualityCmaintenanceEnables Codex to delegate bounded code analysis, review, isolated edits, multimodal research, and native image generation to supervised Antigravity workers, with queued execution, retries, and inspectable patches.232MIT
- AlicenseBqualityCmaintenanceEnables 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.81MIT
- AlicenseAqualityBmaintenanceEnables 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.1034 npm1MIT