Rudder

# Rudder **Rudder 记录您给 AI 编程助手的所有提示，并将一天的工作内容总结成可读的报告。** Rudder 是一个用于理解 AI 辅助编程过程的工具。AI 编程工具可以快速生成、编辑、审查和部署代码，但同时也使得工作成果难以追踪。您可能会花费数小时提示、阅读、接受、拒绝、重写、测试和调整工具，但并不觉得自己真正产生了最终的代码输出。 Rudder 的目标是为 AI 辅助编程过程提供真实的记录，让开发者了解自己的决策、改进工作流程，并构建更好的软件。 它在 **Claude Code** 和 **Codex** 中安装轻量级钩子，静默记录发送给这些工具的每个提示，并存储在本地 SQLite 数据库中。 ## 快速入门 ```bash npm install -g @vivekyy/rudder # 将 `rudder` 添加到您的 PATH 中 rudder init # 创建数据库并安装钩子 ``` 然后像平常一样使用 Claude Code 和/或 Codex —— 每个提示都会自动记录。您可以在任何时候查看自己的工作成果： ```bash rudder start # 实时仪表盘：纠正率 + 分类明细，实时更新 rudder stats # 打印到终端的相同数据 rudder digest # 将一天的提示总结成可读的 Markdown 报告，写入 ./digest.md ``` 需要 Node.js ≥ 23.6 和 `claude` 或 `codex` 中的至少一个在您的 PATH 中。详见 [安装](#安装) 和 [命令](#命令)。 ## 为什么 Rudder 源于一个简单的问题：当我使用 AI 编程时，我感觉自己什么都没做，只是看着代理为我编写代码。 最终的差异只能告诉故事的一部分。它不能显示我如何到达那里，我在哪里改变了方向，我信任了什么，我重写了什么，或我测试了什么。 Rudder 的存在就是为了让这条路径可见。 重要的問題不是“AI 是否编写了这段代码？”，而是“人类做了什么？” ## 工作原理 ``` ┌──────────────┐ 用户提示提交钩子 ┌─────────────────┐ │ Claude Code │ ────────────────────────▶ │ │ └──────────────┘ │ ~/.rudder/ │ ┌──────────────┐ 通知程序 │ rudder.db │ │ Codex │ ────────────────────────▶ │ (SQLite) │ └──────────────┘ └────────┬────────┘ │ rudder digest ▼ 读取当天的提示， 通过 `claude -p`（或 `codex exec`）处理， 并写入 ./digest.md ``` - **仅限本地。** 所有数据都存储在 `~/.rudder/rudder.db` 中。不会上传任何数据；摘要由您已经使用的 LLM CLI 生成。您的数据归您所有。 - **非侵入式。** 钩子是故障安全的 —— 如果 rudder 发生错误，它会记录到 stderr 并退出，状态码为 0，因此它不会阻塞或破坏 Claude Code 或 Codex。 ## 要求 - **Node.js ≥ 23.6** - **Claude Code** (`claude`) 和/或 **Codex** (`codex`) 在您的 PATH 中。您只需要其中一个；rudder 记录已安装的工具，并使用可用的工具生成摘要。 ## 安装 ```bash npm install -g @vivekyy/rudder # 将 `rudder` 添加到您的 PATH 中 rudder init # 创建数据库并安装钩子 ``` `rudder init`： 1. 创建 `~/.rudder/rudder.db`。 2. 在 `~/.claude/settings.json` 中添加 `UserPromptSubmit` 钩子。 3. 在 `~/.codex/config.toml` 中添加顶级 `notify` 程序。 现有的配置文件在修改前会备份到 `*.rudder-bak`，并且该命令是幂等的 —— 运行两次不会重复安装钩子。 ### 从源码安装 ```bash git clone https://github.com/Vivekyy/Rudder.git rudder && cd rudder npm install # 安装依赖 npm run build # 编译到 dist/（npm link 的 `rudder` 二进制文件指向此处） npm link # 将 `rudder` 添加到您的 PATH 中 rudder init ``` > 如果您不想使用 `npm link`，可以直接使用 `node /path/to/rudder/bin/rudder.ts <command>` 运行 rudder。`rudder init` 始终将钩子连接到绝对路径，因此无论您的 PATH 如何变化，它们都能正常工作。 ## 升级 ```bash npm update -g @vivekyy/rudder # 或：npm install -g @vivekyy/rudder@latest ``` 钩子指向全局安装的绝对路径，在升级过程中保持稳定，因此无需重新连接。仅在升级说明中提到钩子格式更改时，才需要重新运行 `rudder init`（它是幂等的，安全）。如果您从源码安装，请使用 `git pull && npm install` 升级 —— `npm link` 符号链接会获取新代码，无需重建。 ## 命令 | 命令 | 描述 | | --- | --- | | `rudder init` | 创建数据库并安装 Claude Code + Codex 钩子。 | | `rudder start [选项]` | 打开实时仪表盘应用；实时更新。 | | `rudder stats [选项]` | 打印当天的纠正率和分类明细。 | | `rudder digest [选项]` | 将一天的提示总结成 Markdown 摘要。 | | `rudder tag [选项]` | 分类未标记的提示并打印当天的统计数据。 | | `rudder help` | 显示用法。 | | `rudder hook claude` | *(内部)* 记录 Claude Code 提示 —— 由钩子调用。 | | `rudder hook codex` | *(内部)* 记录 Codex 回应 —— 由 `notify` 调用。 | ### `rudder start` 启动一个小型本地服务器（在 `127.0.0.1` 上，端口 `41789` — 可以使用 `RUDDER_PORT` 重写）。在运行时，每个新提示都会由您的 `claude`/`codex` CLI 进行分类，仪表盘会实时更新您的纠正率和当天的分类明细。 仪表盘是一个**独立应用**（渐进式网页应用）： - **第一次**运行 `rudder start` 时，会打开一个小型安装程序页面 —— 点击 **安装应用**（或在 Safari 中，`文件 → 添加到 Dock`）将 rudder 添加到您的 Dock 中，其图标独立且无浏览器边框。已安装的窗口会自动调整到其内容大小。 - **之后**，`rudder start` 会直接启动应用（无浏览器标签页）。应用从正在运行的守护进程加载，因此请保持 `rudder start` 运行。 如果您不想安装任何内容，可以在浏览器中打开 `http://127.0.0.1:41789/`。 ### `rudder stats` 打印与仪表盘相同的数据，但输出到命令行： ``` $ rudder stats rudder — 2026-06-18 26 个提示 · 3 个 git 杂项跳过 · 23 个计数 您 12% 的时间拒绝了 AI（3 次拒绝，25 次是/否反应） 架构 30% █████░░░░░░░░░░░ 7 调整 17% ███░░░░░░░░░░░░░ 4 修复 9% █░░░░░░░░░░░░░░░ 2 维护 43% ███████░░░░░░░░░ 10 ``` 它会先分类任何尚未标记的提示（传递 `--no-tag` 可以立即读取已分类的内容，传递 `--date YYYY-MM-DD` 可以读取另一天的数据）。 | 选项 | 默认值 | 描述 | | --- | --- | --- | | `--agent claude\|codex` | `claude`，否则 `codex` | 哪个 LLM 分类提示。 | | `--no-tag` | 关闭 | 仅显示已分类的提示；跳过标记过程。 | | `--date YYYY-MM-DD` | 今天（本地时间） | 要报告的日期。 | 可以安全地让它运行，也可以安全地运行两次（第二次 `rudder start` 只会重新打开窗口）。无需守护进程运行，摘要仍然有效 —— 如果守护进程未运行，提示会在下次运行 `rudder start`、`rudder tag` 或 `rudder digest` 时被分类。 ### `rudder digest` | 选项 | 默认值 | 描述 | | --- | --- | --- | | `--date YYYY-MM-DD` | 今天（本地时间） | 要总结的日期。 | | `--agent claude\|codex` | `claude`，否则 `codex` | 哪个 LLM CLI 生成摘要。 | | `--out PATH` | `./digest.md` | 写入摘要的路径。 | 示例： ```bash rudder digest # 今天 → ./digest.md rudder digest --date 2026-06-16 # 特定日期 rudder digest --agent codex --out ~/digests/today.md ``` 摘要生成一个总结（您的“拒绝 AI”比率）；架构、调整、修复和维护的明细（每个明细的提示份额和您执行的主要操作）；亮点；和未完成的线程。百分比根据 rudder 存储的每个提示的标记计算（见下文），因此它们与 `rudder start` 仪表盘完全匹配 —— LLM 只会编写周围的文本。 ## 数据和隐私 所有提示都以明文存储在 `~/.rudder/rudder.db` 中（模式：时间戳，当地日期，来源，会话 ID，工作目录，项目，提示文本，模型和原始钩子有效载荷）。配套的 `prompt_tags` 表存储每个提示的计算类别和反应（仪表盘和摘要统计的数据）。分类使用与摘要相同的本地 `claude`/`codex` CLI —— 任何地方都不会发送数据。要删除所有内容，请删除 `~/.rudder/`。要停止记录，请从 `~/.claude/settings.json` 中删除钩子，并从 `~/.codex/config.toml` 中删除 `notify` 行。 设置 `RUDDER_HOME` 以覆盖存储位置（用于测试套件）。钩子会遵守 `RUDDER_DISABLE` —— rudder 在为 `rudder digest` 启动的代理上设置它，因此摘要的提示永远不会被记录。 ## 卸载 1. 从 `~/.claude/settings.json` 中删除 `UserPromptSubmit` 条目。 2. 从 `~/.codex/config.toml` 中删除 `notify = [...]` 行。 3. `rm -rf ~/.rudder`。 ## 开发 ```bash npm install npm run typecheck # tsc --noEmit npm test # node --test npm run build # 编译到 dist/（发布到 npm 的代码） ``` 源码位于 `src/`，CLI 入口点位于 `bin/rudder.ts`。在开发过程中，这些 `.ts` 文件可以直接通过 Node 的原生类型剥离运行；`npm run build` 将它们编译到 `dist/`，这是发布到 npm 的代码，也是已安装的 `rudder` 二进制文件运行的代码。