Claude Usage Widget：macOS 桌面端 Claude 订阅额度与用量监视工具

Claude 订阅的 5 小时与每周额度仅在 claude.ai 的用量页呈现。Claude Usage Widget 是一个 macOS 原生桌面小组件（Swift / SwiftUI），将两类额度（已用百分比与重置倒计时）、按模型的每周额度、类似 GitHub 的每日使用热力图，以及本机 Claude Code 的 token 用量与估算费用常驻于桌面；四档尺寸的卡片大小、圆角与网格吸附均与系统小组件一致。最新发布版本为 v1.0.0（2026-10-13），以 MIT 协议开源：Yu-Xiang-Yang/claude-usage-widget。该项目为独立项目，与 Anthropic 无隶属关系，开发过程借助 Claude Code 完成。

1 背景与动机

使用 Claude Code 时，需要掌握当前所处的额度窗口：5 小时窗口剩余多少、每周额度已消耗多少、何时重置。获取这些信息存在三方面不便：

• 可见性：额度百分比与重置时间仅出现在用量页，读取需离开当前工作窗口；
• 数据来源分离：额度百分比由服务端计算，本机日志不含该信息；token 数与费用则只能由本机日志推得。两类数据须分别获取后合并显示；
• 历史不可回溯：Claude Code 会清理旧会话日志，仅依赖日志无法保留长期的使用趋势，需由组件自行保存每日汇总。

Claude Usage Widget 的目标是将上述数据合并为一张常驻桌面的卡片，并使其外观与交互遵循系统小组件的规范。

2 功能概述

图 1 特大尺寸（704 × 344 pt）界面（模拟数据，由 --demo 模式渲染，不对应真实账户）。左栏为 5 小时、每周及按模型（Fable）的每周额度，各附本机在该窗口内的 token 数与估算费用；右栏为每日 token 热力图（近 21 周活跃 107 天）、今日 / 近 7 日 / 近 30 日汇总、今日 token 构成与模型占比。

主要功能如下：

图 1 的模拟数据中，今日 token 总量为 214.0 M，其中缓存读取 203.5 M，占 95.1 %；输出 820.0 K，占 0.38 %。该构成说明 token 总数主要由缓存读取贡献。按源码价格表，Opus 5.5 的缓存读取单价为输入价的 5 %（0.20 / 4），因此 token 总数与估算费用不成比例，组件并列显示两者。

3 尺寸与界面

3.1 小组件尺寸

图 2 四档尺寸（模拟数据）。

图 3 大尺寸的浅色与深色外观（模拟数据）。

图 4 小尺寸（左）与中尺寸（右）（模拟数据）。

3.2 应用图标

图 5 应用图标（512 × 512 px）。

图标由 scripts/make-icon.swift 以几何图形绘制，不含第三方或品牌素材：深色圆角方块上，橙色圆环表示用量仪表，环内为四角星。图标显示于访达、启动台、Spotlight 与「登录项」列表。该图标在 main 分支中（Resources/AppIcon.icns，由 build.sh 写入应用包），更新日志将其记为 1.0.1 的新增项，尚未发布，因此 v1.0.0 发布包不含该图标。

4 系统架构

v1.0.0 的全部源码为 9 个 Swift 文件，共 2 389 行，由 build.sh 一并编译，不含 Swift Package 或 Xcode 工程。数据流如下：

Claude Code 日志（*.jsonl）─▶ UsageScanner（增量扫描 30 s，按消息去重）
                                   │
                                   └─▶ HistoryStore（每日汇总，history.json）─┐
                                                                              ├─▶ Snapshot ─▶ WidgetView（SwiftUI，四档尺寸）
claude.ai 用量接口 ─▶ QuotaFetcher（内嵌 WebKit，至多每分钟一次）─▶ QuotaInfo ─┘
                                                    └─ quota.json（重启后立即显示）

采集与展示以 Snapshot 为接口：日志扫描与额度读取各自在后台完成，合并后发布给视图层。额度读取失败不影响本机统计与热力图的更新。

5 本机用量统计

组件读取 Claude Code 的会话日志（~/.claude/projects/**/*.jsonl，以及 ~/.config/claude/projects 与 CLAUDE_CONFIG_DIR 指定的目录），累加每条助手消息的 usage 字段。

