Codex Agy Bridge

codex-agy-bridge

通过 MCP，在 Agent 运行环境中运行 Antigravity，将 agy 会话作为持久化、并行且可由人工操作的会话。

codex-agy-bridge 使用可恢复的 MCP 控制平面封装官方 Antigravity CLI。Codex、Claude Desktop 等 Agent 运行环境，或你自己的 GPT/Claude 驱动的 MCP 客户端，都可以启动 agy 运行、等待稀疏事件、连接真实终端、发送受保护的输入、安全取消、继续精确的对话，并在之后通过 run_id 收集最终结果。

快速安装

前提条件：

• 用于执行以下命令的 Codex CLI，或其他支持本地 stdio MCP 的运行环境
• 已在本地完成身份验证的官方 Antigravity CLI（agy）
• uv / uvx
• tmux 和受支持的终端启动器：

# macOS
brew install tmux

# Debian/Ubuntu Linux (x-terminal-emulator is also supported)
sudo apt install tmux gnome-terminal

检查所需命令：

codex --version
agy --version
agy models
uvx --version
tmux -V

初次身份验证

agy --version 只能证明二进制文件存在。在添加 MCP 服务之前，先运行 agy models；如果 Antigravity 要求你登录，或报告你尚未登录，请启动一个可见会话并完成浏览器/登录流程：

agy --prompt-interactive "Authenticate Antigravity and then exit."
agy models

agy models 成功后，安装或重启 MCP 服务。如果桥接运行仍遇到身份验证问题，agy_run_start 会返回 status="auth_required"，并默认打开一个可见的 agy 身份验证会话。在该会话中完成登录，然后启动新的运行。你也可以使用 agy_run_observe(view="terminal") 或 agy_admin(action="doctor") 检查身份验证所需状态。

使用 Codex CLI 从 PyPI 安装：

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

重启运行环境；如果使用了上述命令，请在 Codex 中验证：

codex mcp get codex-agy-bridge
codex mcp list

使用以下命令移除：

codex mcp remove codex-agy-bridge

对于 Claude Desktop 或自定义 MCP 客户端，使用相同格式的 stdio 命令：uvx codex-agy-bridge@latest，并将 AGY_CMD 设置为已完成身份验证的 agy 可执行文件。

与众不同之处

• 并行 Antigravity 会话： 启动多个相互独立的 agy 运行，每个运行都有自己的持久化状态、日志、对话记录视图和结果。
• 可由人工操作的终端： 前台运行在持久化的 tmux 会话中，因此 Terminal.app 可以连接，而不会终止 Agent。
• 可恢复的 MCP 控制： MCP 调用可以超时，运行环境可以重启，而运行仍可在之后通过 run_id 观察。
• 目标编排： 创建目标，以有限的并行度启动命名目标，并将整个批次作为一个协调任务进行检查。
• 稀疏唤醒事件： agy_run_wait 通过短轮询检查生命周期、注意事项、进度和终端事件，避免频繁轮询对话记录造成的信息泛滥。
• 受保护的输入： 如果调用方观察到运行后事件游标或对话记录游标发生变化，agy_run_input 可以拒绝过时的写入。
• 了解执行轨迹的可观测性： 提供有界的对话记录摘要和终端证据，不暴露模型的私有推理。
• 运维卫生： 对重复的活动运行进行去重，安全取消进程组，并保留已完成的结果文件。

安装详情

如果你是正在阅读本文的 Agent

帮助用户安装；不要在用户不知情的情况下更改其机器。

1. 先验证前提条件：

command -v codex
command -v agy
command -v uvx
command -v tmux
agy --version
agy models

2. 如果缺少任何内容，先征求用户同意，再进行安装。
3. 如果 agy models 报告身份验证错误，请先帮助用户完成上文所述的初次身份验证流程，再添加 MCP 服务。
4. 然后运行：

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

5. 验证：

codex mcp get codex-agy-bridge
codex mcp list

6. 告知用户重启 Agent 运行环境，以加载新的 MCP 工具。

PyPI

Quick Install 命令会保存一个 stdio MCP 服务定义。Agent 执行环境启动服务时，uvx 会从 PyPI 解析 codex-agy-bridge@latest，将其安装到隔离的缓存环境中，并运行 codex-agy-bridge 控制台脚本。AGY_CMD 会将桥接程序固定到用户已安装并完成身份验证的 agy 可执行文件。

请勿在命令中手动替换 $ 或 $(...)。在 POSIX shell 中，$(command -v agy) 和 $(command -v uvx) 会展开为可执行文件的绝对路径。

GitHub

如果你想直接使用仓库版本，请使用此方式：

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uvx --from git+https://github.com/varadfromeast/codex-agy-bridge \
  codex-agy-bridge

本地开发

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uv --directory "$PWD" run codex-agy-bridge

工作原理

flowchart LR
  H["Agent harness<br/>(Codex, Claude, custom MCP client)"]
  M["codex-agy-bridge<br/>MCP stdio server"]
  S["Durable control plane<br/>runs, goals, events, results"]
  W["Detached run supervisor"]
  A["Antigravity CLI<br/>agy"]
  T["Persistent tmux session<br/>human attach/input"]
  L["Local Antigravity<br/>trajectory files"]

  H <-->|"MCP tools"| M
  M <--> S
  S --> W
  W --> A
  W <--> T
  A --> L
  W -->|"bounded transcript projection"| S
  T -->|"terminal logs and attention prompts"| S

