cc-in-codex

中文主文档。English README: README.en.md

cc-in-codex 是一个本地 MCP server，让 Codex 可以像人类一样使用你本机已经登录好的 Claude Code，并把 Claude Code 变成一个持续陪伴当前项目的实现助手。

这个工具的目标不是再做一个一次性代码生成器，而是建立一种更高效的双 Agent 工作模式：

• 你只和 Codex 对话。

• Codex 负责思考、拆解、判断、审查和最终汇总。

• Claude Code 负责读仓库、改代码、跑测试、重构、执行命令和使用它自己的 subagent/技能体系。

• 同一个项目目录绑定同一个 Claude Code companion，上下文可以持续积累，也可以从 Claude Code CLI 里恢复。

目录

• 为什么需要它

• 核心能力

• 工作模型

• 两种后端：SDK 与 TUI

• 系统要求

• 安装与构建

• 在 Codex 中注册 MCP

• 快速开始：新项目

• 继续已有 Claude Code 项目

• 可见 TUI 模式

• Codex 应该如何调用

• MCP 工具说明

• 上下文、resume 与 compact

• 状态栏与上下文压力监控

• 安全与权限模型

• 本地状态与隐私

• CLI 用法

• 开发与发布前检查

• 常见问题

• 当前边界

• 推荐工作流

• 开源协议

Related MCP server: claude-code

为什么需要它

Codex 和 Claude Code 的强项不完全一样。

在很多真实工程任务中，一个自然的分工是：

• Codex 更适合做科学式思考、方案权衡、任务拆解、风险判断、代码审查和最终决策。

• Claude Code 更适合做本地工程执行：读大量文件、改代码、跑测试、处理工具链、使用 subagent、持续推进实现。

如果每次都让 Codex 给 Claude Code 发一个孤立任务，效果会很差：

• Claude Code 上下文不连续。

• Codex 不知道 Claude Code 之前做过什么。

• 用户需要同时管理两个 Agent。

• prompt 容易重复、变长、污染上下文。

• 出问题时缺少及时监控和止损。

cc-in-codex 解决的是这个交互问题。它让 Codex 通过 MCP 管理一个本地、持久、可恢复的 Claude Code companion。用户只需要和 Codex 对话，Codex 会在合适的时候调用 Claude Code，并负责审查 Claude Code 的结果。

核心能力

cc-in-codex 当前提供：

• 使用本机 claude 可执行文件和本地 Claude Code 登录态，包括 Claude Max 账号。

• 不要求新的 Anthropic API key。

• 每个 cwd 维护一个持久 Claude Code companion。

• 支持 SDK 后端，用于 Codex 后台委派代码任务并等待结果。

• 支持 TUI 后端，在 tmux 里运行原生 Claude Code 全屏 CLI，用户可以实时观看或接管。

• 支持从已有 Claude Code 会话恢复：

  • SDK：绑定明确的 sessionId。

  • TUI：claude --resume <session-id> 或 claude --continue。

• 支持 raw TUI 输入，例如 /status、/help、/clear、Escape、C-c。

• 支持 Claude Code statusLine，读取真实 context_window 信息，用于判断是否适合 compact。

• 支持 companion_tui_compact_check 和 companion_tui_compact，让 compact 发生在合理节点，而不是机械触发。

• 支持 stop-loss：SDK 后端有运行时间和 stall timeout；TUI 后端可以被 Codex 或用户显式打断。

• 支持项目初始化：生成共享的 AGENTS.md 和 CLAUDE.md，让 Codex 与 Claude Code 读取同一份项目指令。

• 状态只存储在本地 ~/.cc-in-codex/。

工作模型

cc-in-codex 的基本思想是：

User
  |
  v
Codex
  |
  | MCP tools
  v
cc-in-codex
  |
  | local claude executable
  v
Claude Code companion
  |
  v
Project files / tests / tools

职责边界：

• 用户只和 Codex 对话。

• Codex 是 lead agent，负责判断什么时候需要 Claude Code、给出高质量任务 prompt、监控执行、审查结果。

• Claude Code 是 implementation companion，负责在本地项目里执行工程任务。

• cc-in-codex 是连接层，不替代 Codex，也不替代 Claude Code。

这意味着：Claude Code 的输出不是最终答案，Codex 仍然需要 review 和 synthesis。

两种后端：SDK 与 TUI

SDK 后端

SDK 是默认后端，适合日常后台委派。

特点：

• Codex 调用 companion_send 或 companion_start。

• Claude Code 在 SDK/print 风格下完成任务。

