Codex Claude Bridge

让已有的 Codex 与 Claude Code 会话直接协作，让长任务在上下文压缩后接着做。

Codex Claude Bridge（管理页与命令名称：Cooperation）连接 Codex 桌面 App 和 VS Code 中的 Claude Code。你继续使用熟悉的原生对话界面，为不同会话分配工作；agent 通过 MCP 或 CLI 互相发送任务、评审意见和结果，本地工作台集中展示多个项目的会话、消息和上下文用量。

它把 原生会话通信、跨项目管理、上下文交接与恢复 放进同一条工作流：从“请另一个 agent 看看这个方案”，到“上下文快满了，保存进度、压缩、恢复并接着协作”。

快速部署 · 发送第一条消息 · 配置-mcp · 自动上下文维护 · 常见问题

核心特色

项目的核心差异，是把“原生界面里的 agent 协作”和“长任务的上下文续接”一起做好。 用户决定参与者与分工，agent 负责交换工作成果，Cooperation 负责传递消息、展示状态和执行获准的维护流程。

例如：让 Codex 实现一个功能，让 Claude 审查方案与变更；发现问题后直接发回原 Codex 会话。两端各自保留自己的任务上下文，协作可以跨越一次上下文压缩继续进行。

flowchart LR
    C[Codex 桌面原生会话] <-->|MCP / CLI| B[Cooperation 本地服务]
    B <-->|消息与原生控制| A[Claude Code 原生会话]
    U[用户管理页] -->|选择目录、查看通信、配置阈值| B
    B --- D[持久消息、维护流程与队列]

Related MCP server: mindmap-mcp-server

快速部署

1. 准备环境并获取项目

当前部署与原生验收以 Windows x64 为基线。

git clone https://github.com/Heisenbear-Rebirth/codex-claude-bridge.git Cooperation
cd Cooperation
node --version
.\scripts\build-claude-wrapper.ps1

无需运行 npm install 或构建前端。最后一步生成 bin/claude-wrapper.exe 和 bin/claude-wrapper.paths，其中包含本机路径；移动项目或换机器后重新构建。

下文统一以 E:/Projects/Cooperation 为安装目录，请替换为你自己的完整路径。工具安装目录用于存放服务和数据；工作项目目录是 Codex、Claude 实际处理代码或文档的目录，两者可以不同。

2. 从 Codex 原生会话启动服务

首次打通双向通信时，建议让 Codex 在它自己的工具环境中启动管理服务。 当前发往 Codex 的普通消息需要服务继承 Codex App 的本机发送桥连接。

在 Codex 桌面 App 中打开本仓库，把下面这段发给它：

请在当前 Codex 原生会话的工具环境中执行下面的命令，启动 Cooperation 后台服务，并告诉我管理页地址：

node "E:/Projects/Cooperation/bin/coop-service.mjs" start

启动成功会输出 Started: http://127.0.0.1:端口，并尝试打开管理页。端口自动选择，以实际输出为准。同一安装目录重复启动会复用已有服务。

如果此前已从资源管理器双击启动了服务，先用 关闭项目.cmd 关闭该实例，再让 Codex 按上述方式启动。重复点击启动只会复用旧实例，不会补上旧进程缺少的桥连接。

日常入口：

从普通终端或资源管理器启动可以查看管理页，但不保证具备发往 Codex 的普通消息连接。连接异常见常见问题。

3. 接入 Claude Code

在 VS Code 的用户设置 JSON 中，合并下面这一项，指向刚构建的文件：

"claudeCode.claudeProcessWrapper": "E:\\Projects\\Cooperation\\bin\\claude-wrapper.exe"

这是一项 VS Code 用户级配置，由你明确选择是否启用；构建和启动服务不会自动写入它。保留其他设置；已有其他 wrapper 时，先核对如何整合。该程序会启动扩展原本选定的 Claude，并转发其输入、输出和权限交互。

随后在管理页：

1. 添加 Claude 实际工作的项目目录。

2. 在该目录下勾选 “Claude 控制”。

3. 关闭并重新打开对应的 Claude Code 面板，让它通过 wrapper 启动。

4. 确认原面板的模型、思考强度与权限选项符合你的预期，并检查管理页是否显示连接状态。

“Claude 控制”精确匹配工作目录。勾选“包含子目录”只扩大展示范围；需要接入的子目录应单独添加并允许。这个开关与“启用自动压缩”相互独立。

详细接入、协议说明与回滚步骤见 Claude 原生控制接入。

4. 找到要协作的会话

在管理页添加一个或多个工作项目目录，按需选择 “包含子目录”。展开目录及其下的 Codex / Claude，找到已有会话并点击 “复制地址”。

