AI Bridge

一个给 Claude 和 Codex 共用的最小协作公告板：看对方的进度、互相留言、认领文件，避免同时修改同一个文件。人也可以从命令行留言。Stop 钩子会在 AI 一轮结束时把新消息带进它的会话。

Windows 优先，只有一个 Rust 程序 bridge-mcp.exe，不需要桌面界面、Node.js 或 Python 运行环境。完整旧版保存在标签 v0-full。

怎么用

在同一个项目里，分别打开 Claude 和 Codex 的干活会话，告诉它们各自负责什么。它们通过 MCP 工具查看进度、认领文件和留言；Stop 钩子在一轮结束时检查新消息，让收件方在自己的会话里继续处理。Bridge 负责传递协作消息，具体工作仍由两个 AI 完成。

已经空闲的 Codex 不会被新消息自动叫醒。 这时需要你去它的窗口说一句话，让它继续一轮；如果它发完消息后还要等对方回复，可以让它用 wait 原地等待，按下文的完整路径、超时和已读流程执行。

对 AI 说“开始监视”或“停止监视”即可开关监视，规则见 RULES.md 第 7 条。

Related MCP server: Pursers

安装与开启项目

从源码安装需要 Git、Rust stable 和 MSVC C++ 构建工具。在仓库目录运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-local.ps1

安装脚本编译并复制到 %USERPROFILE%\.bridge\bin\bridge-mcp.exe，不修改 Claude 或 Codex 的配置。更新前先完全退出两端；如果仍提示占用，检查是否还有后台进程。

$bridge = Join-Path $env:USERPROFILE '.bridge\bin\bridge-mcp.exe'
& $bridge on D:\code\example
& $bridge status
& $bridge show D:\code\example

全局总开关默认开启，每个项目默认关闭；开关由用户操作。Git 子目录和 worktree 归到同一个仓库。消息保存在 %USERPROFILE%\.bridge\bridge.db；更新兼容已有数据库并保留旧表、旧消息。

配置 MCP

已经接入的用户保留原 MCP 配置即可。新用户先在 PowerShell 执行下面的命令，它只打印两段可复制配置，不写文件。使用实际展开的安装路径，是因为 MCP 的 command 字段不会自动展开 %USERPROFILE%。

Git Bash 里的 ~ 可能不是 Windows 的 %USERPROFILE%。本文的用户配置和安装路径统一以 PowerShell 的 $env:USERPROFILE 为准，不要用 Git Bash 的 ~ 推算。

$bridge = Join-Path $env:USERPROFILE '.bridge\bin\bridge-mcp.exe'
@{ mcpServers = @{ bridge = @{ type = 'stdio'; command = $bridge; args = @(); env = @{ BRIDGE_AGENT = 'claude' } } } } | ConvertTo-Json -Depth 6
@"
[mcp_servers.bridge]
command = '$bridge'
args = []

[mcp_servers.bridge.env]
BRIDGE_AGENT = "codex"
"@

• 把第一段 JSON 的 mcpServers.bridge 合入 %USERPROFILE%\.claude.json。

• 把第二段 TOML 合入 %USERPROFILE%\.codex\config.toml。

• 保留文件里已有的其他配置。两端身份分别是 claude、codex，两端使用同一个数据库。

• MCP 连接时会直接提供 RULES.md 中的完整协作规则，无须另行复制到全局 CLAUDE.md 或 AGENTS.md。更新 exe 后重启两端以加载新规则，在干活的窗口调用 bridge_overview 验证。

MCP 一共 7 个工具：bridge_overview、send_message、read_messages、update_status、claim_files、release_files、list_projects。所有工具的 project 都填项目根目录的绝对路径。

配置 Stop 钩子

钩子在 AI 每轮结束时检查未读消息，有消息就让它继续一轮；这一轮已经由 Stop 钩子续过时，不再次续跑。它不会唤醒早已停下的会话，也不会替用户授予新任务权限。

下面的命令在运行时展开 %USERPROFILE%\.bridge\bin\bridge-mcp.exe。使用 PowerShell 包装是为了兼容 Windows 路径中的中文、空格以及 UTF-8 输出。把配置合入已有文件，保留其他钩子；不要用整个示例覆盖已有设置。

Claude Code：%USERPROFILE%\.claude\settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "powershell.exe -NoProfile -Command \"[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); & ([Environment]::GetEnvironmentVariable('USERPROFILE') + '/.bridge/bin/bridge-mcp.exe') hook --agent claude\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Codex：%USERPROFILE%\.codex\hooks.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -Command \"[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); & ([Environment]::GetEnvironmentVariable('USERPROFILE') + '/.bridge/bin/bridge-mcp.exe') hook --agent codex\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

在 Codex 里用 /hooks 检查并确认信任。修改钩子配置后，按客户端提示重新加载、重新信任；如果当前客户端没有这些入口，需使用支持 Stop 钩子的版本。配置格式见 Claude Code 官方钩子文档 和 Codex 官方钩子文档。

