@minhspark/codex-mcp-bridge 1.23.0 → 1.24.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,26 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-10-28
+
+### Added
+
+- Optional Antigravity MCP bridge for verified Codex and Claude Desktop callers. Select an exact existing Antigravity App conversation or explicitly create a bridge-owned CLI streaming session in the same project directory.
+- Native App sidecar transport with current-user socket access, native workspace/project checks, busy-recipient protection, and durable request receipts. CLI streaming validates native conversation identity and preserves permission review; results and uncertain outcomes are recorded without automatic resends.
+- `antigravity-mcp-bridge-install` configures Codex, Claude, and the App sidecar independently or together, previews changes with `--dry-run`, preserves unrelated configuration, and removes only its own registrations.
+- Antigravity Desktop's `agent-bridge` MCP can discover, read, and send to existing Codex Desktop tasks and live Claude Desktop Code sessions in the same project. Native per-call sender metadata, process ancestry, project configuration, and permission checks preserve Antigravity authorship and recipient policy.
+- Sidecars track their native parent process identity and exit when that parent stops, preventing a restarted App from retaining an orphan's stale connection. Desktop callers without workspace metadata resolve their directory through exact native conversation and project evidence.
+
+### Compatibility
+
+- Node.js 22.13 or newer is required for read-only native conversation discovery. The App adapter filters mirrored CLI records rather than trusting the database directory alone.
+- App receipts report native acceptance; App response forwarding and creation are not implemented. CLI support uses bridge-owned headless sessions, not attachment to existing interactive terminals. Antigravity outbound is Desktop-only; nested callers and Linux host verification are unsupported. Claude socket writes remain unconfirmed until a native receipt or reply is observed.
+
+### Verification
+
+- Automated coverage includes real MCP transports, caller identity, project scope, current-user pipe access, duplicate requests, native metadata, recipient permission checks, durable receipt states, stream protocol failures, installer preservation, and file replacement during reads.
+- Live Windows verification covered CLI streaming under native `request-review` permissions and both directions between Codex and Antigravity Desktop. The App replied `ANTIGRAVITY_DESKTOP_NATIVE_OK`; its outbound MCP delivered `ANTIGRAVITY_TO_CODEX_DESKTOP_OK` to the exact originating Codex task. Claude outbound routing has automated coverage; a live Claude receiver was unavailable during verification.
+
 ## [1.23.0] - 2026-10-26
 
 ### Added

package/README.md

@@ -17,6 +17,8 @@
 
 Send prompts and replies between **Claude and Codex**, keeping each conversation in its own app. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
 
