nikitadoudikov/claude-pulse

# Claude Code 的 Pulse [](https://www.npmjs.com/package/pulse-for-claude-code) [](https://github.com/nikitadoudikov/claude-pulse/stargazers) [](LICENSE) [](package.json) **Claude Code，带脉动。** 一个本地仪表盘，监视您机器上的每一个 Claude Code（以及 Codex）会话，给它一个字面意义上的心跳，并允许您从手机或 MacBook 刘海下方的长条中批准其工具调用。零依赖。数据不会离开您的机器。 受 [XDA Developers](https://www.xda-developers.com/stopped-wasting-claude-tokens-after-installing-open-source-dashboard/) 报道：“任何使用 Claude 工作的人的必备工具。”  ## 脉动 *45 bpm。Claude 正在休息。* 心率是真实的：过去两分钟内的工具调用和生成的 token 将其从静息状态下的约 45 bpm 提升至 Claude 忙于代码重构时的约 185 bpm。当您达到使用限制时，心率会变平。它会在每个屏幕的 topbar 和刘海中跳动：  ## 刘海  *一个始终置顶的本地长条，位于您的摄像头刘海下方：状态、今日数据、上下文进度条、消耗速率以及可用的批准按钮。鼠标悬停时，它会展开为一个包含所有实时会话的菜单。右键点击可将其关闭。* `claude-pulse notch`（或仪表盘中的 ▂ 按钮）会一次性编译一个约 100 行的 Swift 覆盖层，并将其固定在每个应用和每个 Space 之上。没有 Electron，也没有框架。整个界面就是一个 NSPanel 和一个 WKWebView。 ## 办公室  *Claude 坐在纽约的办公桌前，替您完成工作，而您就像一位仁慈的管理者一样在一旁观看。*  *也在运行 Codex？它的仪表盘是一个独立的单色世界，同一栋楼，不同的楼层。数据会正确分离：Codex 仪表盘显示 Codex 的数据，Claude 的则显示 Claude 的。* *工作时听音乐：粘贴任何 YouTube 链接，或者点一下播放 lofi / synthwave / jazz。* ## 个人资料  *等级、连续记录、历史最佳成绩以及一面成就墙，完全根据您的本地日志计算得出。是的，这里有一个“一天内消耗 1 亿 token”的成就。不，我们并不为它是怎么挣来的感到自豪。*  *一个 GitHub 风格的活动热力图：点击任意方块，当天的情况就会在毛玻璃效果上方大面积展开，并用通俗易懂的语言总结您何时开始、何时停止，以及 token 都去哪儿了。* ## 限制  *“我还剩多少额度”的真实版本：以您真实的实际上限（根据您上次触发限制的情况推算出来）来衡量，并显示消耗速率和距离用尽的剩余时间。Anthropic 并未公开限制标准；Pulse 也不会假装知道它们。* ## 为什么您可能需要它 - **随时随地批准。** 手机推送带有可用的 `Allow` / `Allow all` / `Deny` 按钮。无需设置 Wi-Fi，无需 IP，适用于蜂窝网络。批准卡片会显示实际的命令或 diff，并且每个会话都有一个 **auto mode**，适合长时间的无人值守运行。 - **安排消息。** 限制在 10:00 重置？打开会话，输入时间和“continue”，然后离开即可。Pulse 会在 10:00 以无头模式恢复运行，并将结果链接发给您。 - **永不丢失会话。** 一个命令即可将您的上一个会话恢复为可读的对话记录；自动快照意味着崩溃永远不会让您丢失上下文。 - **查看开销。** 按小时、天、周、模型和项目统计 token 及等效 API 成本，并根据您设置的预算进行衡量，当超出预算时会在手机上收到提醒。 - **您的本周回顾。** 一张可分享的 Spotify Wrapped 风格的本周总结卡片，在本地生成 PNG。 - **自定义声音。** `claude-pulse gen-sounds` 使用 ElevenLabs 生成四种 UI 声音（done、attention、error、sent），每种声音各司其职。 - **多台机器。** 将 `extraRoots` 指向另一台主机的 rsync 镜像，即可获得一个统一的仪表盘。 - **搜索一切。** 对磁盘上的每个会话进行全文搜索，只需点击一下即可跳转至对话记录。 - **本地且私密。** 只读访问 `~/.claude`，在 `127.0.0.1` 上提供服务，零依赖，无遥测。 ## 快速开始 需要 Node 18+。无需安装即可运行： ``` npx pulse-for-claude-code ``` 或者全局安装，这会将 `claude-pulse` 命令添加到您的 PATH 中： ``` npm install -g pulse-for-claude-code claude-pulse ``` 或者克隆代码库： ``` git clone https://github.com/nikitadoudikov/claude-pulse.git cd claude-pulse node bin/cli.js ``` 无论哪种方式，它都会打开 `http://127.0.0.1:4317`。要获取桌面和手机 通知以及批准工具调用，请配置 hooks（一个命令，可安全地 重复执行）： ``` claude-pulse install-hooks # adds the hooks to ~/.claude/settings.json ``` 本 README 中的每个 `claude-pulse ` 都假定您使用的是全局安装。如果 您使用 `npx`，则命令为 `npx pulse-for-claude-code `， 例如 `npx pulse-for-claude-code install-hooks`。如果是通过克隆代码库安装的，则 命令为 `node bin/cli.js `。 然后重启 Claude Code，您就大功告成了。其他选项： ``` claude-pulse --port 4317 # change the port claude-pulse --no-open # do not open the browser ``` ## 保持运行 在前台运行意味着当您关闭该终端时，Pulse 也会停止。为了让它 独立存活，请在后台运行它： ``` claude-pulse start # run detached, survives closing the terminal claude-pulse status # is it running? claude-pulse stop # stop it claude-pulse restart # stop and start again ``` 如果您的终端崩溃了，`claude-pulse start` 可以用一个命令将其恢复， 而且后台实例在第一时间根本不受崩溃的影响。 在 macOS 上，您可以将 Pulse 交给系统管理，这样它就会在登录时启动，并且 在发生意外停止时自动重启： ``` claude-pulse install-service # start at login, auto-restart claude-pulse uninstall-service # remove it ``` ## 恢复丢失的会话 终端崩溃了，笔记本电脑死机了，或者触发了会话限制？什么都不会 丢失：Claude Code 会在运行时将每个会话实时写入磁盘。一个命令即可 找回上一个会话，打印回顾摘要并保存可读的对话记录： ``` claude-pulse recover # the most recent session claude-pulse recover 2 # the one before that claude-pulse recover # a specific session ``` 它会在 `~/.claude-pulse/exports/` 下保存一个轻量级的 markdown 文件（15 MB 的日志 会变成约 180 KB 的文件），并打印一个链接，以便您在浏览器 或手机上阅读完整的对话记录。您也可以在仪表盘中打开任意会话，并使用 **open transcript** / **download .md**。 在 Pulse 运行期间，它还会将最近活动的每个会话**自动快照**到 `~/.claude-pulse/exports/snapshots/`（每个会话一个文件，仅在内容发生 变化时重写）。因此，即使您从未运行过 `recover`，最新状态也始终保存在磁盘上。在 `~/.claude-pulse.json` 中将 `snapshotMinutes` 设置为 `0` 可关闭此功能。 要一次性备份所有内容，`claude-pulse export-all` 会将每个会话 写入单个经过 gzip 压缩的小型 markdown 文件中，或者使用 Sessions（会话）屏幕上的 **download all history**。 ## 搜索每个会话 忘记了在哪里做过某事？**Sessions**（会话）屏幕有一个搜索框，可以 扫描磁盘上的每个会话以查找某个单词或短语，并直接将您 带到对话记录中。它在您的手机上也同样有效。 ## 在您的手机上 最简单的手机控制方式就是 ntfy 通知本身：它带有可用的 `Allow` / `Allow all` / `Deny` 按钮（如上所述），完全不需要网络设置。 要获得更丰富的视图，可以在连接到同一 Wi-Fi 的情况下，在手机上打开 `http://:4317/phone`（需要设置 `bindLan: true`），以查看 Claude 当前正在做什么，以及一个 **Pause / Resume** 按钮。点击暂停会阻止 Claude 运行更多工具，直到您 恢复它。两者都需要配置 `PreToolUse` hook。 ## 工作原理 ``` ┌──────────────┐ writes .jsonl ┌──────────────────────┐ SSE ┌──────────────┐ │ Claude Code │ ─────────────────▶ │ Pulse (read only) │ ───────▶ │ dashboard │ │ (terminal) │ │ 127.0.0.1:4317 │ │ + phone │ └──────┬───────┘ └──────────────────────┘ └──────────────┘ │ │ hooks: Notification · Stop · PreToolUse ▼ ┌─────────────────────────────┐ │ ~/.claude-pulse/ │ pending approvals · decisions · events └─────────────────────────────┘ ``` Claude Code 将每个会话以 JSONL 格式记录在 `~/.claude/projects/` 下。每条 assistant（助手） 消息都带有一个 `usage` 区块（包含输入、输出和缓存 token）以及时间戳。 Pulse 读取这些文件（只读模式），根据修改时间缓存每个文件，因此 未更改的会话永远不会被重新解析，并对数据进行汇总。浏览器 通过 Server-Sent Events 接收实时更新。三个小型 hooks 让 Claude Code 能够在 需要您时、一轮对话结束时以及想要运行工具时通知 Pulse。 ## Claude 需要您时的通知 Claude Code 可以在需要引起您注意时运行 hook。将其 `Notification` 事件指向内置的脚本，Pulse 就会显示横幅并发送桌面 通知，即使标签页在后台运行。 最简单的方法是使用一个命令： ``` claude-pulse install-hooks # wires the hooks into ~/.claude/settings.json (safe to re-run) claude-pulse uninstall-hooks # removes them ``` 它会备份一次您的设置，与您已有的任何 hooks 合并，并且 绝不会添加重复项。之后重启 Claude Code。如果您想手动完成，请将 以下内容添加到 `~/.claude/settings.json` 中（使用您克隆代码库的绝对路径）： ``` { "hooks": { "Notification": [ { "matcher": "", "hooks": [ { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/notify-hook.js" } ] } ], "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/stop-hook.js" } ] } ], "PreToolUse": [ { "matcher": "", "hooks": [ { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/permission-hook.js" } ] } ] } } ``` 保持 `claude-pulse` 运行，您就设置好了。 ## 从仪表盘（和您的手机）批准工具 配置好 `PreToolUse` hook 后，当 Claude 想要运行需要 权限的内容时，Pulse 中会出现一张带有 `Allow`、`Allow all` 和 `Deny` 的批准卡片。`Allow all` 会在剩余的运行过程中停止再次询问。 此功能的设计初衷是绝不卡住 Claude。只读工具直接放行，如果 Pulse 未运行，在批准超时时间内（默认为 60 秒，可通过 `approvalTimeoutMs` 设置）未收到您的回复， 或者遇到任何错误，它都会回退到正常的 终端提示。如果您忽略它，也不会破坏任何东西。手机推送带有 `Allow`、 `Allow all` 和 `Deny` 按钮。 要从手机上进行批准，您只需要一个 `ntfyTopic`（见下文）和 ntfy 应用。推送通知带有 `Allow`、`Allow all` 和 `Deny` 按钮， 点击其中一个即可通过 ntfy 将回复发送回 Pulse 监听的私有回复 topic。无需同一 Wi-Fi，无需 IP，无需开放端口：它可以在任何地方 工作，甚至在蜂窝网络下。Pulse 仅在确实正在等待 该请求时才会对回复采取行动，因此过期的通知无法进行任何操作。 ``` Claude wants to run a tool │ ▼ PreToolUse hook ──▶ Pulse ──push──▶ phone notification │ │ │ tap "Allow" │ │ │ answer returns over ntfy │ │ ▼ ▼ hook is still waiting ◀── decision ◀── Pulse (subscribed to the reply topic) │ ▼ hook returns "allow" ──▶ Claude runs the tool ``` ## 手机推送（可选） 要在 Claude 需要您或完成任务时在手机上获取推送，请选择一个难以 猜测的 topic 名称，安装免费的 [ntfy](https://ntfy.sh) 应用并订阅 该 topic，然后在 `~/.claude-pulse.json` 中进行设置： ``` { "ntfyTopic": "claude-pulse-9f3a7c" } ``` 配置好上述 hooks 后，`Notification` hook 会在 Claude 等待 您时发送推送，而 `Stop` hook 会在一轮对话完成时发送推送（设置 了 30 秒的防抖处理，因此来回对话不会对您造成信息轰炸）。任何知道该 topic 的人都可以读取它，因此请使用 随机名称。 如果您设置了 `budgets`（见下文），当滚动窗口的使用量达到预算的 80% 和 100% 时，Pulse 也会发送推送，因此您可以从口袋里掏出手机获知，而 不必反复查看。 ### 保留的 topic、访问 token 和自托管的 ntfy 在纯粹的公共 ntfy.sh 上，topic 名称就是整个安全边界。为了消除 这一隐患，请保留该 topic（ntfy Supporter 等级或自托管服务器的 ACL），以同样的方式保留 `-reply`，生成一个访问 token并进行设置： ``` { "ntfyTopic": "claude-pulse-9f3a7c", "ntfyServer": "https://ntfy.sh", "ntfyToken": "tk_..." } ``` 设置 `ntfyToken` 后，每次发布和回复 topic 订阅都会发送 `Authorization: Bearer `，并且 Allow / Allow all / Deny 按钮会在其 操作定义中携带相同的标头（ntfy 应用本身不会将您的 账户凭据附加到 `http` 操作上，因此对保留的回复 topic 的回复 需要它）。请注意，该 token 因此被嵌入到了通知 负载中；在仅限订阅者的保留 topic 上，能够看到它的唯一 方就是您自己的设备和签发它的 ntfy 服务器。`ntfyServer` 也 接受自托管的基础 URL，例如 `https://ntfy.example.com`。 ### 每个 hook 的推送开关 如果另一个工具已经推送了其中某些事件（或者您只想要批准 推送），您可以在不取消设置 topic 的情况下关闭各个 hook 的推送： ``` { "ntfyPushApproval": true, "ntfyPushNotification": false, "ntfyPushStop": false } ``` 这三个选项默认均为 `true`。它们仅控制手机推送；桌面 通知和仪表盘的事件流不受影响。 ## 在一个仪表盘中管理多台机器 ``` { "extraRoots": [ { "label": "buildbox", "claudeProjects": "/srv/mirrors/buildbox/claude-projects", "codexSessions": "/srv/mirrors/buildbox/codex-sessions" } ] } ``` 每个条目的这两个目录键都是可选的。来自额外 root 的会话会在 Sessions（会话）列表和搜索 结果中显示带有该 root 名称的绿色标签芯片，并计入所有 总计。`CLAUDE_PULSE_EXTRA_ROOTS` 环境变量（相同的 JSON 数组）会覆盖配置条目。 ## 配置 将 `config.example.json` 复制到 `~/.claude-pulse.json` 并进行编辑。所有字段均为可选。 ``` { "plan": "max20", "contextLimit": 200000, "idleMinutes": 10, "approvalTimeoutMs": 60000, "budgets": { "fiveHour": 140, "day": 360, "week": 1100 } } ``` ### 关于限制 Anthropic 并未公布确切的订阅限制，它们是基于使用情况的， 而不是固定的 token 数量。Pulse 无法读取您真实的计划上限，因此 上述预算只是粗略的 API 等效估算值，您可以根据实际 观察到的结果进行调整。`pro`、`max5` 和 `max20` 预设只是起始参考点，并非官方 数据。Token 成本是根据公开的 API 列表价格估算的，纯粹作为使用情况的 代理指标；订阅用户无需按 token 付费。 ## 安全与隐私 Pulse 是本地优先且可选择开启的。在默认状态下，它仅绑定到 `127.0.0.1`， 不进行任何外部调用，零依赖（没有供应链风险），并且只读 访问 `~/.claude`。任何数据都不会离开您的机器，也没有分析追踪。有两个 可选功能改变了这一点，但在您开启之前，它们都是关闭的： - **手机推送 (`ntfyTopic`)** 通过公共 [ntfy.sh](https://ntfy.sh) 中继进行路由。批准提示（包含简短的命令 摘要）和您的点击操作都会通过您指定的 topic 传递，因此任何获知该 topic 的人都可以读取这些提示并进行回复。请使用较长的随机 topic，如果您需要更强的安全 保障，请自托管 ntfy 或使用 ntfy 访问 token。Pulse 仅在确实正在等待该确切请求时 才会对回复采取行动，因此过期或被猜到的消息本身无法 批准任何操作。 - **局域网访问 (`bindLan`)** 将服务器绑定到您的整个网络，以便连接到同一 Wi-Fi 的手机可以 打开实时的 `/phone` 页面。在此功能开启期间，该网络上的其他设备 也可以读取仪表盘和您的对话记录，因此请仅在您信任的 网络上启用它。您在手机端批准时不需要它（这部分 通过 ntfy 进行），因此大多数人应该将其保持关闭。 运行时状态、设备 token 和您的配置都存放在您的主目录下的 `~/.claude-pulse/` 中，并且永远不会被提交或发送到任何地方。 ## 许可证 MIT

标签：Claude Code, GNU通用公共许可证, MITM代理, Node.js, SOC Prime, 仪表盘, 开发工具, 监控, 自定义脚本