@cottonc/codex-claude-collab
v0.1.5
Published
Local collaboration between existing Codex and Claude Desktop Code sessions
Readme
Codex × Claude Desktop Collaboration
连接 Codex Desktop 与 Claude Desktop Code 会话,也支持创建缺少的同伴会话。用户在两个 GUI 中操作;CLI 执行投递、关联回复、空闲唤醒和任务状态管理。
发布形态是 npm CLI+两端同名的全局 Skill codex-claude-collab。没有客户端插件或 MCP Server。pnpm add -g 安装程序,cc-collab install 用标准 skills CLI 注册到 Codex 和 Claude,适用于任意项目。
Skill 适用于用户明确采用的双 GUI 协作流程,两个方向均可发起:
- 在 Codex 侧说“UI 交给 Claude”,由 Codex 委派、Claude 实现,再交回 Review。
- 在 Claude 侧说“做完叫 Codex Review”,由 Claude 主动发起 Review;没有旧任务时会建立新的关联任务。
- 在 Claude 侧说“创建一个 Codex 会话”或“交接给 Codex 实现”,走本工具的 CLI 创建或交接流程。
这不要求每次点名 Skill。已明确建立的任务继续沿用原流程和授权,后续接口协商、回复和 Review 无需每轮重新询问。默认 Codex 是协调者,角色策略可配置。
默认创建策略:Claude Desktop Code 由用户手动新建一次,工具负责绑定、消息与唤醒;Codex 保留已验证的 CLI 创建后接入 Desktop。 两端 Skill 都不用 Computer Use 补齐创建步骤,GUI 预填不计为自动创建。
当前能力
0.1.5 增加独立的 Claude 入站配置命令:默认只检查或预览,用户明确确认后才可通过 --global --confirm 写入;保留其他设置并创建私有备份。install/setup 只读取策略,不自动改权限。
Codex 直接通过已保存的 UUID 链接交给 Desktop;首次未接管时只重开同一链接一次,不再创建另一条引导会话。创建输出明确区分 canSend 与后续动作;手动绑定了替代会话时结束旧请求。两端 Skill 禁止用 Computer Use 补救创建,并要求 Codex 提交不带 Co-Authored-By。
协作状态继续使用 ~/.collab/workspaces/<项目真实路径的 SHA-256>/,不默认写入项目目录,也不迁移项目里已有的 .collab。交接前需要的 commit 全部由 Codex 完成,Claude 不自行提交。
支持 Codex CLI 创建与就绪校验、真实 GUI 会话绑定、双向消息、静默 ACK、幂等键、回复链与任务消息预算、任务依赖、接口协商、Review 修订与完成、写入范围冲突检查、持久化发件箱和空闲投递器。两端共用全局 Skill;Claude 手动创建,默认命令不打开 GUI。
已实测两次 Codex GUI -> Claude GUI -> 原 Codex GUI 空闲唤醒的闭环。CLI 测试覆盖单条回执查询与独立进程的静默确认;自动检查、构建和测试见 docs/validation.md。
安装与接入
需要 Node.js 22+ 和对应桌面客户端。Codex 默认创建路径还需要已登录的 Codex CLI;Claude 本版使用已登录的 Desktop,不要求独立 CLI 登录。当前支持 macOS/Linux Unix socket,实机验证环境为 macOS;Windows 尚未实现。npm 包名为 @cottonc/codex-claude-collab。
源码开发:
npm ci
npm run check
node dist/cli.js setup --workspace /absolute/shared/project --dry-run
node dist/cli.js setup --workspace /absolute/shared/project从 npm registry 用 pnpm 安装:
pnpm add -g @cottonc/[email protected]
cc-collab --version
cc-collab install这些命令可由 GUI 中的 Agent 执行,用户无需用终端操作 Agent。
install(也可用 skill install 或 setup --global)默认注册同一个 Skill:
- Codex:
~/.agents/skills/codex-claude-collab/ - Claude:
~/.claude/skills/codex-claude-collab/,由标准安装器链接到共享目录
Claude 显式调用 /codex-claude-collab,Codex 可选择同名 Skill。共享项目按当前任务选择,不固定指向安装时目录。~/.config/cc-collab/cli.json 仅记录全局 CLI 命令;项目范围安装仍可用 setup --workspace /project。不改系统提示词、客户端权限或其他插件。旧会话若有缓存,需重新发现 Skill。详见 docs/setup.md。
状态统一保存在 home 下的 .collab,按项目真实路径隔离;同一个项目的两端共享状态,符号链接别名会解析到同一项目。cc-collab paths --workspace /project 可查看实际位置而不创建数据。--state-dir PATH 仍可指定其他目录;不会自动读取、移动或删除项目下的旧 .collab。
Claude 入站策略可用 cc-collab claude-inbound 只读检查。需要变更时,先用 cc-collab claude-inbound --value accept 预览;用户确认展示的全局改动后,才执行 cc-collab claude-inbound --value accept --global --confirm。缺少确认时不创建目录、不写设置。Skill 不得替用户自行确认;详见安装文档。
创建同伴会话
先复用已绑定会话。用户已请求创建或允许自动创建同伴时,可执行:
cc-collab create --workspace /absolute/shared/project --agent codex --as codex-main --key codex-main-v1
cc-collab wait --workspace /absolute/shared/project --request REQUEST_UUID --timeout 15000Codex 默认通过 CLI 创建一个仅回复固定标记、禁止使用工具的初始会话,退出 CLI,再直接打开该 UUID 的 Desktop 链接。只有确认同一个 UUID 由 GUI 持有且目录正确,才自动绑定为 ready、返回 canSend=true。未接管时最多重开同一链接一次;返回 wait_once 后,Agent 最多再执行一次有界 wait,仍未就绪就说明需要用户手动打开或创建并注册。不会用 Computer Use、模拟按键或 --via gui 补救,也不能把未注册端点的任务声称为已排队。
Claude 请在 Desktop Code 中手动选定共享项目,新建会话并发送一句消息,再由 Agent 发现并注册其精确 UUID。默认 create --agent claude 返回 manual_creation_required,不会打开 GUI。兼容保留的显式 --via gui 仅是预填助手,仍需用户提交与握手;它不是无界面自动创建,两端 Skill 都不会调用它或使用 GUI 自动化替代。
社区资料记录了 Desktop 内置 start_session(initiation=user_asked) 的直接启动路径,但它依赖已有 Desktop 会话和工具开关;本机尝试被原生入站策略扣留,尚未验证成功,不作为当前可靠能力。CLI 建立会话再 claude --desktop --resume UUID 则需要独立 CLI 登录,本机当前未登录。创建方式的调查见 docs/references.md。
不要求窗口持续前台显示。关键是会话在对应 Desktop 中可继续,并通过就绪检查。仅指定相同目录不会让任意 CLI 会话自动同步。查询、取消与恢复规则见 docs/setup.md。
异步回执
| 状态 | 意义 |
| --- | --- |
| pending | 尚未投递,例如 Codex GUI 正忙,等待空闲 |
| dispatching | 已被一个投递进程认领 |
| submitted | 原生入口已接受写入或启动请求,尚未证明 Agent 收到 |
| held | Claude 原生入站策略扣留 |
| acknowledged | 对方已显式 ACK 或返回关联回复 |
| rejected | 原生策略明确拒绝/丢弃 |
| failed | 明确未投递,发送者可主动重试 |
| unknown | 写入后失去确认,禁止自动重放 |
发送命令返回的是当时快照。询问最终是否送达时应查询:
cc-collab status --workspace /absolute/shared/project --message MESSAGE_UUID静默 ACK 只更新共享回执,不唤醒发送者,所以不会自动修改客户端先前的自然语言说明。Skill 要求汇报前读最新状态。ACK 表示接收,任务交付由 Review 状态机另行确认。
实现与边界
通信核心、原生 Adapter 和 CLI 分层,独立于 Skill。以后增加入口不影响当前工作流。
- 业务任务在已验证的桌面会话执行。Codex 创建时使用一次固定标记的 CLI 引导,随后退出并交给 Desktop;本版不使用 Claude headless 创建。
- 只使用本机文件、stdio 与原生 Unix socket;不监听 TCP,不配置代理、隧道、端口转发或远控服务。
- 只读消费客户端会话注册信息,不读取模型登录凭据或代理环境变量,不修改入站/审批/沙箱设置。
- 发送给 Claude 时,只按发送方 Codex 的原生当前权限快照声明权限类别;无法核实时不声明。不会按接收方模式猜测或固定声称 bypass,Claude 的 held/refused 策略仍生效。
- Codex 使用现有 GUI owner 定位和空闲状态;共享 daemon 真正加载该会话时使用官方 queue,否则走实验性 Desktop IPC。
- Claude 在原生私有 socket 目录创建短时回执 socket,结束后清理;不修改客户端注册或 key 文件。
- Desktop IPC 是非公开接口,升级可能失效。结果未知不自动重放,也不切换后台 Agent 冒充成功。
- 写入范围是协作约定和冲突检测,不是文件系统沙箱。每端仍遵守自身权限;同一个 OS 用户下的本地程序共享信任边界。
- 协作交接前需要的 commit 全部由 Codex 在用户已有授权范围执行,不添加共同作者署名;Claude 交接未提交改动与验证结果,不要求加署名。桥接工具不执行 Git 命令,push 仍需已有用户授权。
协议与恢复见 docs/protocol.md。项目为独立实现,不是 ocs Wrapper/Fork,也不依赖 ocs;来源见 docs/references.md。
