English · 简体中文 ↓

Codex × Claude Code Bridge

A local MCP bridge for Codex to delegate, review and verify Claude Code work.

Quick start · Agent Skill · Frequency & reasoning · Verification · 简体中文

What it does

Codex Claude Code Bridge is a Codex plugin and local MCP server for AI coding agent orchestration. Give Codex a goal, workspace and acceptance criteria. It can create or attach a Claude Code session, delegate scoped implementation, receive handoffs, arrange review and verify the actual changes.

Codex handles planning and key decisions, and can take over implementation. Claude Code handles scoped coding, checks and independent review. Local processes manage sessions, save evidence and wait for events.

The executor uses your existing Claude Code login or model configuration, including third-party models configured through CCSwitch. Orca is optional. Costs depend on the provider, context, caching and rework; the project does not promise a fixed saving.

Related MCP server: codex-claude-subagent

How collaboration works

Claude can actively report results, blockers or decisions. Routine progress stays local; eligible handoffs and major exceptions trigger Codex CLI resumption of the controller. Receiving a report, processing it and accepting the work are separate states.

Native managed tasks support isolated Git worktrees, independent review, revision and acceptance merging. Sessions and owned worktrees or branches can be cleaned up after confirming they are no longer reusable. Existing user workspaces and shared results retain their ownership.

Choose a runtime

Start with native terminals. You do not need Orca.

Orca is an optional desktop workspace for multiple AI terminals and Git worktrees. It is not a model. Use it if you already run Claude there or want a shared view of visible sessions. Feature boundaries · Mac setup

Quick start

Prerequisites: Codex CLI, a working Claude Code configuration, Node.js 20+ and Git. Native Windows windows also need Windows Terminal and PowerShell 7. macOS uses Terminal. Both platforms use the same source package.

codex plugin marketplace add https://github.com/lordfine/codex-claude-bridge.git
codex plugin add claude-code@codex-claude-bridge

Reload the plugin/MCP connection if required, then tell Codex:

Check the Claude bridge environment without dispatching a task.

Initial native-terminal setup downloads runtime dependencies through npm. After setup, start with a small task:

Workspace: . Use a native managed Claude session to improve the README setup instructions only. Use medium frequency and medium reasoning. Verify the changes against the project scripts, and do not merge yet.

New work happens in a separate worktree; ask Codex to show its path and diff. Full setup guide

Install an Agent Skill

The standalone codex-claude-bridge skill provides first-run onboarding. It checks the environment and, for an authorized installation or delegation task, prepares the full Codex plugin through the official CLI.

npx skills add lordfine/codex-claude-bridge --skill codex-claude-bridge --agent codex

Then invoke:

Use $codex-claude-bridge to prepare Codex–Claude Code collaboration. Check my current setup first.

Installing the skill does not by itself start an MCP server. The skill verifies plugin installation, handles any required reload, runs setup and routes to the runtime collaboration skill. It preserves your model configuration. Successful first use includes one optional Star/Watch suggestion; skipping it does not affect any functionality.

Skill source: SKILL.md. Discovery and onboarding. Skills directory indexing is separate from direct installation; publication does not guarantee immediate search visibility.

Frequency and reasoning are independent

The default is medium frequency + medium reasoning.

• Frequency sets when Codex intervenes: complete batches, milestones or agreed subtasks. Major exceptions and necessary decisions still escalate.

• Reasoning sets requested low/medium/high effort. Complex decisions or repeated failures can receive a scoped increase, then return to the original setting.

Ask for low frequency + low reasoning for well-scoped batches, or low frequency + high reasoning for complex work with focused reviews. New Claude sessions receive effort settings and scoped agent definitions. Existing sessions may need an optional restart; the current desktop Codex turn cannot be changed instantly. CLI-displayed effort does not prove a third-party gateway honors it.

Reuse evidence and collect useful feedback

Task briefs stay focused on the goal, scope, handoff and required checks. Reports include evidence pointers; Codex expands details only when needed. Verification records bind the source snapshot, declared environment, scope and command. Matching evidence can be reused; changes, failure, insufficient coverage or risk require additional verification.

Enable event-driven resumption and let Codex save its phase and end the current turn. An active Goal or another controller writer can still delay resumption.