地址形如：

codex://实现功能的会话:原生会话ID
claude://审查方案的会话:原生会话ID

也可以使用短地址 codex:会话ID 或 claude:会话ID。接收方由你指定；发送者由工具自动识别。

会话被发现只代表它存在。先打开准备使用的原生会话；Codex 自动维护需要任务已在 App 中加载，Claude 接收和控制需要相应连接在线。

发送第一条消息

通过 CLI：无需先配置 MCP

把下面的提示发给 Codex 发送方会话，替换目标地址与正文：

请通过 Cooperation CLI 向以下目标会话实际发送消息，并告诉我投递结果：

node "E:/Projects/Cooperation/bin/coop.mjs" send --client codex --to "这里粘贴目标会话地址" --text "请审查我的实现方案，并通过 Cooperation 把意见发回本会话。"

如果发送方是 Claude Code，把 --client codex 改为 --client claude。该参数表示谁在发送；--to 表示发给谁。

CLI 应由原会话的命令工具执行，以便取得该会话的身份。从独立 PowerShell 手工执行可能无法确认发送者。

长消息、代码片段或复杂引号内容适合先写入发送方获准目录内的 UTF-8 文本文件，再发送：

node "E:/Projects/Cooperation/bin/coop.mjs" send --client claude --to "codex:目标会话ID" --file "E:/Work/MyProject/review.txt"

正文前会自动带上发送方地址。接收方可以用这个地址回信；是否回复、何时回复由任务要求和 agent 决定。

怎样确认第一次协作成功

1. 在目标原生会话中看到消息及发送方信息。

2. 在管理页展开相关会话，右侧找到同一条通信记录。

3. 让接收方回一条消息，并在原发送方会话中确认收到。

submitted 表示客户端已接受投递，对方实际回复才表明它已处理消息。如返回 unknown，先在原会话核对，避免重复发送。

给 agent 的协作约定

下面这段适合放在任务开头，或由你决定加入工作项目的指令文件：

本任务允许通过 Cooperation 与以下会话协作：
对方地址：<粘贴地址>
对方分工：<例如：审查方案、复核测试结果>

需要对方协助时，优先使用已加载的 Cooperation send_message 工具；未加载 MCP 时使用本机 Cooperation CLI。
发送时说明目标、必要背景、需要对方完成的事项和相关文件位置。
取得反馈后结合当前任务处理；需要回复时使用消息中附带的发送方地址。
发送后检查投递结果；结果不确定时先核对原会话。

Cooperation 负责通信和上下文维护。任务分工、文件修改范围与结果验收由你和参与会话约定。

配置 MCP

CLI 和 MCP 都连接同一个管理服务。配置 MCP 是让 agent 能直接调用工具；它不会替你启动管理服务或完成 Claude 接入。

把配置放在需要调用工具的工作项目中，并把其中的安装路径替换为自己的路径。已有配置文件时合并相应条目。

Codex

在工作项目的 .codex/config.toml 中加入以下配置；Codex 需要信任该项目才能加载项目级配置。配置位置和格式参见 OpenAI MCP 文档。

[mcp_servers.cooperation]
command = "node"
args = ["E:/Projects/Cooperation/bin/coop.mjs", "mcp", "--client", "codex"]
tool_timeout_sec = 75

Claude Code

在工作项目根目录的 .mcp.json 中合并以下配置。Claude Code 对项目级 MCP 的加载确认与连接检查见 Claude Code MCP 文档。

{
  "mcpServers": {
    "cooperation": {
      "command": "node",
      "args": ["E:/Projects/Cooperation/bin/coop.mjs", "mcp", "--client", "claude"]
    }
  }
}

重新加载对应客户端的 MCP 配置，完成客户端要求的信任或权限确认，并检查 cooperation 是否已连接。配置样例也保存在 Codex 与 Claude 文件中。

让会话调用 MCP

请实际调用 Cooperation MCP 的 send_message 工具：
to：<粘贴目标会话地址>
message：请审查刚才的方案，完成后通过 Cooperation 回复本会话。

调用后告诉我投递结果。

本项目只提供两个业务工具：

会话发现和通信历史由用户在管理页查看，agent 根据用户提供的地址工作。维护回执所需参数由系统下发，日常发消息只需使用 send_message。

管理页怎么用

• 左侧目录树：添加项目、展开客户端、搜索会话、复制地址。文件夹名称、客户端名称和会话卡片按层级展示。

• 会话卡片：持续显示上下文占用、模型、活动状态与统计时间。关闭自动压缩后仍更新统计；离线记录标记为快照，未知容量显示为未知。