• Codex 可以拿到结构化结果、事件、成本、turn 数、session id。

• 适合代码修改、测试、审计、小型重构、只读分析。

推荐场景：

• “让 Claude Code 改这个 bug，然后跑测试。”

• “让 Claude Code 读这几个模块，给我一个实现报告。”

• “让 Claude Code 执行一组明确的工程任务。”

TUI 后端

TUI 后端会在 tmux 中打开原生 Claude Code CLI。

特点：

• 你可以在 Codex 右侧终端 attach 进去，看到 Claude Code 的原生 ASCII/TUI 界面。

• Codex 可以向这个 TUI 发送任务 prompt。

• 你也可以直接在 TUI 里打字、发 slash command、接管会话。

• TUI 后端不尝试从全屏终端里“猜测任务完成”，它更像可见的远程控制。

推荐场景：

• 你想实时观看 Claude Code 在干什么。

• 任务复杂，想保留人工接管能力。

• 你想继续已有 Claude Code CLI 的体验。

• 你要使用 Claude Code 自己的 TUI 能力、slash command、resume picker 或 subagent 工作流。

怎么选

默认用 SDK。需要“看见 Claude Code 原生界面”或“人类随时接管”时用 TUI。

系统要求

• Node.js 22 或更新版本。

• 本机已安装并登录 Claude Code，claude --version 可运行。

• Codex 支持 MCP server。

• TUI 模式需要 tmux。

macOS 安装 tmux：

brew install tmux

确认依赖：

node --version
claude --version
tmux -V

安装与构建

从源码安装：

npm install
npm run build

开发检查：

npm run typecheck
npm run build
npm run smoke

npm run smoke 不会启动真实 Claude 任务，也不会创建 TUI 会话。它只检查：

• MCP server 能正常启动并暴露关键工具。

• SDK resume 绑定逻辑可用。

• CLI help 包含 resume/continue 选项。

在 Codex 中注册 MCP

把构建后的 server 注册到 Codex：

codex mcp add cc-in-codex -- node /absolute/path/to/cc-in-codex/dist/index.js

查看配置：

codex mcp get cc-in-codex

如果 claude 不在 PATH，可以指定：

CC_IN_CODEX_CLAUDE_PATH=/absolute/path/to/claude

注册后重启 Codex，确保工具列表刷新。重启后 Codex 应该能看到 companion_send、companion_resume、companion_tui_open、companion_tui_resume 等工具。

快速开始：新项目

在一个全新项目中，推荐这样用：

1. 用户告诉 Codex：“这个项目使用 cc-in-codex。”

2. Codex 调用 companion_init_project。

3. cc-in-codex 创建：

   • AGENTS.md

   • CLAUDE.md

4. Codex 后续用 companion_send 给 Claude Code 分配任务。

5. 当用户想看实时 UI 时，Codex 调用 companion_tui_open，用户在右侧终端 attach。

初始化项目：

{
  "cwd": "/absolute/path/to/project"
}

生成的 AGENTS.md 是 Codex 和 Claude Code 的共享项目记忆。CLAUDE.md 会提示 Claude Code 先读取 AGENTS.md。

这样做的原因是：项目指令应该写在仓库里，而不是每一轮 prompt 里重复粘贴。

继续已有 Claude Code 项目

如果一个项目本来已经用过 Claude Code，你通常不希望丢掉已有会话上下文。cc-in-codex 支持两种恢复方式。

精确恢复 session id

如果你知道 Claude Code 的 session id，可以让 SDK 后端绑定它：

{
  "cwd": "/absolute/path/to/project",
  "backend": "sdk",
  "sessionId": "00000000-0000-0000-0000-000000000000"
}

之后 Codex 再用 companion_send，就会 resume 这个 Claude Code 会话。

TUI 也可以精确恢复：

{
  "cwd": "/absolute/path/to/project",
  "sessionId": "00000000-0000-0000-0000-000000000000"
}

这等价于在该项目里启动：

claude --resume 00000000-0000-0000-0000-000000000000

继续当前目录最近一次 Claude Code 对话

如果你不知道 session id，但想继续该项目最近的 Claude Code 对话，使用 TUI：

{
  "cwd": "/absolute/path/to/project",
  "continueLatest": true
}

这等价于：

claude --continue

注意：SDK 后端需要明确 session id。--continue 是 Claude Code CLI/TUI 的语义，当前由 TUI 后端负责。

避免误替换正在看的 TUI

如果该项目已经有一个 cc-in-codex TUI pane 在运行，resume 默认不会偷偷替换它。你会得到明确错误，提示已有 tmux session。