桥接程序会保持 MCP 服务的响应能力，同时由分离的监督进程管理长时间运行的 agy 进程。状态和事件会持久化到本地，因此原始 MCP 调用返回后，运行仍可继续。有关更深入的进程模型，请参阅 docs/ARCHITECTURE.md。有关 MCP 控制循环的愿景，请参阅 docs/MCP_VISION.md。

MCP 工具

工具	用途
agy_run_start	启动、继续或打开交互式前台运行
agy_run_wait	短轮询，直到选定的运行发出稀疏唤醒事件
agy_run_observe	查看完整视图、状态视图、对话记录或原始终端视图
agy_run_input	在可选的事件／对话记录前置条件下发送输入
agy_run_cancel	取消一个正在运行的任务
agy_run_result	读取最终结果元数据或有界结果分块
agy_goal	创建目标、启动目标任务并读取汇总状态
agy_admin	查看诊断信息、模型、插件、验证结果和更新日志

省略 model（或传入 null），即可让 Agy 选择其默认值：桥接程序会存储 model: null，且不会发送 --model。这适用于运行、审查工具和目标；目标任务会继承其目标的选择。显式指定的模型会根据 agy models 进行验证，包括桥接程序之前的默认值 Gemini 3.5 Flash (Medium)；未知或空的选择会被拒绝。桥接程序绝不会替换为目录中的第一个条目。agy_admin(action="models") 会报告 default_model: null 和 default_model_source: "agy_cli"；这表示将选择委托出去，并非观察到的实际生效模型。

现有的持久化运行和目标会保留其模型字符串，仍可读取。它们不会被静默迁移到其他模型。对于旧目标，新启动的任务会重新验证其模型选择；如果该模型已不可用，则会拒绝启动。请使用可用模型创建新目标，或省略模型选择以将其委托给 Agy。此前已预留的运行会保留原有的命令策略。新的委托请求使用与显式选择模型不同的去重键。要求目标模型为字符串的旧版桥接程序无法读取模型为 null 的新目标；使用这些目标期间请勿降级。

典型流程：

agy_run_start -> agy_run_wait -> agy_run_observe -> agy_run_result

在 Codex MCP 中，工具可能会使用服务前缀暴露，例如 codex_agy_bridge_agy_run_wait。运行响应会包含精确的 wait_call 参数；请注意，即使只有一个运行，agy_run_wait 也始终需要 run_ids: ["..."]。支持的等待条件包括 any_attention、any_terminal、all_terminal、any_event，以及别名 attention、terminal、finished、finish、complete、completed、result、all_finished、all_complete 和 all_completed。

如果执行环境需要将工作拆分为具有共同目标和有界并行度的命名目标，请使用 agy_goal。

配置

变量	默认值	用途
AGY_CMD	agy on PATH	Antigravity 可执行文件的确切路径
AGY_BRIDGE_STATE_DIR	~/.local/state/codex-agy-bridge	持久化运行和目标状态
AGY_BRIDGE_AGY_ROOT	~/.gemini/antigravity-cli	Antigravity 对话和轨迹
AGY_BRIDGE_MAX_PARALLEL	50	全局并发运行上限
AGY_BRIDGE_COMPLETION_STABILITY_SECONDS	150	最终标记必须保持稳定的时间
AGY_BRIDGE_MCP_WAIT_SLICE_SECONDS	120	单次 agy_run_wait MCP 调用阻塞并返回快照前的最长秒数，避免网关超时

MCP 服务重启后，运行状态仍会保存在 ~/.local/state/codex-agy-bridge/。

状态与风险

本项目处于实验阶段。目前面向 Python 3.11+、macOS 或 Linux（需使用受支持的终端启动器）、tmux，以及兼容 Antigravity CLI 1.0.8 的命令和轨迹文件。

Antigravity 是一个 Agentic 命令行工具。它可以读取和写入文件、执行命令，并以当前用户的权限访问网络。此桥接工具不是沙箱，也不是安全边界。

该桥接工具始终启用 Antigravity 的危险权限跳过策略，以免无人值守运行因 CLI 审批提示而停滞。任何 dangerously_skip_permissions=false 输入都会被拒绝；唯一允许的值是 true。sandbox=true 和 additional_directories 是 CLI 策略提示，并不构成文件系统隔离。

该桥接工具不会读取或复制 Antigravity OAuth 凭据。它会调用已安装的 agy 二进制文件，并读取普通的本地对话元数据和轨迹文件。

开发

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev
uv run pytest
uv run ruff check .
uv build

直接运行服务：

uv run codex-agy-bridge

该服务使用 stdio 传输。请勿将诊断文本打印到 stdout，否则会破坏 MCP 帧格式。

发布

推送版本标签后会运行 .github/workflows/publish.yml，该工作流会验证版本、运行检查、构建分发包、通过 GitHub OIDC 发布到 PyPI、创建 GitHub Release，并将 server.json 发布到 MCP Registry。

兼容性

当前读取器需要以下位置的 Antigravity 轨迹 JSONL：

~/.gemini/antigravity-cli/brain/<conversation-id>/
  .system_generated/logs/transcript.jsonl

如果 Antigravity 改用 SQLite 或本地守护进程 API，可以用新的适配器替换此读取器，而无需更改 MCP 工具契约。

许可证

MIT