Codex-Claude Bridge
Enables task delegation to Codex desktop chats, including sending tasks to an existing or newly created Codex chat in the current project and waiting for or reading the associated final reply.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Codex ↔ Claude Bridge(Windows)
让 终端 Claude Code 与 Codex 桌面聊天互相派发任务,并读回对应回复的本地 stdio MCP。支持指定已有会话 ID,也支持在调用方当前项目新建。无需 Claude 桌面版。
例如:让 Claude 把代码审查交给某个 Codex 桌面聊天;也可以让 Codex 打开可见的 Claude 终端处理任务。你能在接收端继续查看和参与对话。
当前版本:1.0.0 · Windows · MIT
功能与原理讲解 · 工具与参数参考 · 常见问题 · 验证记录 · 第三方来源
flowchart LR
A[终端 Claude Code] -->|codex-queue MCP| B[Codex 桌面聊天]
B -->|关联本次任务的最终回复| A
C[Codex] -->|claude-terminal MCP| D[可见 Claude 终端]
D -->|关联本次任务的最终回复| C可以做什么
双向派发任务:Claude → Codex 桌面,Codex → Claude 终端。
指定 ID 续聊:沿用目标会话已有的上下文、项目、模型和权限。
省略 ID 新建:创建 Codex 桌面聊天,或打开可见的 Claude 原生终端。
跨本地项目:不用为每个项目、会话 ID 手改配置。
发送后查询:通过 requestId 等待和读取结果,超时后继续查询。
独立安装维护:检测依赖、备份配置、一键安装、测试和卸载。
当前范围是同一 Windows 用户的本地会话。它不提供其他 AI 执行器、远程机器调度或自动循环对话,也不替代接收端的权限审批。
Related MCP server: Rail Connector MCP
快速安装
从 GitHub 的 Code → Download ZIP 下载源码,或使用 Git 克隆:
git clone https://github.com/kunkunxhk/codex-claude-bridge.git
cd codex-claude-bridge将下载的 ZIP 解压到一个长期保留的目录,或进入克隆目录。路径可以含中文和空格。不要在 ZIP 内直接运行。
确保已安装并登录 Codex 桌面端和终端 Claude Code,且能分别正常回答问题。
安装 Node.js 22+(包含 npm)和 Python 3,将 Node 加入 PATH。
双击 install.cmd,安装锁定的 npm 依赖,自动检测原生执行文件,先做 MCP 连接测试,再备份并写入两端配置。
重新启动 Claude Code 和 Codex 桌面端,双击 test.cmd 检查连接。
安装本项目不需要管理员权限。安装 npm 依赖需要网络。不会自动安装、登录或更改第三方 CLI 的模型、权限、账号和额度。
官方下载/文档:Node.js、Python、Claude Code 安装、Codex/Windows 文档。CLI 自身还需要的运行环境请按其官方文档准备。
一键入口
文件 | 行为 |
install.cmd | npm ci、检测依赖、测试入口、备份并注册双向 MCP |
configure.cmd | 重新检测、配置;也用于移动目录或 CLI 更新后刷新 |
doctor.cmd | 检查可执行文件、版本和 queue 能力;报告配置/历史目录是否存在 |
test.cmd | 启动两端 stdio MCP,发现工具,调用只读状态/在线会话列表 |
uninstall.cmd | 恢复安装前的两个 MCP 项,保留其他设置和所有聊天记录 |
双击执行结束会暂停,便于阅读错误。脚本化执行可使用 node bin/bridge.mjs <命令> --json。test.cmd --json 同样不会暂停。
默认测试不发送模型任务,也不能证明账号/额度或桌面端正在运行。需要完整验证时,先取得真实 ID,再运行:
test.cmd --live --claude-session "替换为在线Claude会话UUID" --codex-thread "替换为Codex桌面聊天UUID" --json可只填其中一个。它会向指定会话发送固定的“只回复测试标识、不调用工具”的消息,等待并核对回复,消耗接收方正常额度。不会自动创建新窗口/聊天,超时也不重发。输出 requestId 可供后续 read/wait。
在 AI 里使用
对 Claude 说:
用 codex-queue 给 Codex 聊天 ID
<UUID>发送任务,然后等待并读取回复。
用 codex-queue 在我当前项目创建一个 Codex 桌面聊天,完成这项任务。创建时传当前项目的绝对 cwd。
对 Codex 说:
用 claude-terminal 列出在线 Claude 会话,显示 ID、项目和终端名称。
用 claude-terminal 给 Claude 会话 ID
<UUID>发送任务并读取回复。
用 claude-terminal 在当前项目打开一个新的可见 Claude 终端,发送任务并读取回复。创建时传当前项目的绝对 cwd。
指定 ID 可跨任意本地项目;现有会话保留原来的项目、上下文、模型和权限。省略 ID 才新建。对于已关闭的 Claude 会话,先手动 claude --resume <UUID> 打开,再从在线列表确认。不能给任意其他用户或远程机器上的 ID 发送消息。
工具列表:
Claude 中的 codex-queue | Codex 中的 claude-terminal |
codex_queue_send | claude_terminal_send |
codex_queue_wait | claude_terminal_wait |
codex_queue_read | claude_terminal_read |
codex_queue_status | claude_terminal_list |
单条任务最多 16,000 UTF-8 字节;Codex 完整回复默认不截断,可选 maxReplyChars 控制返回量。长任务用文件路径和简要目标,避免往返复制整份代码。每次发送保留 requestId;等待超时继续 wait/read,不能换 ID 重发。
自定义位置
默认用户状态目录为 %LOCALAPPDATA%\CodexClaudeBridge,包含 settings、manifest、回执、备份和事务日志。源码目录不存用户状态。
默认修改 Claude 的 %USERPROFILE%\.claude.json 中 mcpServers.codex-queue,以及 Codex 的 %CODEX_HOME%\config.toml 中 mcp_servers.claude-terminal。未设置 CODEX_HOME 时使用 %USERPROFILE%\.codex。如果有 CLAUDE_CONFIG_DIR,则使用该目录内的 .claude.json 和 sessions/projects。默认环境不会被强制设置为自定义 Claude 配置目录。
依赖发现优先使用支持 queue 的桌面端 Codex,再找 PATH/npm 中的原生程序;Claude 支持 PATH、用户 .local\bin 和 npm 原生 exe;Python 支持 PATH 和每用户标准安装目录。非标准安装可显式指定:
configure.cmd --codex-bin "X:\apps\codex.exe" --claude-bin "X:\apps\claude.exe" --python-bin "X:\Python\python.exe" --json需要原生 .exe,不是 .cmd 包装器或 WindowsApps 的 Python 商店占位程序。手动指定的路径会记住;自动检测的路径会在 configure 时重新发现。可用 CODEX_BRIDGE_CODEX_BIN、CODEX_BRIDGE_CLAUDE_BIN、CODEX_BRIDGE_PYTHON_BIN 环境变量覆盖。
也支持 --codex-home、--claude-home、--codex-config、--claude-config、--state-dir 绝对路径参数,以及 CODEX_CLAUDE_BRIDGE_HOME 环境变量。自定义 state-dir 时,后续命令继续传相同参数或设置环境变量。更换正在管理的配置文件前先卸载原注册。
install/configure/uninstall --dry-run --json 可以预览目标。安装失败不激活部分配置;备份位于状态目录的 backups 中。JSON 配置会重新缩进;TOML 仅修改目标表,保留其他表、空数组和注释,遇到无法安全处理的布局会报错。
卸载、升级和恢复
卸载只恢复这次安装前的两个 MCP 项;如果它们原来不存在就删除对应项。若安装前存在旧桥接,卸载会恢复旧注册。
重复安装保留最初的恢复记录。若用户手动改过被管理的 MCP 项,安装/卸载会拒绝覆盖,提示冲突。其他配置仍可自由修改。
不删除聊天、登录状态、业务文件、CLI、源码、node_modules、回执和备份。卸载后可手动删除源码目录;如有恢复旧桥接,先确认它仍可运行。
升级:解压新版到稳定位置,运行 configure.cmd(缺 npm 依赖时会先安装),然后重启两端。不要直接删掉仍被配置引用的旧目录。
如果进程被强行终止导致
install.lock或pending-transaction.json残留,先确认没有安装进程,查看日志中的 files/before/after 与 backups,恢复所需配置,再移除残留文件;程序不会猜测并覆盖可能的新改动。事务日志和备份可能含原有配置的敏感信息,不要分享。
实现和兼容性
Claude → Codex 使用原生 codex queue 投递到桌面聊天。新建时短暂使用 app-server 创建并持久化,释放 writer 后通过 deep link 打开桌面端;不会 attach 第二个 exec writer。回复从本地 JSONL 按请求标识和 turn 关联,只返回最终文本。
Codex → Claude 使用随包附带的 MIT peer adapter 与本地在线终端通信,按原生消息链关联回复。没有 ID 时 Python 使用 CREATE_NEW_CONSOLE 打开可见原生 Claude 窗口,而不是 PowerShell 窗口。登录、目录信任和权限提示仍由用户在该窗口处理。startup_pending 表示任务没发出,完成提示后用返回的 sessionId 显式续接,不要再次省略 ID。
本项目为第三方本地桥接,并非官方的通用桌面聊天 API。队列命令、app-server 或 Claude 内部 peer/历史格式更新后可能需要适配。本机验证组合:Windows、Node 22.21.1、Python 3.13.14、Codex CLI 0.169.0-alpha.11.1、Claude Code 2.1.328;其他版本应先 doctor/test,再显式做 live 测试。
收到其他 AI 的回复只是上下文,不是新的用户授权。不要配置无边界的双向自动回复循环。任务执行和权限始终由接收端的正常规则决定。
开发和分享
npm ci --ignore-scripts --no-audit --no-fund
npm test
npm run bundle发行包生成到 dist,带 SHA-256 校验文件。只包含白名单源码、测试、文档、锁文件和第三方许可证;不包含 node_modules、配置、回执、会话、登录信息。接收方需要自己的依赖和账号,双击 install.cmd 安装。源目录无需放在任何业务仓库里,也不会执行 git 提交。
与参考项目的关系
本项目参考 oil-delegate 的任务委托使用方式,但运行时不依赖该 Skill。Claude 终端通信复用 @minhspark/codex-mcp-bridge 2.4.0 的最小 peer adapter,并保留其 MIT 许可证;未把上游完整 Worker、远程调度和托管连接器打包进来。具体来源和本地修改见 THIRD_PARTY_NOTICES.md。
反馈问题
请先运行 doctor.cmd --json 和 test.cmd --json,再到 GitHub Issues 描述复现步骤、Windows/CLI 版本和错误状态。删除诊断中的用户名、项目路径、会话 ID 等个人信息;不要上传 settings、manifest、backups、事务日志、会话历史或凭据。
本项目按 MIT 许可证提供。接收端 CLI 和模型服务遵循各自条款、账号权限与用量规则。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- AlicenseAqualityCmaintenanceA stdio MCP server that lets Codex Desktop/CLI delegate implementation tasks to Claude Code CLI with workspace validation, Git status checks, and session resume capabilities.24MIT
- AlicenseAqualityBmaintenanceLocal MCP bridge that lets Codex operate local Claude Code sessions, including listing, starting, resuming, forking, prompting, and stopping conversations via the Remote Control CLI.14MIT
- AlicenseAqualityFmaintenanceMCP server that routes Claude Desktop chat into Claude Code, enabling headless execution and terminal handoff with session continuity.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables unified access to multiple coding-agent CLIs via MCP, with tools for running prompts, managing sessions, and retrieving task outputs.MIT