5.1 token 的定义

token 总数定义为输入、输出、缓存写入与缓存读取四项之和。缓存写入按 cache_creation 中的 5 分钟与 1 小时 TTL 分别记录；两项之和小于 cache_creation_input_tokens 时，差额计入 5 分钟 TTL。模型标识为 <synthetic> 的记录不计入。

5.2 流式消息的去重

同一条流式消息在日志中被多次写入，各条记录的输出 token 数随生成过程递增。组件以 message.id 与 requestId 的组合为键，对同一键仅保留输出 token 最大的一条（最终条目）。消息与请求标识均缺失时，退而使用记录的 uuid。实测表明，不去重时 token 总数约翻倍。

5.3 费用估算

费用按公布的 API 标价估算，价格表为源码中的 Pricing（Sources/UsageStore.swift），单位为美元 / 百万 token，按模型标识的最长前缀匹配；未匹配的模型按 claude-opus-5-5 的价格计。单条记录的费用为

$$ C = 10^{-6} \left( p_{\mathrm{in}} N_{\mathrm{in}} + p_{\mathrm{out}} N_{\mathrm{out}} + 1.25 \cdot p_{\mathrm{in}} N_{\mathrm{w5m}} + 2 \cdot p_{\mathrm{in}} N_{\mathrm{w1h}} + p_{\mathrm{cr}} N_{\mathrm{cr}} \right) $$

其中 $N_{\mathrm{in}}$、$N_{\mathrm{out}}$、$N_{\mathrm{w5m}}$、$N_{\mathrm{w1h}}$、$N_{\mathrm{cr}}$ 依次为输入、输出、5 分钟缓存写入、1 小时缓存写入与缓存读取的 token 数，$p_{\mathrm{in}}$、$p_{\mathrm{out}}$、$p_{\mathrm{cr}}$ 为对应的输入价、输出价与缓存读取价。缓存写入按输入价的 1.25 倍（5 分钟 TTL）或 2 倍（1 小时 TTL）计。订阅套餐不按 token 计费，该数值仅用于横向比较；价格表需在价格变动时手动更新。

5.4 扫描开销

日志每 30 s 增量扫描一次；700 MB 日志的首次全量扫描约需 2 s。统计范围仅限本机的 Claude Code，claude.ai 网页端对话与其他设备的用量不在其中。

5.5 热力图

热力图每日一格，以周一为每周首日，度量为 tokens 或消息数。色阶共 5 级：无使用记录的日期为最浅一级，其余 4 级的分界取活跃日的 25 %、50 % 与 75 % 分位数。每日汇总保存于 history.json，Claude Code 清理旧会话日志后，已记录的历史仍保留。

6 订阅额度的读取

额度百分比由服务端计算，本机日志不含该信息。组件因此采用与 claude.ai 用量页相同的数据，读取流程如下：

1. 登录窗口为内嵌的 WebKit 视图，登录态保存于组件自身的 WebKit 数据存储；
2. 组件至多每分钟在该存储中加载一次 /api/organizations/<组织>/usage。响应中的 limits 列表含 session（5 小时）、weekly_all 与 weekly_scoped（按模型）三类窗口，均含百分比与重置时间；旧字段 five_hour、seven_day 作为后备；
3. 解析结果缓存于 quota.json，重启后立即显示。

该接口并非公开 API。接口变更或登录失效时，组件回退为按本地日志估算的 5 小时窗口，并显示原因，不显示虚构的百分比。

6.1 登录窗口中的通行密钥问题

本地构建的应用不具备浏览器类应用的通行密钥（passkey）授权。登录页面检测到 WebAuthn 可用时会优先提供通行密钥，随后流程停滞。组件在登录窗口中于文档加载前注入脚本，处理方式如下：

屏蔽后，Google 与 claude.ai 改用密码、设备确认或邮箱验证码。Google 与 Apple 登录在弹出窗口中进行，登录窗口已启用脚本打开窗口的能力。邮件中的登录链接会在默认浏览器中打开，登录态不会进入组件，应使用验证码。

6.2 凭据与网络范围

• 组件不读取、复制或传输密码、Cookie 与令牌，仅读取用量接口的响应；
• 唯一的网络目标为 claude.ai；
• 右键菜单的「清除登录状态」删除 WebKit 数据、已保存的组织标识与 quota.json。