For an actual task retrospective, invoke:

Use $claude-code:bridge-retrospective to collect a redacted bridge evidence bundle.

Local collection recursively covers workflow logs and deduplicates requests. Unique events, retry attempts and model executions with usage evidence are counted separately. Collection does not call a model; the invocation turn itself still consumes tokens. Unknown costs remain unknown. Logs are not uploaded automatically.

Verified scope

Version 0.24.0 passed 197 local bridge regressions and eight CI combinations: Windows, Linux, Mac ARM/Intel × Node.js 22/24. An isolated native session actually called a scoped agent, submitted two reports, and triggered Codex to process both and write an acceptance file. A new Orca session received and completed a test instruction, then its terminal was removed. The onboarding entry has separate installer regressions.

A 30-second quiet interval produced no extra run or usage. This is not a business cost benchmark. Mac GUI/model field tests and private gateway reasoning support remain unverified. Actual receipts and limitations

Documentation and support

Quick start · Best practices · Reasoning profiles · Troubleshooting · Retrospectives · Changelog

For agents and tools: llms.txt provides concise links and boundaries; project metadata describes supported capabilities. These are project-maintained aids, not an external certification or a promise that every search engine will consume them.

If the project helps, you can voluntarily Star to bookmark it or Watch to choose update notifications. Report reproducible issues with the version, runtime and redacted evidence through Issues.

MIT licensed; inherited copyrights are retained. Project origins. Illustrations are editable project diagrams, not software screenshots.

English ↑ · 简体中文

Codex × Claude Bridge

把目标交给 Codex，让 Claude Code 执行，再由 Codex 验收。

快速开始 · 选择运行方式 · 频率与思考 · 验证记录 · 最新版本

你能用它做什么

把“复制任务到 Claude、再复制结果回 Codex”的操作接起来。你只需给 Codex 目标、工作目录和验收条件，它就能创建或接入 Claude Code 会话、下达任务、接收交付、安排审查并继续工作。

Codex 负责规划和关键判断，也能接手改代码；Claude Code 负责明确范围内的实现、检查与独立审查。连接器在本机管理会话、保存协作证据、处理事件和等待。

Claude Code 默认沿用你当前的登录或模型配置，包括已经通过 CCSwitch 配置的第三方模型。你可以指定当前配置中的模型名称，连接器不会自行切换 CCSwitch 供应商配置。实际费用取决于模型、网关、上下文和返工，项目不承诺固定节费比例。

协作怎样推进

Claude 可以主动回传结果、受阻原因或待决定事项。普通进展由本地程序保存，完整交付和重大异常按档位触发 Codex CLI 续接原主控。阶段交付、主控处理和业务验收分别记录，最终判断依靠实际改动与检查证据。

确认没有复用价值后，可清理连接器创建的会话、专用工作树与分支。已有用户目录与共享成果按各自归属保留。协作和收尾说明

选择运行方式

没有 Orca 也能使用。第一次体验建议选择普通终端。

“工作树”是同一 Git 仓库的另一个目录与分支，适合让执行方独立修改，验收后再合并。它和模型会话是不同的资源。

Orca 是集中管理 AI 编程终端、项目、代码差异和工作树的桌面工作台。它是可选的软件，不是执行模型。

如果你已经在 Orca 中使用 Claude Code，或者经常管理多个可见终端，可以选这条路径。连接器通过 Orca CLI 操作精确终端，并按 Claude UUID 核对身份。Orca 自身的功能与本插件接入的功能分别看。官方终端说明

详细能力与限制 · Windows 首次准备 · Mac 安装与验收

快速开始

准备好 Codex、能正常回复的 Claude Code、Node.js 20+ 和 Git。Windows 普通窗口还需要 Windows Terminal、PowerShell 7；Mac 使用系统 Terminal。两种平台使用同一源码包。

1. 安装插件

git clone https://github.com/lordfine/codex-claude-bridge.git
cd codex-claude-bridge
codex plugin marketplace add .
codex plugin add claude-code@codex-claude-bridge

也可以下载最新源码包，解压后在市场根目录执行最后两条命令。

2. 重新加载插件，然后对 Codex 说

检查 Claude 协作插件环境，先不要派发任务。

