dores-codex

dores-codex 是一个只基于原生 Codex 官方 hooks 的插件包。
它不会替换 codex 命令本身，也不会走桥接层；它做的事情是：

• 把原生 Codex hooks 事件转成 websocket 消息
• 默认发送到 ws://127.0.0.1:8765
• 通过 codex-plugin-setup 把 hooks 安装到 ~/.codex/hooks.json
• 让你在任意目录启动原生 codex 时都能触发这套全局 hooks

支持的原生 Hooks

当前包只处理官方这 5 类 hooks：

• SessionStart
• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop

对应 websocket event_type 映射如下：

• SessionStart -> StartWork 或 ManualWorkRecovery
• UserPromptSubmit -> Statistics
• PreToolUse -> Statistics
• PostToolUse -> Statistics 或 AutoDebugError
• Stop -> EndWork

不再支持的旧能力：

• 桥接 bridge
• notify 驱动的 TaskComplete
• 自定义 wrapper codex
• HTTP 回调链路

1. 打包本地 npm 包

当前版本号是 4.0.0。

在项目根目录执行：

env npm_config_cache=/tmp/dores-codex-npm-cache npm pack

执行后会生成本地包：

dores-codex-4.0.0.tgz

2. 安装 npm 包

推荐全局安装。这样 setup 写入的 hooks 会稳定指向全局安装路径，后续你在任何目录执行原生 codex 都能触发。

如果你已经发布到 npm 仓库：

npm install -g [email protected]

如果你使用本地打包出来的 tgz：

npm install -g ./dores-codex-4.0.0.tgz

如果你只是临时测试，也可以本地安装：

npm install ./dores-codex-4.0.0.tgz

但本地安装不推荐长期使用，因为 hooks 会指向当前项目里的 node_modules/dores-codex，项目移动或删除后路径就会失效。

3. 执行 Setup

安装完包以后，不是直接执行 codex 就会生效。
你还需要先执行一次 setup，把 hooks 安装到 Codex 会读取的全局位置：

codex-plugin-setup

这个命令会做两件事：

1. 确保 ~/.codex/config.toml 里启用了：

[features]
codex_hooks = true

2. 把本插件管理的 hooks 写入：

~/.codex/hooks.json

写入的是带绝对路径的命令，所以 setup 完成后，你在任意目录执行原生 codex，都能加载这套全局 hooks。

如果你本来就有自己的 ~/.codex/hooks.json，codex-plugin-setup 会保留已有内容，只更新它自己管理的条目。
本插件管理的 hook 组会带有 dores-codex: 前缀，便于后续卸载和重装。

4. WebSocket 地址

默认 websocket 地址：

ws://127.0.0.1:8765

如果你的服务端不是这个地址，可以在启动 codex 之前覆盖：

export CODEX_PLUGIN_APP_WS_URL=ws://127.0.0.1:8765

如果你不设置，默认就会连 ws://127.0.0.1:8765。

5. 如何触发原生 Codex hooks

setup 完成后，直接启动原生 codex：

codex

然后在交互里输入内容，不同场景会触发不同 hooks。

场景 A：只测试会话开始和结束

输入：

1+1=?

通常会触发：

• SessionStart
• UserPromptSubmit
• Stop

因为这类问题通常不需要调用 Bash。

场景 B：测试 Bash 成功执行

输入：

Use Bash to run the command pwd exactly once, then reply with only the resulting directory path.

通常会触发：

• SessionStart
• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop

场景 C：测试 Bash 失败事件

输入：

Use Bash to run the command false exactly once, then reply with only the word failed.

通常会触发：

• SessionStart
• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop

其中 PostToolUse 会因为非零退出码映射成 AutoDebugError。

6. 如何判断 hooks 是否真的触发

可以看两个地方：

• 你的 websocket 服务端是否收到消息
• 本地日志文件是否有 hook 执行记录

默认日志路径在 setup 所安装的包目录运行时对应的：

<package-root>/runtime/codex-plugin.log

如果 websocket 没收到消息，先检查：

• codex-plugin-setup 是否执行过
• ~/.codex/config.toml 里是否真的启用了 codex_hooks = true
• ~/.codex/hooks.json 是否存在
• websocket 服务是否真的监听在 ws://127.0.0.1:8765
• 你运行的是原生 codex，不是别的 wrapper

7. 卸载

删除这套全局 hooks：

codex-plugin-uninstall

这个命令会从 ~/.codex/hooks.json 里移除本插件写入的 managed hooks。
它不会自动把 config.toml 里的 codex_hooks 改回去。

如果你还想彻底移除包：

npm uninstall -g dores-codex

8. 开发校验

如果你在源码仓库里改了代码，可以先校验：

npm run check

再重新打包：

env npm_config_cache=/tmp/dores-codex-npm-cache npm pack