Agent Bridge

Codex 监督 Claude Code 和 DeepSeek Harness。Bridge 自己不调用 LLM。

Let Codex be the only supervisor. Claude Code or DeepSeek Harness does the implementation. You review, verify, and apply in Codex.

What it is

Codex 负责计划、审核、approve / apply。外部 Coding Agent 只在独立 worktree 里改代码。Bridge 不调用任何 LLM，也不替你选 model / provider / effort。

Codex  ──bridge_run──►  Claude Code / DeepSeek Harness
  ▲                         │
  │      ReviewPacket       │  在独立 worktree 里改代码
  │      verification       │  不得 commit / push / merge
  └──── bridge_apply ◄──────┘

Related MCP server: cc-agent

Features

• MCP 工具：bridge_run → respond → review → approve → apply

• Worker 在独立 git worktree 干活，不得 commit / push / merge

• 独立 verification，不信 Worker 自称测过

• ReviewDigest、checkpoint、CAS、guarded cherry-pick

• doctor 自检：缺什么、为什么、怎么修

Quick Start

别人看到 README 后按这五步走，不用翻文档。

1. Install

需要 Node.js 22+ 和 Git。

npx -y codex-agent-bridge

这条命令会：把运行时装到 ~/.agent-bridge，写入 Codex Skill 和 MCP（用本机 node.exe，不用 npx.cmd），并跑一次 doctor。

更新再跑同一条。卸载：

npx -y codex-agent-bridge uninstall
npx -y codex-agent-bridge uninstall --purge

2. Configure Claude or DeepSeek

Bridge 不安装 Worker，也不改它们的 model / provider / reasoning effort。你至少要有一个已经能独立登录、独立干活的 Worker：

Agent Bridge不管理DeepSeek model/provider/reasoning effort。DeepSeek effective route由运行中的Harness ACP composition决定。当前legacy integration使用上游composition配置。Claude Code 沿用其原生配置。

3. Run doctor

npx -y codex-agent-bridge doctor
npx -y codex-agent-bridge doctor --project /path/to/your/git-repo

成功时会看到：

✓ Agent Bridge installed
✓ Git available
✓ Claude ACP available
✓ DeepSeek ACP legacy available
✓ Workspace ready

某一项是 ✗ 时，doctor 会写：缺少什么、为什么、怎么解决。不要忽略 Fix: 行。

4. Connect the MCP client

安装后新开一轮 Codex。旧会话看不到新的 bridge_* 工具。

MCP 已由安装器写入 ~/.codex/config.toml。不要手写 npx.cmd。

5. First task

目标必须是独立 git 仓库。每次 bridge_* 都带同一个 project。任务 UUID 字段名是 task。

bridge_run          worker=claude 或 deepseek
→ WAITING_FOR_INPUT 时 bridge_respond
→ AWAITING_REVIEW + ReviewPacket
→ bridge_approve     任务分支 checkpoint，不是完成发布
→ bridge_apply       cherry-pick 到当前分支，不是 merge

Turn 结束 ≠ 任务完成。Diff 只认 baseCommit vs worktree。bridge_run 只选 worker，不要传 model / provider / effort。

项目里如果有 .agent-bridge/verify.json，默认会跑其中全部 verifyId。示例：templates/verify.json。

Architecture

Codex (Supervisor)
  │ MCP stdio
  ▼
Agent Bridge
  ├── TaskManager / worktree / verification / review
  ├── checkpoint + CAS + guarded apply
  └── WorkerProfile → AcpRuntimeDriver
        ├── Claude official ACP
        └── DeepSeek legacy source ACP

更细的说明：

Limitations

• DeepSeek 当前是 legacy source ACP，不是官方 Product runtime。官方 ACP runtime 迁移等上游补入口，见 ADR-004。

• 同一项目同一时刻只能有一个 Writer。第二写者返回 CORE_LOCK_HELD。

• 损坏的 tasks.json 会 TASK_STORE_CORRUPTED，不会当成空库。

• 没有 GUI、HTTP daemon、SQLite。审核面在 Codex。

• V1 不管理 Worker 的 model / provider / effort。

从源码开发

npm install
npx tsx src/cli.ts setup --dev
npm test

--dev 让 MCP 指向当前仓库，而不是 ~/.agent-bridge。

License

Apache-2.0. See LICENSE.

Roadmap: ROADMAP.md. Changes: CHANGELOG.md.

发布新版本

本地 npm publish 每次都会要 2FA。正确做法是：改版本 → 打 tag → push，GitHub Actions 用 Trusted Publishing 发 npm。

仓库目录可能仍叫 Agent Relay。产品名是 Agent Bridge。npm 包名是 codex-agent-bridge。