首次准备原生终端会安装运行依赖，需要 npm 和网络。环境检查通过后，再做一个真实小任务。完整准备与排障

3. 先试一个范围明确的小任务

工作区：〈Git 仓库绝对路径〉。通过普通终端托管 Claude，只补充 README 中的环境准备说明。使用中频、中思考，不改业务代码。完成后核对实际差异与项目脚本，先不要合并。

你会看到 Claude 的可见窗口。新任务在独立工作树中执行，原目录不会立即出现全部改动，可以让 Codex展示执行目录和差异。

如果按上面的本地克隆方式安装，先在项目目录更新源码：

git pull --ff-only
codex plugin marketplace upgrade codex-claude-bridge

如果市场直接登记的是 Git 来源，可使用市场升级命令获取更新。升级后重新加载插件／MCP 实例；运行中的 Claude 会话是否应用新设置，以实际回执为准。

通过技能首次准备

可以从Agent Skills生态安装独立入口：

npx skills add lordfine/codex-claude-bridge --skill codex-claude-bridge --agent codex

在Codex中使用 $codex-claude-bridge，先检查环境，再根据已授权任务准备完整插件。技能本身不等于MCP服务器；插件安装、工具加载与真实任务成功分别确认。首次准备完成后只提示一次可自愿Star／Watch，跳过不影响使用。收录与首次安装说明

频率与思考分别调

默认中频＋中思考，两个参数可以独立组合。

• 交互频率：低频在完整批次交付时介入，中频在里程碑介入，高频在约定子任务交付时介入；重大异常和必需决策及时升级。

• 思考等级：低、中、高控制处理工作的推理投入。复杂决策或重复失败可以局部升档，处理完恢复。

可以直接说：

用低频、低思考完成这批边界明确的改动；明确子任务交给少量子代理，小改动直接完成。

这个问题比较复杂，用低频、高思考；阶段交付时集中核查关键逻辑。

新 Claude 会话会传入思考参数并加载分档子代理，默认继承当前模型。已有会话可能显示“待重启”；Codex 当前正在生成的桌面轮无法即时调档。CLI 显示档位也不能证明第三方网关实际遵守参数。档位、生效范围与操作说明

把投入花在必要的工作上

减少重复阅读。 派单只写目标、范围、交付和必要约束；执行方回传短报告和证据位置，主控按需展开详情。

复用可靠检查。 检查账本绑定源码、环境、范围和命令。条件一致时复用，变化、失败或证据不足时补验；主控仍核查关键逻辑和覆盖，保留必要的全量及部署检查。

等待交给本地程序。 普通进展和无变化状态不由连接器反复启动模型轮。启用事件续接后，让 Codex 保存阶段并结束当前轮，收到交付再继续。运行中的 Goal 或其他写入器长期占用主控时，续接仍可能延迟。

在实际工作窗口收集复盘

输入：

使用 $claude-code:bridge-retrospective 复盘本次 Claude 协作，生成用于迭代连接器的证据包。

本地程序读取当前主控及关联 Claude 日志，生成 复盘报告.md＋证据包.json，默认保存在用户目录 .cache/cc-plugin-codex/迭代复盘/。将返回的路径交给插件开发窗口，就能继续定位问题。

采集递归覆盖工作流子日志、跨来源去重，分别记录独立事件、重复调度和有用量证据的模型执行；无法归因与缺失数据保持明确。采集程序不调用模型，使用技能的这一轮仍有正常用量。日志默认不上传，费用没有可靠账单时保持未知。复盘说明

已验证到哪里

以上是 0.24.0 的验证范围，不能外推为所有模型、Goal 流程或故障场景都已验证。详细回执与限制 · CI 记录

给Agent和搜索工具的入口

llms.txt提供短说明和文档链接，项目说明.json给出能力与限制。它们是项目维护的辅助入口，不保证所有搜索引擎或Agent采用。

有用的话欢迎自愿Star收藏，或Watch选择更新通知；连接器不会替用户操作。

文档与反馈

通过 Issues 提交问题，附插件版本、运行方式与脱敏复现步骤。协作异常可附复盘文件，提交前核对内容。

配图为项目矢量示意，不是软件截图。项目独立维护，保留沿用源码的版权与 MIT 许可；见项目来源。