如果你明确想关闭现有 pane 并启动恢复后的会话，传入：

{
  "cwd": "/absolute/path/to/project",
  "continueLatest": true,
  "replaceTui": true
}

这个保护很重要：用户右侧终端看到的 Claude Code 会话，必须和 Codex 正在操作的会话一致。

可见 TUI 模式

打开 TUI：

{
  "cwd": "/absolute/path/to/project"
}

工具返回类似：

tmux attach -t ccic-my-project-abc123def0

在 Codex 右侧终端运行这条命令，就能看到原生 Claude Code TUI。

常用 tmux 操作：

Ctrl-b d      detach，退出观察但不关闭 Claude Code
Ctrl-b [      进入 scrollback
q             退出 scrollback

Codex 给 TUI 发任务时，会把 prompt 粘贴到 Claude Code CLI 并按 Enter。用户会在 TUI 中实时看到输入、输出、工具调用和 Claude Code 的交互状态。

TUI prompt 分层

TUI 后端有一个重要 UX 设计：bootstrap 与 task 分离。

第一次向一个新 TUI pane 发送任务时，cc-in-codex 会发送一段 bootstrap，建立 companion 角色：

• Codex 是 lead agent。

• Claude Code 是执行 companion。

• 当前工作目录。

• 权限策略。

• 汇报格式。

• 不要直接问用户，向 Codex 汇报 blocker。

后续每轮任务只发送：

Task: ...

这样避免每轮都把大量身份说明塞进 Claude Code 上下文，同时新 pane 仍然能被正确初始化。

当执行 /clear 或 /compact 后，下一轮会自动重新 bootstrap。

Raw 输入

有些输入不应该被 cc-in-codex 包装成任务，例如 slash command 或控制键。使用 companion_tui_raw：

{
  "cwd": "/absolute/path/to/project",
  "text": "/status"
}

发送 Escape：

{
  "cwd": "/absolute/path/to/project",
  "keys": ["Escape"],
  "enter": false
}

发送 Ctrl-C：

{
  "cwd": "/absolute/path/to/project",
  "keys": ["C-c"],
  "enter": false
}

Raw 输入适合：

• /status

• /help

• /clear

• /compact

• Escape

• C-c

• 用户明确要求原样输入的内容

长任务 prompt 和较长 raw 输入会通过 tmux buffer 粘贴，并按输入长度动态等待后再按 Enter。这样比直接 send-keys 更适合长命令、长 slash command 或多行任务说明。

Codex 应该如何调用

这个 MCP server 是给 Codex 用的。理想行为是：

• 用户说“用 Claude Code 做一下这个实现”，Codex 调用 companion_send。

• 用户说“做一个较长实现/重构/审计”，Codex 调用 companion_start，然后用返回的 eventCursor 调用 companion_wait 等进展。

• 用户说“打开可见 TUI”，Codex 调用 companion_tui_open。

• 用户说“继续我原来 Claude Code 的上下文”，Codex 优先判断是否有 session id；没有则用 TUI continueLatest。

• 用户说“看一下右边 Claude Code 在干嘛”，Codex 调用 companion_tui_screen。

• 用户说“停掉它”，Codex 调用 companion_cancel 或 TUI raw C-c。

• 用户说“现在是否该 compact”，Codex 先调用 companion_tui_compact_check，再决定是否 companion_tui_compact。

Codex 不应该：

• 把整个仓库摘要粘贴给 Claude Code。

• 每轮重复长篇身份说明。

• 在没有检查 checkpoint 的情况下随便 compact。

• 盲目信任 Claude Code 的输出而不 review。

• 在用户正在观察 TUI 时静默替换为另一个会话。

MCP 工具说明

通用工具

TUI 工具

上下文、resume 与 compact

Claude Code 自己会保留上下文吗

会。Claude Code 会在本地保存可恢复的 session。cc-in-codex 不需要复制 Claude Code 的全部对话历史。

但有一个边界必须讲清楚：

Codex 不能天然看到 Claude Code 的完整历史。Codex 能看到的内容来自：

• MCP 工具返回的结构化结果。

• companion_recent 保存的事件摘要。

• companion_tui_screen 捕获的当前 TUI 屏幕。

• AGENTS.md / CLAUDE.md / 项目文件。

• statusLine 快照。

所以 cc-in-codex 的设计是：

• Claude Code 的完整上下文由 Claude Code 自己维护。

• Codex 的当前判断依赖 MCP 暴露出来的高信号状态。

• 重要项目知识应该进入 AGENTS.md，而不是只存在某次终端滚动记录里。

resume 的目的

resume 不是为了把所有历史复制给 Codex，而是为了让 Claude Code 自己继续原来的上下文。

当 Codex 调用 companion_send 时，SDK 后端会用已绑定的 session id resume。TUI 后端则可以启动 claude --resume 或 claude --continue。

compact 的原则

compact 不是越频繁越好。好的 compact 应该发生在：

• 当前任务已经汇报完成。

• 测试或验证结果明确。

• 没有正在运行的命令。

• 没有审批弹窗或未完成交互。

• 上下文压力已经中高，继续保留完整 transcript 的收益下降。

推荐流程：

1. 先调用 companion_tui_compact_check。

2. 看 checkpointReady 和 recommendation。

3. 只有推荐 compact_now，或用户明确要求时，才调用 companion_tui_compact。

companion_tui_compact 会发送带保护说明的 /compact，要求 Claude Code 保留：

• companion 分工关系。

• 当前项目状态。

• 最近关键决策。

• 未完成任务。

• 验证状态。

• blocker。

• 用户可见工作流假设。

状态栏与上下文压力监控

Claude Code 支持 statusLine。配置后，Claude Code 会把包含 context_window 的 JSON 发给命令。cc-in-codex 可以保存这些快照，用于更准确判断上下文压力。

在 Claude Code settings 中加入：

{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/cc-in-codex/dist/index.js statusline"
  }
}