• 右侧通信列表：显示发送方或接收方属于当前展开会话的消息。折叠目录或客户端会收窄范围，重叠目录不会重复计入同一条消息。

• 右侧详情：选择消息后查看完整正文、发送方、接收方和投递结果；可按关键词或状态筛选记录。

• 自动保存：阈值可输入或拖动；失焦、按 Enter 或松开滑块后保存，以卡片中的保存状态为准。

页面适应窗口高度，目录、消息列表和详情分别在内部滚动。管理页中的通信记录只包含经 Cooperation 发送的消息。

自动上下文维护

每个会话有独立的 “启用自动压缩” 开关，默认关闭。先确认会话接入和通信正常，再按需启用。

空闲阈值表示：达到该占用后，等待当前工作结束再维护。强停阈值表示：工作过程中达到该占用，先中断对应轮次，再进行维护。数值可按会话修改；必须满足 0 < 空闲阈值 < 强停阈值 < 100。已启用时降低阈值可能立即触发维护。

一次维护会发生什么

达到阈值 → 锁住 Cooperation 入站消息 → 必要时中断原工作
    → 写交付文档 → handoff 回执 + 本轮结束
    → 原生压缩完成
    → 读取交付文档、加载上文 → restored 回执 + 本轮结束
    → 原本工作中才继续任务 → 按顺序投递排队消息

交付文档保存接续任务所必需的信息，比如当前进展、关键约束或容易遗漏的事项，具体内容和组织方式由 agent 判断；文档写入目标会话工作目录的 .cooperation/handoffs/。两个回执都校验身份、阶段凭证与文档内容；普通回复 OK 不会推进流程。

工具沿用原会话的模型、思考强度和权限选项。维护包含模型参与的交付与恢复轮次，会使用原客户端的正常用量。

回执遇到权限确认

维护提示优先要求调用 context_checkpoint；未加载 MCP 时，会提供专用 CLI 命令。Claude 如果要求执行授权，可以按原权限流程批准。

若希望在特定工作项目中允许该专用入口，可由你在该项目的 .claude/settings.local.json 中合并窄规则，例如：

{
  "permissions": {
    "allow": [
      "Bash(node E:/Projects/Cooperation/bin/coop-checkpoint.mjs *)"
    ]
  }
}

保留已有权限条目，并使用实际安装路径。该许可只覆盖专用回执 CLI；工具不会自动安装这条规则。路径包含空格时，以维护提示实际生成的命令及客户端权限匹配结果为准。

流程显示“需要处理”时

先查看原生会话和卡片提示，再选择“核对后继续”“重发当前请求”或取消维护。取消时可选择释放消息或保留消息；保留的消息仍会阻挡后续消息插队。

服务重启会保留锁与流程，确认已有原生完成证据后才能续接。结果未知的消息或压缩不会自动重复执行。

常见问题

数据、升级与使用范围

中央消息、策略、SQLite 数据库、流程与队列保存在工具安装目录的 .cooperation/；交付文档保存在目标工作项目的 .cooperation/handoffs/。服务日志是 .cooperation/service.stdout.log 与 .cooperation/service.stderr.log。

备份前先正常关闭管理服务。备份工具的数据目录；需要保留上下文交接文件时，同时备份相应工作项目的 handoffs 目录。连接记录和 wrapper 注册文件含本机凭据，不应随源码公开。项目的 .gitignore 已排除中央运行数据、机器相关构建产物和本机验收记录。

从旧版升级时，服务会备份并导入旧 messages.jsonl，保留原文件。升级后以 SQLite 为写入来源；若旧日志随后被改动，启动会要求核对，避免形成两个不一致的数据来源。

当前支持同一台 Windows 机器上的会话协作。Cooperation 的锁覆盖本工具入口；原生界面输入与其他工具直连可以绕过它，观测到介入时流程会暂停。活动 goal、子agent 和后台任务的完整暂停与恢复尚未验收，此类目标暂不开放自动维护。

本地原生控制依赖客户端接口，客户端升级后可能需要适配。已验收基线为 Codex Desktop 26.901.6511.0 / Core 0.153.4、Claude Code VS Code 2.1.237；这些是验证版本记录，不是对最新版本的声明。

验证与进一步阅读

在仓库根目录执行：

.\scripts\build-claude-wrapper.ps1
node --test test/*.test.mjs

最近一次完整自动检查 74 项通过。原生专用会话已完成 Codex、Claude 各自的空闲软阈值与工作中硬阈值四项维护流程，验证了回执、原生轮次结束、真实压缩、条件继续与排队消息顺序。新版管理页的视觉与交互复验状态单独记录在验收文档中。