由于接口未公开，其使用应事先核对 Anthropic 的服务条款。

6.3 存储的文件

7 系统小组件几何的复现

系统小组件是 WidgetKit 扩展，须以开发者证书签名，构建它需要完整 Xcode。本项目不使用 WidgetKit，组件因此是独立的无边框面板，不出现在系统小组件库中；其几何参数取自 macOS 26 上系统小组件的实测值，测量通过窗口列表完成。

上述卡片边长满足 $180n - 16$（$n$ 为占用的网格数）：$n = 1, 2$ 时分别为 164 与 344 pt。特大尺寸按同一网格推算，宽度取 $n = 4$，得 704 pt，高度取 $n = 2$，得 344 pt；该尺寸未经实测。

窗口行为如下：

• 吸附：拖动时向屏幕边距、屏幕中线与 180 pt 网格线吸附，阈值为 14 pt，并始终保持在屏幕内；启动与切换尺寸后同样落到网格上；
• 层级：面板位于桌面图标之上、普通窗口之下，所有空间可见，最大化窗口会将其遮挡，可启用「窗口置顶」改变该行为；
• 阴影：不绘制投影，与桌面上的系统小组件一致。

8 安装与使用

8.1 安装

方式一：发布包（推荐）。 在最新发布页下载 ClaudeUsageWidget-<版本>-macos.zip（通用二进制，支持 Apple 芯片与 Intel，需 macOS 14 及以上），解压后将 ClaudeUsageWidget.app 移入 /Applications。应用采用临时签名且未经公证，首次启动会被系统拦截，执行一次下列命令移除隔离标记：

xattr -dr com.apple.quarantine /Applications/ClaudeUsageWidget.app

也可在「系统设置 → 隐私与安全性」中选择「仍要打开」。发布页附有 SHA256SUMS.txt，可校验下载文件。

方式二：源码构建。 仅需 Xcode 命令行工具（xcode-select --install），无需完整 Xcode：

git clone https://github.com/Yu-Xiang-Yang/claude-usage-widget.git
cd claude-usage-widget
./build.sh install          # 构建并安装到 /Applications（无写入权限时安装到 ~/Applications）
open /Applications/ClaudeUsageWidget.app

单独执行 ./build.sh 仅生成 build/ClaudeUsageWidget.app。命令行工具的默认 SDK 版本可能高于已安装的编译器（报错 this SDK is not supported by the compiler），脚本因此在存在 macOS 26 SDK 时优先使用它。

8.2 首次使用

1. 右键小组件，选择「登录 claude.ai…」，在弹出的窗口中登录；读取到额度后窗口自动关闭。
2. 可在同一菜单中启用「登录时启动」；移动应用位置后需重新启用。

未登录时，组件显示按本地日志估算的 5 小时窗口与「登录」按钮；热力图与本机统计不依赖登录。额度需要 Claude Pro 或 Max 订阅及 claude.ai 登录；本机统计与热力图需要 Claude Code。

8.3 命令行模式

9 构建、验证与发布

项目暂无测试套件，验证依赖命令行模式：

持续集成包含两个 GitHub Actions 工作流，均运行于 macos-26 镜像（Liquid Glass 材质需要 macOS 26 SDK）：

10 设计取舍

11 局限与注意事项

• 本机统计仅覆盖本机的 Claude Code，不含 claude.ai 网页端对话与其他设备的用量；
• 订阅额度依赖未公开的网页接口与有效的登录态，接口可能变更或失效；
• 特大尺寸由系统网格推算，未经实测；
• 菜单栏空间不足时（如刘海屏），系统可能隐藏菜单栏图标，全部功能仍可从小组件的右键菜单使用；
• 价格变动时需手动更新价格表；
• 小组件不出现在系统小组件库中，最大化窗口会将其遮挡（可启用「窗口置顶」）。

12 声明与项目地址

本项目为独立项目，与 Anthropic 无隶属、认可或赞助关系；“Claude” 为 Anthropic 的商标。项目借助 Claude Code 开发。

GitHub：https://github.com/Yu-Xiang-Yang/claude-usage-widget（MIT 协议，含中英文 README、更新日志与安全策略）。