+The optional **Antigravity bridge** also sends authorized work from Codex or Claude Desktop to an existing Antigravity App conversation or a new Antigravity CLI streaming session. [Setup and current limits](#antigravity-app-and-cli).
+
 https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
 
 ## Installation
@@ -25,7 +27,7 @@ https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
 npm install -g @minhspark/codex-mcp-bridge@latest
 ```
 
-Requires **Node.js 22+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
+Requires **Node.js 22.13+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
 
 On macOS or Linux you can install with [Homebrew](https://github.com/buidangminh23/homebrew-tap) instead, which brings its own Node.js:
 
@@ -37,6 +39,35 @@ Update with `brew upgrade codex-mcp-bridge`. The installers record Homebrew's st
 
 [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [ChatGPT plugin](#chatgpt-plugin)
 
+### Antigravity App and CLI
+
+Install and sign in to the Antigravity App and/or `agy` CLI, then run:
+
+```bash
+antigravity-mcp-bridge-install --all
+```
+
+Use `.cmd` on Windows. Select `--codex`, `--claude`, or `--desktop` to install individual components; `--dry-run` previews changes. The installer preserves unrelated configuration and native permissions. Reload Codex/Claude to load the new MCP server. Antigravity launches its own sidecar from `~/.gemini/config/sidecars/codex-bridge/sidecar.json`; do not run that sidecar manually or copy authentication environment variables between processes.
+
+| Tool | Behavior |
+| --- | --- |
+| `antigravity_bridge_status` | Reports native sidecar connectivity and CLI capabilities. |
+| `list_antigravity_conversations` | Lists the selected surface in the verified sender's exact project directory. |
+| `send_to_antigravity_conversation` | Sends to an exact existing App conversation or a CLI session owned by this bridge. |
+| `start_antigravity_cli_session` | Starts an explicitly authorized CLI streaming session with its initial prompt. |
+| `read_antigravity_delivery` | Reads the original receipt without resending. |
+| `close_antigravity_cli_session` | Closes an idle CLI session owned by the sender. |
+
+Generate a new `requestId` UUID for each intentional delivery and reuse it only when inspecting or retrying that same delivery. A pending or unknown receipt must be inspected before further action. Receipts survive process restarts; live CLI processes do not. A CLI timeout retains its conversation identity for inspection. No mode or permission-bypass flag is added; headless tool requests requiring interaction may be denied by Antigravity.
+
+The App adapter uses the official [sidecar `agentapi`](https://antigravity.google/docs/sidecars), verifies native workspace metadata, and refuses busy or ambiguous destinations. An App `accepted` receipt confirms native acceptance, not a completed agent reply. Open the exact App conversation to read its response. The CLI adapter uses the official [streaming JSON interface](https://antigravity.google/docs/cli/headless) and returns the agent's final result. It creates bridge-owned headless sessions; it does not attach to an already running interactive terminal. The two surfaces never substitute for one another.
+
+The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.gemini/config/mcp_config.json`. Reload the App after installation to discover it. From an Antigravity conversation, ask the agent to check `agent_bridge_status`, call `list_agent_tasks` for `codex` or `claude`, then use `send_to_agent_task` with the exact destination ID, project directory, prompt, and a fresh request UUID. Claude destinations also require their native `taskId`. Read `read_agent_delivery` without resending; `read_agent_task` reads the selected Codex task's response or Claude's native task metadata.
+
+Outbound calls verify Antigravity's per-call MCP metadata, Desktop process ancestry, native workspace/project, and effective permission settings. The sender is attributed as Antigravity. Codex keeps its native task settings; Claude's inbound policy and permission-class checks remain in effect. A socket write to Claude is `sent_unconfirmed`, not acceptance or completion. After MCP restart, a saved receipt remains available but live Claude reply tracking may be unavailable; inspect the exact native task before further action.
+
+Outbound support targets existing local Codex tasks and live Claude Desktop Code sessions in the same project. Nested Antigravity callers, outbound CLI callers, App conversation creation, and automatic App reply forwarding are not implemented. Windows Desktop is the live verification platform; macOS ancestry has unit coverage and Linux outbound host verification fails closed. The existing Codex↔Claude bridge remains separate. Use `antigravity-mcp-bridge-install --all --remove` to remove only these registrations; delivery receipts are retained.
+
 ### Windows (PowerShell)
 
 Install and sign in to [Codex Desktop](https://developers.openai.com/codex/app) and [Claude Desktop](https://claude.com/download). Save the project in Codex Desktop and open the same directory in Claude Desktop's **Code tab**. Have the Codex and Claude Code CLIs available.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.23.0",
-  "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
+  "version": "1.24.0",
+  "description": "MCP bridges for Claude, Codex, and Antigravity Desktop and CLI conversations.",
   "keywords": [
     "mcp",
     "codex",
     "claude-code",
     "claude-desktop",
     "app-server",
+    "antigravity",
     "model-context-protocol"
   ],
   "license": "MIT",
@@ -24,6 +25,8 @@
   "bin": {
     "codex-mcp-bridge": "src/codex-bridge-launcher.mjs",
     "claude-mcp-bridge": "src/claude-bridge-launcher.mjs",
+    "antigravity-mcp-bridge": "src/antigravity-bridge.mjs",
+    "antigravity-mcp-bridge-install": "scripts/install-antigravity-bridge.mjs",
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "codex-bridge-code-install": "scripts/install-claude-code.mjs",
     "bridge-projects": "scripts/bridge-projects.mjs",
@@ -62,6 +65,8 @@
     "analytics:publish": "node scripts/publish-repo-analytics.mjs",
     "start": "node src/codex-bridge-launcher.mjs",
     "claude-bridge": "node src/claude-bridge-launcher.mjs",
+    "antigravity-bridge": "node src/antigravity-bridge.mjs",
+    "install:antigravity": "node scripts/install-antigravity-bridge.mjs",
     "app-server": "codex app-server --listen ws://127.0.0.1:8791",
     "test": "node scripts/run-tests.mjs",
     "check": "node scripts/check.mjs",
@@ -79,7 +84,7 @@
     "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs src/native-relay-companion.mjs scripts/install-native-relay.mjs .codex-plugin/plugin.json"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-antigravity-bridge.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { isMainModule, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
+import { resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+const NAME = "antigravity-bridge";
+const SIDECAR = "codex-bridge";
+const OUTBOUND = "agent-bridge";
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a JSON object`);
+  return value;
+}
+
+function snapshot(file) {
+  let descriptor;
+  try { descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); }
+  catch (error) {
+    if (error.code === "ENOENT") return { file, text: null, value: {} };
+    if (error.code === "ELOOP") throw new Error(`Unsafe configuration file: ${file}`);
+    throw error;
+  }
+  const safe = (value) => value.isFile() && !value.isSymbolicLink() && value.nlink === 1 && value.size <= 16 * 1024 * 1024;
+  const matches = (left, right) => safe(right) && left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+  try {
+    const stat = fs.lstatSync(file);
+    const opened = fs.fstatSync(descriptor);
+    if (!safe(stat) || !safe(opened)) throw new Error(`Unsafe configuration file: ${file}`);
+    if (!matches(stat, opened)) throw new Error(`Configuration changed while opening: ${file}`);
+    const buffer = Buffer.alloc(opened.size + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const read = fs.readSync(descriptor, buffer, length, buffer.length - length, length);
+      if (!read) break;
+      length += read;
+    }
+    if (length !== opened.size || !matches(opened, fs.fstatSync(descriptor)) || !matches(opened, fs.lstatSync(file))) throw new Error(`Configuration changed while reading: ${file}`);
+    const text = buffer.subarray(0, length).toString("utf8");
+    return { file, text, value: object(JSON.parse(text), file), mode: opened.mode & 0o777, dev: opened.dev, ino: opened.ino };
+  } finally { fs.closeSync(descriptor); }
+}
+
+export function validateCodexExecutable(executable, { platform = process.platform } = {}) {
+  if (typeof executable !== "string" || !path.isAbsolute(executable) || executable.includes("\0")) throw new Error("Codex executable must be an absolute native executable path");
+  const resolved = fs.realpathSync.native(executable);
+  if (!fs.statSync(resolved).isFile()) throw new Error("Codex executable must be a regular file");
+  if (platform === "win32" && !/\.(exe|com)$/i.test(resolved)) throw new Error("Codex executable must be a native Windows executable, not a shell script");
+  return resolved;
+}
+
+function ownEntry(entry, expected, label) {
+  if (entry === undefined || entry === null) return;
+  object(entry, label);
+  if (!Array.isArray(entry.args) || entry.args.length !== 1 || typeof entry.args[0] !== "string" || path.resolve(entry.args[0]) !== path.resolve(expected)) {
+    throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
+  }
+}
+
+function changed(original, value) {
+  const text = value === null ? null : JSON.stringify(value, null, 2) + "\n";
+  if (text === original.text || value !== null && JSON.stringify(value) === JSON.stringify(original.value)) return null;
+  return { ...original, next: text };
+}
+
+export function planAntigravityInstallation({ home = os.homedir(), root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, codexExisting = null } = {}) {
+  if (!path.isAbsolute(home) || !path.isAbsolute(root) || !path.isAbsolute(node)) throw new Error("Installer paths must be absolute");
+  if (!targets.length || targets.some((target) => !["codex", "claude", "desktop"].includes(target))) throw new Error("Unknown installation target");
+  const entry = path.join(root, "src", "antigravity-bridge.mjs");
+  const sidecarEntry = path.join(root, "src", "antigravity-sidecar.mjs");
+  const outboundEntry = path.join(root, "src", "antigravity-outbound-bridge.mjs");
+  const edits = [];
+  const notices = [];
+  let codex = null;
+  if (targets.includes("codex")) {
+    if (codexExisting && codexExisting.transport?.type !== "stdio") throw new Error("The existing Antigravity MCP transport is not stdio");
+    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge");
+    const existingCaller = codexExisting?.transport?.env?.ANTIGRAVITY_BRIDGE_CALLER;
+    if (existingCaller !== undefined && existingCaller !== "codex") throw new Error("The existing Codex bridge has a conflicting caller identity");
+    codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry, envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
+  }
+  if (targets.includes("claude")) {
+    const original = snapshot(path.join(home, ".claude.json"));
+    const value = structuredClone(original.value);
+    if (value.mcpServers !== undefined) object(value.mcpServers, "Claude mcpServers");
+    const existing = value.mcpServers?.[NAME];
+    ownEntry(existing, entry, "Claude Antigravity bridge");
+    if (existing?.type !== undefined && existing.type !== "stdio") throw new Error("The existing Claude bridge transport is not stdio");
+    if (existing?.env !== undefined) object(existing.env, "Claude bridge environment");
+    if (existing?.env?.ANTIGRAVITY_BRIDGE_CALLER !== undefined && existing.env.ANTIGRAVITY_BRIDGE_CALLER !== "claude") throw new Error("The existing Claude bridge has a conflicting caller identity");
+    if (remove) { if (existing) delete value.mcpServers[NAME]; }
+    else {
+      value.mcpServers ??= {};
+      value.mcpServers[NAME] = { ...existing, type: "stdio", command: node, args: [entry], env: { ...existing?.env, ANTIGRAVITY_BRIDGE_CALLER: "claude" } };
+    }
+    const edit = changed(original, value);
+    if (edit) edits.push(edit);
+  }
+  if (targets.includes("desktop")) {
+    const configRoot = path.join(home, ".gemini", "config");
+    const originalMcp = snapshot(path.join(configRoot, "mcp_config.json"));
+    const mcp = structuredClone(originalMcp.value);
+    if (mcp.mcpServers !== undefined) object(mcp.mcpServers, "Antigravity mcpServers");
+    const outbound = mcp.mcpServers?.[OUTBOUND];
+    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge");
+    if (outbound?.type !== undefined && outbound.type !== "stdio" || outbound?.url !== undefined || outbound?.serverUrl !== undefined || outbound?.httpUrl !== undefined) throw new Error("The existing Antigravity outbound bridge transport is not stdio");
+    if (outbound?.env !== undefined) object(outbound.env, "Antigravity outbound bridge environment");
+    if (Object.keys(outbound?.env ?? {}).some((name) => /^(?:CLAUDE|CODEX_|ANTIGRAVITY_BRIDGE_CALLER$)/i.test(name))) throw new Error("The existing Antigravity outbound bridge contains a foreign caller environment; review it before installation");
+    for (const name of ["codex-bridge", "claude-bridge"]) {
+      if (Object.hasOwn(mcp.mcpServers ?? {}, name)) notices.push(`Existing Antigravity MCP entry ${name} was preserved; it is separate from the native agent-bridge sender integration.`);
+    }
+    if (remove) { if (outbound) delete mcp.mcpServers[OUTBOUND]; }
+    else {
+      mcp.mcpServers ??= {};
+      mcp.mcpServers[OUTBOUND] = { ...outbound, command: node, args: [outboundEntry] };
+    }
+    const mcpEdit = changed(originalMcp, mcp);
+    if (mcpEdit) edits.push(mcpEdit);
+    const originalSidecar = snapshot(path.join(configRoot, "sidecars", SIDECAR, "sidecar.json"));
+    if (originalSidecar.text !== null) ownEntry(originalSidecar.value, sidecarEntry, "Antigravity sidecar");
+    const originalConfig = snapshot(path.join(configRoot, "config.json"));
+    const config = structuredClone(originalConfig.value);
+    if (config.sidecars !== undefined) object(config.sidecars, "Antigravity sidecars");
+    if (config.sidecars?.[SIDECAR] !== undefined) object(config.sidecars[SIDECAR], "Antigravity bridge sidecar settings");
+    if (originalSidecar.text === null && config.sidecars?.[SIDECAR] !== undefined) throw new Error("An Antigravity sidecar with this name exists without a matching bridge definition");
+    let definition = null;
+    if (remove) { if (config.sidecars) delete config.sidecars[SIDECAR]; }
+    else {
+      definition = { ...originalSidecar.value, command: node, args: [sidecarEntry], restart_policy: originalSidecar.value.restart_policy ?? "on-failure", display_name: "Codex / Claude Antigravity Bridge" };
+      if (definition.builtin !== undefined) throw new Error("A builtin Antigravity sidecar cannot be replaced");
+      config.sidecars ??= {};
+      config.sidecars[SIDECAR] = { ...config.sidecars[SIDECAR], enabled: true };
+    }
+    const sidecarEdit = changed(originalSidecar, definition);
+    const configEdit = changed(originalConfig, config);
+    if (sidecarEdit) edits.push(sidecarEdit);
+    if (configEdit) edits.push(configEdit);
+  }
+  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry };
+}
+
+function assertCurrent(edit) {
+  const current = snapshot(edit.file);
+  if (current.text !== edit.text || current.dev !== edit.dev || current.ino !== edit.ino) throw new Error(`Configuration changed while preparing installation: ${edit.file}`);
+}
+
+export function applyJsonEdits(edits) {
+  for (const edit of edits) assertCurrent(edit);
+  const completed = [];
+  try {
+    for (const edit of edits) {
+      assertCurrent(edit);
+      if (edit.next === null) fs.unlinkSync(edit.file);
+      else {
+        fs.mkdirSync(path.dirname(edit.file), { recursive: true, mode: 0o700 });
+        const temporary = `${edit.file}.${process.pid}.bridge.tmp`;
+        try {
+          fs.writeFileSync(temporary, edit.next, { mode: edit.mode ?? 0o600, flag: "wx" });
+          assertCurrent(edit);
+          fs.renameSync(temporary, edit.file);
+        } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+      }
+      completed.push(edit);
+      if (snapshot(edit.file).text !== edit.next) throw new Error(`Configuration readback did not match the saved update: ${edit.file}`);
+    }
+  } catch (error) {
+    for (const edit of completed.reverse()) {
+      if (snapshot(edit.file).text !== edit.next) continue;
+      if (edit.text === null) fs.unlinkSync(edit.file);
+      else fs.writeFileSync(edit.file, edit.text, { mode: edit.mode ?? 0o600 });
+    }
+    throw error;
+  }
+}
+
+export function installerArguments(args) {
+  const allowed = new Set(["--codex", "--claude", "--desktop", "--all", "--remove", "--dry-run", "--help"]);
+  if (args.some((arg) => !allowed.has(arg))) throw new Error("Unknown option; use --help");
+  const selected = ["codex", "claude", "desktop"].filter((target) => args.includes(`--${target}`));
+  return { targets: args.includes("--all") || !selected.length ? ["codex", "claude", "desktop"] : selected, remove: args.includes("--remove"), dryRun: args.includes("--dry-run"), help: args.includes("--help") };
+}
+
+export function runAntigravityInstaller(args = process.argv.slice(2)) {
+  const options = installerArguments(args);
+  if (options.help) {
+    console.log("Usage: antigravity-mcp-bridge-install [--all|--codex|--claude|--desktop] [--remove] [--dry-run]");
+    return;
+  }
+  const home = os.homedir();
+  const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const node = stableNodeBin();
+  let run;
+  let codexExisting = null;
+  if (options.targets.includes("codex")) {
+    const codexBin = validateCodexExecutable(resolveCodexBin(process.env.CODEX_EXE));
+    run = (command) => execFileSync(codexBin, command, { encoding: "utf8", env: spawnEnv(), windowsHide: true, shell: false, timeout: 30000, stdio: "pipe" });
+    const inventory = JSON.parse(run(["mcp", "list", "--json"]));
+    if (!Array.isArray(inventory)) throw new Error("Codex returned an invalid MCP inventory");
+    if (inventory.some((item) => item.name === NAME)) codexExisting = JSON.parse(run(["mcp", "get", NAME, "--json"]));
+  }
+  const plan = planAntigravityInstallation({ ...options, home, root, node, codexExisting });
+  if (!options.remove) {
+    for (const entry of [plan.entry, ...(options.targets.includes("desktop") ? [plan.sidecarEntry, plan.outboundEntry] : [])]) {
+      if (!fs.existsSync(entry)) throw new Error(`Missing bridge entrypoint: ${entry}`);
+    }
+  }
+  if (options.dryRun) {
+    console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
+    return plan;
+  }
+  for (const edit of plan.edits) assertCurrent(edit);
+  if (plan.codex) {
+    if (options.remove) { if (plan.codex.remove) run(["mcp", "remove", NAME]); }
+    else applyStdioMcpRegistration({ name: NAME, registration: plan.codex, existing: codexExisting, run, configPath: path.join(process.env.CODEX_HOME ?? path.join(home, ".codex"), "config.toml") });
+  }
+  applyJsonEdits(plan.edits);
+  console.log(`${options.remove ? "Removed" : "Installed"} Antigravity bridge: ${plan.targets.join(", ")}.`);
+  for (const notice of plan.notices) console.log(notice);
+  if (!options.remove && options.targets.includes("desktop")) console.log("In Antigravity Customizations > Installed, find agent-bridge and choose More actions > Restart. If it is absent, reopen the App to load its new registration. In the CLI, use /mcp to reload server configurations.");
+  if (!options.remove) console.log("Reload the selected clients to load the bridge. Antigravity Desktop must launch its sidecar; installation alone does not prove a live connection. Native permissions were preserved.");
+  return plan;
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  exitForVersionRequest(import.meta.url);
+  try { runAntigravityInstaller(); }
+  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.23.0";
+const VERSION = "1.24.0";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/antigravity-bridge.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { resolveCodexSenderContext } from "./codex-sender-context.mjs";
+import { readClaudeSenderContext, requireClaudeSenderContext, stopProcessInspectors } from "./claude-sender-context.mjs";
+import { readClaudeAccountContext } from "./desktop-account-context.mjs";
+import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
+import { antigravityBridgeDirectory, callAntigravityDesktop } from "./antigravity-ipc.mjs";
+import { AntigravityDeliveries } from "./antigravity-deliveries.mjs";
+import { AntigravityCliSession } from "./antigravity-cli.mjs";
+import { exitForVersionRequest } from "./cli-version.mjs";
+import { NativeDesktopRelay, desktopTaskSocketPath, accountRelaySocketPath } from "./native-relay.mjs";
+import { requireBridgeAccounts, readBridgeAccounts, assertAccountIdentity } from "./bridge-account-context.mjs";
+
+exitForVersionRequest(import.meta.url);
+
+const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const rootPolicy = createHardenedRootPolicy();
+const directory = antigravityBridgeDirectory();
+const deliveries = new AntigravityDeliveries(path.join(directory, "cli-deliveries"));
+const sessions = new Map();
+let startingSessions = 0;
+const caller = process.env.ANTIGRAVITY_BRIDGE_CALLER;
+const senderRelay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() });
+const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const schema = { requestId: z.string().uuid(), cwd: z.string().min(1), prompt: z.string().min(1).max(65536) };
+
+async function sender(extra) {
+  if (caller === "codex") {
+    const context = await resolveCodexSenderContext(extra?._meta, { inspectDesktopTask: async (threadId) => {
+      const accounts = requireBridgeAccounts(readBridgeAccounts());
+      const { result } = await senderRelay.requestDesktop("read_thread", { threadId, hostId: "local", turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 1 }, { accountContext: accounts, beforeSend: () => assertAccountIdentity(accounts) });
+      assertAccountIdentity(accounts);
+      return { thread: result?.thread, latestTurnId: result?.turns?.[0]?.id ?? null };
+    } });
+    if (context.status !== "verified") throw new Error(context.reason ?? "Unverified Codex sender");
+    return { provider: "codex", id: context.threadId, cwd: context.cwd };
+  }
+  if (caller === "claude") {
+    const context = requireClaudeSenderContext(await readClaudeSenderContext({ account: readClaudeAccountContext() }));
+    return { provider: "claude", id: context.sessionId, cwd: context.cwd };
+  }
+  throw new Error("Install this bridge for Codex or Claude; unknown callers cannot read conversations or send work");
+}
+
+function sameCwd(expected, actual) {
+  if (!path.isAbsolute(expected) || !path.isAbsolute(actual)) throw new Error("Expected an absolute project directory");
+  const left = fs.realpathSync.native(expected);
+  const right = fs.realpathSync.native(actual);
+  if (path.relative(left, right)) throw new Error("Antigravity destination must match the verified sender's project directory");
+  rootPolicy.assert(left, "Antigravity project");
+  return left;
+}
+
+function owns(record, identity) {
+  if (!record || record.sender?.provider !== identity.provider || record.sender?.id !== identity.id) throw new Error("Delivery does not belong to this sending conversation");
+  sameCwd(identity.cwd, record.cwd);
+  return record;
+}
+
+function handoff(prompt, identity) {
+  return `[Agent handoff from ${identity.provider} conversation ${identity.id}. Native Antigravity permissions remain in effect.]\n\n${prompt}`;
+}
+
+const server = new McpServer({ name: "antigravity-bridge", version }, { instructions: "Send authorized work to Antigravity Desktop through its native sidecar or to an explicitly created CLI streaming session. Always select the requested surface; never substitute CLI for Desktop. The exact destination directory must match the verified sending conversation. Desktop delivery acceptance is not an agent reply. CLI sessions are bridge-owned headless sessions, not attached interactive terminals. Preserve requestId across retries and read_antigravity_delivery after pending or unknown outcomes; never resend automatically. Native tool approvals remain in force. Do not claim support for Antigravity-origin handoffs into Codex or Claude; this server receives from those hosts." });
+
+function register(name, description, inputSchema, readOnly, handler) {
+  server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async (args, extra) => {
+    try { return result(await handler(args, extra)); }
+    catch (error) { return { ...result({ error: error.message, deliveryState: error.deliveryState ?? "not_sent" }), isError: true }; }
+  });
+}
+
+register("antigravity_bridge_status", "Inspect connection capabilities without sending prompts.", {}, true, async () => {
+  let desktop;
+  try { desktop = await callAntigravityDesktop({ operation: "status" }, { timeoutMs: 5000 }); }
+  catch { desktop = { available: false, reason: "Open Antigravity with the installed codex-bridge sidecar enabled" }; }
+  return { version, caller: caller ?? "unconfigured", desktop, cli: { transport: "stream-json", activeSessions: sessions.size, permissionPolicy: "native-unchanged", interactiveTerminalAttachment: false } };
+});
+
+register("list_antigravity_conversations", "List native Desktop conversations and bridge-owned CLI sessions in the sending project.", { surface: z.enum(["desktop", "cli"]) }, true, async ({ surface }, extra) => {
+  const identity = await sender(extra);
+  const records = surface === "desktop" ? await callAntigravityDesktop({ operation: "list" }) : [...sessions.values()].map((entry) => ({ ...entry.session.read(), sender: entry.sender }));
+  return records.filter((record) => {
+    try { sameCwd(identity.cwd, record.cwd); return surface !== "cli" || record.sender.id === identity.id && record.sender.provider === identity.provider; }
+    catch { return false; }
+  });
+});
+
+register("send_to_antigravity_conversation", "Send one authorized prompt to an exact existing Desktop conversation or a bridge-owned CLI session. Retain requestId and poll the delivery receipt.", { ...schema, surface: z.enum(["desktop", "cli"]), conversationId: z.string().uuid() }, false, async (args, extra) => {
+  const identity = await sender(extra);
+  const cwd = sameCwd(identity.cwd, args.cwd);
+  const prompt = handoff(args.prompt, identity);
+  if (args.surface === "desktop" && (prompt.length > 30000 || prompt.includes("\0"))) throw new Error("Desktop handoff must fit within 30000 characters and contain no NUL");
+  if (args.surface === "desktop") return callAntigravityDesktop({ operation: "send", ...args, cwd, prompt, sender: identity });
+  const entry = sessions.get(args.conversationId);
+  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw new Error("CLI session is not owned by this sender and bridge process");
+  sameCwd(cwd, entry.session.read().cwd);
+  return deliveries.dispatch({ ...args, cwd, sender: identity, prompt }, async () => {
+    const current = await sender(extra);
+    sameCwd(cwd, current.cwd);
+    if (current.id !== identity.id) throw Object.assign(new Error("Sender changed before delivery"), { deliveryState: "not_sent" });
+    return entry.session.send(prompt);
+  });
+});
+
+register("start_antigravity_cli_session", "Create a new bridge-owned Antigravity CLI streaming session for explicitly authorized new work; sends the initial prompt and returns a durable delivery receipt.", schema, false, async (args, extra) => {
+  const identity = await sender(extra);
+  const cwd = sameCwd(identity.cwd, args.cwd);
+  if (sessions.size + startingSessions >= 4) throw new Error("At most four CLI sessions may be open in one bridge");
+  return deliveries.dispatch({ ...args, cwd, sender: identity, surface: "cli" }, async () => {
+    if (sessions.size + startingSessions >= 4) throw Object.assign(new Error("CLI session capacity reached"), { deliveryState: "not_sent" });
+    startingSessions++;
+    let reserved = true;
+    let session;
+    try {
+      const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !/^(?:CODEX_|CLAUDE|ANTHROPIC_|MCP_)/i.test(name)));
+      session = new AntigravityCliSession({ cwd, env });
+      const started = await session.start();
+      deliveries.identify(args.requestId, started.conversationId);
+      sessions.set(started.conversationId, { session, sender: identity });
+      startingSessions--;
+      reserved = false;
+      const current = await sender(extra);
+      sameCwd(cwd, current.cwd);
+      if (current.id !== identity.id) throw Object.assign(new Error("Sender changed before delivery"), { deliveryState: "not_sent" });
+      return await session.send(handoff(args.prompt, identity));
+    } catch (error) {
+      if (error.deliveryState !== "unknown") {
+        for (const [id, entry] of sessions) if (entry.session === session) sessions.delete(id);
+        await session?.close();
+      }
+      throw error;
+    } finally {
+      if (reserved) startingSessions--;
+    }
+  });
+});
+
+register("read_antigravity_delivery", "Read the original receipt without resending. Desktop accepted means the native API accepted it, not that the agent completed a turn.", { surface: z.enum(["desktop", "cli"]), requestId: z.string().uuid() }, true, async (args, extra) => {
+  const identity = await sender(extra);
+  const record = args.surface === "desktop" ? await callAntigravityDesktop({ operation: "receipt", requestId: args.requestId }) : deliveries.read(args.requestId);
+  return owns(record, identity);
+});
+
+register("close_antigravity_cli_session", "Close an idle bridge-owned CLI session belonging to the caller.", { conversationId: z.string().uuid() }, false, async ({ conversationId }, extra) => {
+  const identity = await sender(extra);
+  const entry = sessions.get(conversationId);
+  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw new Error("CLI session is not owned by this sender");
+  sameCwd(identity.cwd, entry.session.read().cwd);
+  if (["running", "starting"].includes(entry.session.read().status)) throw new Error("Wait for the active CLI delivery before closing");
+  const closed = await entry.session.close();
+  if (closed.status !== "closing") sessions.delete(conversationId);
+  return { closed: closed.status !== "closing", conversationId, status: closed.status };
+});
+
+let stopping = false;
+async function stop() {
+  if (stopping) return;
+  stopping = true;
+  await Promise.allSettled([...sessions.values()].map(({ session }) => session.close()));
+  await stopProcessInspectors();
+  await server.close();
+}
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void stop(); });
+process.stdin.once("end", () => { void stop(); });
+await server.connect(new StdioServerTransport());