配置后，快照会写到：

~/.cc-in-codex/statusline/

companion_tui_compact_check 会优先使用 statusLine 的真实 context_window.used_percentage。如果没有配置，它会退回到屏幕长度和事件数量的启发式判断。

压力等级当前逻辑：

• used_percentage >= 75：high

• used_percentage >= 60：medium

• 其他：low

如果没有 statusLine：

• 事件很多、屏幕内容很长、字符数很高时提高压力等级。

• 这是保守估计，不是精确 token 读数。

安全与权限模型

默认策略是 balanced。需要注意：SDK 后端和 TUI 后端的安全边界不同。

SDK 后端通过 Claude Agent SDK 的工具许可回调做拦截，因此可以执行较强的工具级策略。TUI 后端运行的是原生 Claude Code CLI，cc-in-codex 负责可见启动、发送 prompt、发送 raw key、读取屏幕和打断，但不能在 MCP 层对 TUI 内部每一次工具调用做同等级别的路径拦截。

maxBudgetUsd 是 SDK 单轮调用的可选止损参数，不会作为项目默认配置持久化。Claude Max/subscription 的正常个人工作流建议省略它，主要依靠 maxRuntimeMs、stallTimeoutMs、TUI 可见监控和人工 C-c 止损。

mode

permissionPolicy

SDK 只读模式会阻止：

• Bash

• Edit

• MultiEdit

• Write

• NotebookEdit

SDK balanced 会检查常见路径参数，发现 cwd 外路径时拒绝。

TUI 后端的安全策略更接近“可见远程控制”：

• 用户可以 attach 到同一个 tmux pane 实时观看。

• Codex 可以用 companion_tui_screen 检查状态。

• 出现危险命令、错误循环、权限循环或用户要求停止时，Codex 可以发送 C-c。

• TUI 内部实际工具权限仍由 Claude Code CLI、项目设置、用户确认和本地环境共同决定。

• 如果要让 TUI 以 bypass 启动，必须新建或 replaceTui:true 重建 pane；已经存在的 Claude Code TUI 不能事后改变启动权限参数。

注意：任何本地自动化工具都不能替代用户和 Codex 的审查。对于高风险命令、跨目录写入、删除操作、发布操作，Codex 应该保持明确审查。

本地状态与隐私

cc-in-codex 使用本地 Claude Code 登录态，不引入新的云端账户。

本地状态位置：

~/.cc-in-codex/state.json
~/.cc-in-codex/statusline/

state.json 保存：

• cwd 到 companion 的绑定。

• Claude Code session id。

• tmux session 名称。

• attach command。

• 最近事件摘要。

• 最近结果。

• 配置项。

它不试图保存 Claude Code 的完整 transcript。完整 Claude Code session 由 Claude Code 自己维护。

CLI 用法

cc-in-codex 默认作为 MCP server 从 stdio 启动。

statusline

Claude Code statusLine 调用：

cc-in-codex statusline

通常不需要手动执行。

attach

打开或 attach 项目的 TUI：

cc-in-codex attach /absolute/path/to/project

继续该项目最近的 Claude Code 对话：

cc-in-codex attach /absolute/path/to/project --continue

