codex-collab

English | 中文

在 Claude Code 中与 Codex 协作——派发任务、审查代码、并行研究，全程不用离开 Claude 会话。

codex-collab 是一个 Claude Code 技能，借助 Codex app server 的 JSON-RPC 协议驱动 Codex——从会话的维护、结构化事件的实时推送，到工具调用的审批管控与对话恢复，全部在 Claude 会话内闭环完成。

核心优势

• 结构化通信 — 与 Codex 之间通过 stdio JSON-RPC 通信，每个事件都有完整的类型定义，可解析、可追踪。
• 实时进度反馈 — Codex 工作时实时推送进度，Claude 随时掌握运行状态。
• 一键代码审查 — 一条命令即可在只读沙箱中审查 PR、未提交更改或特定 commit。
• 会话复用 — 接续先前的会话继续对话，在既有上下文基础上推进，不必从头开始。
• 审批控制 — 按需配置工具调用的审批策略：自动批准、交互确认、拒绝，或交给 Codex 的 Guardian 自动审查（--approval auto）。
• 实时可观测 — run --detach 将长任务交给分离的运行进程；follow --watch 提供专门设计的实时视图，在终端分屏里持续跟踪每一次运行。
• 记忆隔离 — codex-collab 创建的会话默认不进入 Codex 的记忆功能，代理驱动的会话不会改变 Codex 对你本人工作方式的认知。可用 --memory 重新开启（详见选项说明）。

安装

需要 Bun >= 1.0 和 Codex CLI（npm install -g @openai/codex）并加入 PATH。已在 Linux (Ubuntu 22.04)、macOS 与 Windows 10 上测试通过。

git clone https://github.com/Kevin7Qi/codex-collab.git
cd codex-collab

Linux / macOS

./install.sh

Windows

powershell -ExecutionPolicy Bypass -File install.ps1

安装完成后，重新打开终端以使 PATH 生效，然后运行 codex-collab health 验证安装。

安装脚本会自动构建独立 bundle，部署到主目录下（Linux/macOS 为 ~/.claude/skills/codex-collab/，Windows 为 %USERPROFILE%\.claude\skills\codex-collab\），并安装可执行文件（install.ps1 会将其加入 PATH；install.sh 会放置在 ~/.local/bin，若该目录不在 PATH 中会打印提示）。完成后 Claude 即可自动发现该技能。

升级

升级已有安装时，拉取最新代码并重新运行安装脚本即可：

git pull
./install.sh
codex-collab health

Windows:

git pull
powershell -ExecutionPolicy Bypass -File install.ps1
codex-collab health

安装脚本会替换已安装的 skill bundle 和可执行文件 shim。~/.codex-collab/ 下已有的配置、模板、会话历史和运行日志都会保留。请将 ~/.claude/skills/codex-collab/ 视为安装脚本管理的目录：升级时其中的手动修改可能会被覆盖。

从旧版本升级时，codex-collab 会在首次使用时自动把会话状态迁移到按工作区划分的新布局，无需手动迁移状态。旧的 jobs 命令仍可作为 threads 的已弃用别名使用。

开发模式

使用 --dev 以符号链接方式安装，源码变更实时生效：

# Linux / macOS
./install.sh --dev

# Windows（可能需要启用开发者模式或使用管理员终端以创建符号链接）
powershell -ExecutionPolicy Bypass -File install.ps1 -Dev

快速开始

# 向 Codex 提问
codex-collab run "这个项目是做什么的？" -s read-only --content-only

# 代码审查
codex-collab review --content-only

# 恢复会话继续对话
codex-collab run --resume <id> "现在检查错误处理" --content-only

# 长任务：分离运行，在另一个终端分屏实时观看
codex-collab run "大规模重构" --detach --approval auto
codex-collab follow --watch

CLI 命令

命令	说明
run "prompt" [opts]	新建会话、发送提示、等待完成并输出结果（run - 从标准输入读取提示词——不受 shell 引号转义困扰）
review [opts]	代码审查（PR、未提交更改、指定 commit）
threads [--json] [--all]	列出会话（--limit <n> 限制数量，--discover 扫描服务器，--session 只列当前会话期运行过的会话）
kill <id>	中断运行中的会话
follow [id]	实时查看运行中的会话，结束时随其状态退出（已结束的会话则回放最近一次运行）。不带 ID 时自动附着到当前工作区的活跃运行——若无活跃运行则回放最近一次。配合 --watch 保持打开并按启动顺序跟踪每一次新运行（每次运行只显示一次）
output <id> [--last]	查看会话完整日志（--last: 只输出最近一轮的结果）
progress <id>	查看近期活动（日志尾部）
peek <id>	从服务器查看最近的会话片段
config [key] [value]	查看或设置持久化默认值
models	列出可用模型
templates	列出可用提示词模板
health	检查依赖项
version	打印版本号（也可在命令前使用 -v/--version）