钩子出错时只向 stderr 记录错误，退出码仍是 0，不阻止 AI 正常结束。一次最多投递最近 10 条并标为已读，剩余消息用 read_messages 查看。

收件窗口和重新指定

同一个项目的每个 AI 各有一个收件窗口。第一次真正投递消息时绑定当前窗口；它保持活跃时，其他提问窗口的钩子不会抢走消息。收件窗口超过两小时没有触发钩子后，下一次有消息可送的窗口可以接替。

首次绑定之前或两小时失效以后，提问窗口也可能成为收件窗口。 想明确指定干活窗口，或者认错窗口时，先运行：

& $bridge rebind D:\code\example --agent claude
& $bridge rebind D:\code\example --agent codex

然后在各自想接收消息的窗口里说一句话。这一轮结束时，即使没有消息，也会完成绑定。每条命令只影响所指定的 AI；重新指定后，避免先在其他窗口触发 Stop 钩子。

只回答问题的窗口应遵循 RULES，不主动调用 Bridge 的读消息工具；收件绑定约束的是钩子投递，主动调用读消息工具仍会标记已读。

在其他项目里使用

要使用包含 Stop 自动收信的完整流程，项目必须是 Git 仓库。Bridge 程序、上面的 MCP 配置和钩子配置都是全局的，配好一次后无须为每个项目重复安装或复制配置。对已有 Git 仓库，只需由用户开启新项目的开关，再在两端打开该项目的干活会话：

$bridge = Join-Path $env:USERPROFILE '.bridge\bin\bridge-mcp.exe'
& $bridge on "D:\code\another-project"

每个项目的每个 AI 使用一个干活窗口。另开的提问窗口不调用 Bridge；在干活窗口已绑定且保持活跃时，提问窗口的 Stop 钩子不会抢走消息。首次绑定、两小时失效和认错窗口的情况见上文；需要指定窗口时运行 rebind，再到目标窗口说一句话。

暂时不想在这个项目使用 Bridge，可运行 & $bridge off "D:\code\another-project"，其他项目的开关不受影响。

同一仓库的 Git worktree 共用公告板、消息已读状态和每个 AI 的收件窗口。 worktree 可以分开代码目录，但不能隔离多对 AI 的协作消息；当前暂不支持在同一个仓库的多个 worktree 中运行多对互相独立的 Claude/Codex。

和审查规则配合

如果项目已有通过 REVIEW/REPLY 文件交接的规则，可以保留文件和原有分工。把“写完文件后由用户触发下一轮”改为：写完文件后，通过 Bridge 的 send_message 通知对方，说明文件路径和需要它做什么。审查意见、技术细节和逐条回复仍写在文件里，Bridge 消息只做通知。

对方已经空闲时，仍需按“怎么用”一节由用户唤起，或让对方事先用 wait 等待。通知只用于已授权工作的交接，不能代替用户授权。

命令行

下面用 bridge-mcp 简写已安装程序。PowerShell 中用前面定义的 & $bridge 代替；省略项目时使用当前目录。

需要 AI 原地等回复时，使用完整安装路径。例如 PowerShell：

& "$env:USERPROFILE\.bridge\bin\bridge-mcp.exe" wait "D:\code\example" --agent codex --timeout 300

Git Bash 使用 "$USERPROFILE/.bridge/bin/bridge-mcp.exe" wait "D:/code/example" --agent claude --timeout 300。把命令工具的执行超时设为大于 300 秒，例如 360 秒（360000 毫秒）；也可通过后台进程或会话句柄分段等待。有新消息返回后，先调用 MCP 的 read_messages 读取并标记已读，再处理消息，避免 Stop 钩子再次投递。等待超时最多重试至三轮，开关关闭或命令报错时停止等待。

常见问题

Claude 为什么把消息标成 Stop hook blocking error？

Bridge 用 {"decision":"block","reason":"…"} 让 Claude 先处理新消息再结束，正常投递时退出码是 0。Claude 会把这种阻止结束的反馈显示为上述标签；单凭这个标签不代表程序出错。这里的 block 表示继续当前工作，详见 Claude Stop 钩子的决策说明。

消息没有自动送达，先检查什么？

1. 未开启： 用 & $bridge status 检查项目开关和全局总开关。两者都开启，才会正常投递；开关由用户操作。

2. 收件窗口不是当前窗口： 消息可能仍绑定到另一个干活窗口。按“收件窗口和重新指定”一节执行 rebind，再在想接收消息的窗口结束一轮。

3. 会话空闲： Stop 钩子只在一轮结束时触发，不会持续后台轮询。去收件窗口说一句话，或在后续协作时让 AI 用 wait 原地等回复。

开发和验证

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release -p bridge-mcp
python -X dev -W error -m unittest discover -s tests/conformance -t . -v
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-install-local.ps1
pwsh -NoProfile -File .\scripts\test-install-local.ps1

契约测试只使用 Python 标准库（3.10+），通过真实子进程验证 MCP 和命令行。测试用 BRIDGE_DB 指向临时数据库，不读写用户数据。CI 只测 Windows。