恢复指定 session：

cc-in-codex attach /absolute/path/to/project --resume <session-id>

关闭已有 cc-in-codex tmux pane 后再启动：

cc-in-codex attach /absolute/path/to/project --continue --replace

查看帮助：

cc-in-codex attach --help

开发与发布前检查

发布前必须跑：

npm run typecheck
npm run build
npm run smoke
npm pack --dry-run

推荐额外检查：

npm audit --audit-level=moderate
git status --short

npm pack --dry-run 应该只包含：

• dist/

• scripts/smoke.mjs

• README.md

• README.en.md

• LICENSE

• package.json

不要把 node_modules/、本地状态、日志、临时包、测试残留发布出去。

当前 .gitignore 已忽略：

node_modules/
dist/
.DS_Store
.cc-in-codex/
*.log

常见问题

这个工具会不会影响我平时直接用 Claude Code

不会。它使用你本机已有的 claude 命令和 Claude Code 本地 session。你仍然可以正常打开 Claude Code CLI。

我能在 Claude Code CLI 里 resume 到 cc-in-codex 创建的对话吗

可以。companion_status 和 companion_result 会返回：

claude --resume <session-id>

你可以在终端里执行这条命令。

Codex 能不能看到 Claude Code 的完整历史

不能天然看到。Codex 只能看到 MCP server 暴露的结果、摘要、屏幕捕获和项目文件。Claude Code 的完整上下文由 Claude Code 自己保留。

TUI 是否实时同步

是。TUI 模式下，Claude Code 运行在 tmux 中。你 attach 到同一个 tmux session 后，会看到同一个原生 Claude Code 界面。Codex 发 prompt 时，输入会真实出现在这个界面里。

我能不能自己在 TUI 里打字

可以。你和 Codex 操作的是同一个 Claude Code TUI。需要注意的是，如果你手动改变了状态，Codex 可能需要通过 companion_tui_screen 或 companion_status 重新确认。

为什么 TUI send 不等待任务完成

因为 Claude Code TUI 是全屏交互界面，当前没有稳定结构化信号能证明“任务已完成”。cc-in-codex 选择保守：负责发送、监控、截图、打断，但不假装能完美解析 TUI 状态。

SDK 和 TUI 是同一个进程吗

不是。SDK 后端和 TUI 后端是两条调用路径，但它们可以通过 Claude Code session id 连接到同一个会话上下文。TUI 可以用于观察/接管，SDK 适合结构化后台任务。

为什么需要 AGENTS.md 和 CLAUDE.md

因为项目长期指令应该进入仓库，而不是每次通过 prompt 重复注入。AGENTS.md 是 Codex 和 Claude Code 的共享项目记忆，CLAUDE.md 指向它。

没有 tmux 可以用吗

可以用 SDK 后端。只有 TUI 后端需要 tmux。

statusLine 是必须的吗

不是。没有 statusLine 也能用。但配置 statusLine 后，compact check 能看到更准确的上下文窗口压力。

当前边界

这是一个本地优先的开发者工具，当前刻意保持简单。

已知边界：

• TUI 后端不保证自动判断任务完成。

• SDK 后端的 --continue 语义需要明确 session id；最近会话 continue 由 TUI 后端负责。

• statusLine 依赖 Claude Code 提供的 JSON 字段，字段变化时可能需要适配。

• balanced 路径检查覆盖常见工具参数，但不是形式化沙箱。

• 这个项目不替代 Codex 的最终 review。

推荐工作流

普通代码任务

1. 用户向 Codex 描述目标。

2. Codex 拆解任务。

3. Codex 调用 companion_send。

4. Claude Code 修改代码并运行检查。

5. Codex review diff 和验证结果。

6. Codex 向用户汇报。

复杂实现任务

1. Codex 先用 SDK 或本地工具读关键上下文。

2. Codex 打开 TUI：companion_tui_open。

3. 用户 attach 到右侧终端观看。

4. Codex 用 companion_tui_send 发送高质量任务。

5. Codex 定期用 companion_tui_screen 检查状态。

6. 出现错误循环或危险命令时，Codex 用 C-c 止损。

7. 任务完成后，Codex review 代码并跑最终检查。

长期项目

1. 初始化 AGENTS.md 和 CLAUDE.md。

2. 把稳定项目知识写入 AGENTS.md。

3. 让 Claude Code companion 持续在同一 cwd 工作。

4. 高压前在 checkpoint 做 compact。

5. 必要时通过 claude --resume <session-id> 手动接管。

开源协议

MIT。见 LICENSE。