会话管理

命令	说明
delete <id> [--purge]	归档会话（可用 codex unarchive 恢复）并删除本地文件；--purge 则在服务端永久删除，不可恢复
clean	清理过期日志和失效映射
approve <id>	批准待处理的请求
decline <id>	拒绝待处理的请求

选项

参数	说明
-d, --dir <path>	工作目录
-m, --model <model>	模型名称（默认: 自动选择最新可用模型）
-r, --reasoning <level>	none, minimal, low, medium, high, xhigh（默认: 自动选择模型支持的最高级别）
-s, --sandbox <mode>	read-only, workspace-write, danger-full-access（默认: workspace-write；review 始终使用 read-only）
--mode <mode>	审查模式: pr, uncommitted, commit, custom
--ref <hash>	指定 commit 哈希（配合 --mode commit）
--resume <id>	恢复已有会话
--approval <policy>	审批策略: never, on-request, on-failure, untrusted, auto（默认: never）。auto: Codex 的 Guardian 审查器自主批准或拒绝每个请求——绝不阻塞等待人工；决策以 Guardian 进度行的形式实时展示
--memory	允许 Codex 的记忆功能学习本次运行创建的会话。默认: 创建的会话会执行 thread/memoryMode/set mode=disabled；恢复的会话永不改动（该标记按会话持久保存，你自己创建的会话应继续进入你的记忆）。只作用于 Codex 的本地记忆整合（~/.codex/memories）——personality 属于显式用户配置（非学习所得），不受影响。持久化设置: config memory true
--detach	（run）在轮次真正开始运行后立即返回；用 follow <id> 观看。任务的生命周期与发起它的 shell 解耦
-w, --watch	（follow）运行结束后不退出——继续跟踪每一次新运行（Ctrl-C 停止）
--template <name>	提示词模板（run 命令；优先使用 ~/.codex-collab/templates/，然后使用内置模板）
--json	对支持的命令输出 JSON（threads、peek）
--all	列出全部会话，不限制显示数量
--discover	从 Codex 服务器查询本地索引中没有的会话
--limit <n>	限制 threads 或 peek 显示的条目数
--full	在 peek 输出中包含所有条目类型（默认只显示消息）
--content-only	隐藏进度输出；配合 output 时仅返回正文内容
--last	（output）只输出最近一轮的结果，而非整个会话历史（隐含 --content-only）
--session	（threads）只列当前会话期运行过的会话
--timeout <sec>	单轮超时时间，单位秒（默认: 1200，最大 2147483）
--base <branch>	PR 审查的基准分支（默认: 自动检测默认分支）
--	选项结束标记；其后的参数一律视为提示词文本
-	（run）从标准输入读取提示词

run 和 review 的退出码标识运行结果：0 完成、1 失败、3 超时、4 被中断、5 因等待审批而中止（该审批请求已失效——用更长的 --timeout 恢复，或改用 --approval auto）、6 broker 占用（瞬态——可重试）。

默认值与配置

默认情况下，codex-collab 自动选择最新模型（优先选择 -codex 变体）及该模型支持的最高推理级别。无需配置——新模型发布后自动更新。

使用 codex-collab config 持久化覆盖默认值：

codex-collab config                     # 查看当前配置
codex-collab config model gpt-5.3-codex # 设置默认模型
codex-collab config reasoning high      # 设置默认推理级别
codex-collab config model --unset       # 取消单个设置（恢复自动检测）
codex-collab config --unset             # 取消所有设置

可配置项: model、reasoning、sandbox、approval、timeout、memory

优先级: CLI 参数 > 配置文件 > 自动检测

配置存储于 ~/.codex-collab/config.json。

参与贡献

欢迎贡献！开发环境搭建及贡献流程详见 CONTRIBUTING.md。本项目遵循 Contributor Covenant 行为准则。

相关项目

如果只需更轻量的交互，不妨试试官方的 Codex MCP server。codex-collab 则专为 Claude Code skill 场景打造，内置代码审查、会话管理与实时进度推送。