用量告警 hook —— Claude 用量阈值 macOS 通知

定位

在 5 小时 / 7 天用量窗口越过阈值时，发一条 macOS 通知，提醒你快到限额了。仅 macOS，需订阅账号（Pro/Max）。

这是一个 hook（挂在 Stop 事件），随 vft-kit 插件自动注册，不用你写 settings.json。但它需要跑一次 usage-alert-setup 把「用量数据管道」接上才会真正告警。

这是理解这个 hook 的关键：官方 hook 事件的 payload 里不含任何用量数据。整个 Claude Code 里，唯一能拿到 rate_limits（限额百分比、重置时间）的地方是 statusline。

所以这个 hook 不直接读用量，而是读一份由 statusline 落盘的快照文件。这就需要 claude-hud 这个状态栏插件开启快照写入：

// ~/.claude/plugins/claude-hud/config.json
{ "display": { "externalUsageWritePath": "/Users/<你>/.claude/usage-snapshot.json" } }

claude-hud 侧只要这个 path 非空就开始落盘（每 ~30s 节流写一次），无额外开关。hook 端读这个快照，越过阈值就弹通知。没配这条、或用的是 API key（按量付费，没有限额窗口）时，hook 静默退出，不影响会话。

装完 vft-kit 后跑一次 usage-alert-setup skill（对话里说「开通用量告警」「用量告警怎么设」「为什么用量告警不响」即可触发），或直接跑脚本：

bash ${CLAUDE_PLUGIN_ROOT}/skills/usage-alert-setup/scripts/setup.sh

它幂等（反复跑安全），做三件事：

装 jq（hook 本体和向导都需要）；
检测 claude-hud 是否安装（没装则引导安装，不自动装）；
往 claude-hud 的 config.json 写 display.externalUsageWritePath，指向 usage-alert.sh 默认读取的快照路径 ~/.claude/usage-snapshot.json（两者必须指同一文件才能联动）。

跑完注意：重启会话（claude-hud 才会重载 config、开始落盘）；仅 Pro/Max 有限额窗口才会告警，API key 账号快照为空、不告警（正常）。

setup 首次运行会在 ~/.claude/vft-kit/usage-alert-config.json 落一份填满默认值的模板（已存在则不覆盖），直接编辑，改后重启会话生效：

{
  "thresholds": [70, 75, 80, 85, 90, 95, 100],
  "sound": "Glass",
  "maxAgeSeconds": 600,
  "snapshotPath": "~/.claude/usage-snapshot.json"
}

thresholds：越过哪些百分比时告警。每档只在当前达到的最高档告警一次（避免 92% 同时触发 70 和 90 两条）。想少打扰就精简成 [80, 95]。
sound：macOS 系统音名（Hero / Basso / Glass / Ping…）。
maxAgeSeconds：快照超过这个秒数就视为过期、不告警（默认 600）。
snapshotPath：必须与 claude-hud 的 externalUsageWritePath 一致。

取值优先级：环境变量（CLAUDE_USAGE_THRESHOLDS / CLAUDE_USAGE_SNAPSHOT）> 配置文件 > 内建默认。env 用于临时覆盖，长期自定义改配置文件。

告警去重键含 resets_at（限额窗口的重置时间）：同阈值、同窗口只告警一次；窗口一翻新（重置时间变了），同阈值可再次告警。state 文件在 ~/.claude/usage-alert-state，不会无限增长（超过 50 行自动截断）。

跑几个 turn 后：

cat ~/.claude/usage-snapshot.json   # 应能看到 five_hour / seven_day 的 used_percentage

有数据即管道通了；越过阈值时会弹「Claude 用量告警」通知。