English · 中文
Windows 桌面常驻置顶悬浮窗，用进度条实时显示 Claude Code 的 5 小时 与 7 天滚动窗口用量占比，每隔 N 秒自动刷新。限额自动校准、半透明可调、可拖动、不占任务栏。
● Claude 23:45 更新
5h ▓▓▓▓▓░░░ 50%
剩 4h13m
7d ▓░░░░░░░ 12%
8h13m后重置
到 Releases 页面 下载 ClaudeUsageWidget.exe（单文件，约 36 MB，双击即用）。
exe 不含数据源，运行前请先装好 Node.js 和 ccusage：
# 1) 装 Node.js：https://nodejs.org （任意 LTS 版本）
# 2) 装 ccusage：
npm install -g ccusage没装的话，悬浮窗会显示 ⚠ 采集失败。
双击 ClaudeUsageWidget.exe，桌面右下角即出现悬浮窗。
- 左键拖动：移动窗口，位置自动记忆
- 右键：菜单（立即刷新 / 设置 / 窗口置顶 / 开机自启 / 退出）
- 双击：打开设置
- 想开机自动启动：右键勾选「开机自启」
- 进度条 = ccusage 算的已用费用 ÷ 限额；颜色随占比变（蓝 <70% / 黄 <90% / 红 ≥90%）
- 鼠标悬停看 tooltip（完整费用、限额来源
[auto]/[手动]、重置时刻） - 5h 显示当前活跃块，空闲时显示「空闲」
- 周窗口与官方
/usage同口径：从你指定的每周固定时刻重置（默认周三 19:00）
工具有两种模式，默认自动：
基于你的历史用量反推真实限额，无需手填：
- 5h 限额 = 扫历史 5h 块，找「提前停手 + 等到 5h 窗口重置才再开」的撞限痕迹 → 这些块的 cost 中位数
- 周限额 = 按你的周重置时刻把每日数据切成完整周 → P95 of 完整周累计 cost
- 撞限信号不足（< 2 次）或周数据不够（< 5 周）时，自动回退到手动默认值
打开 Claude Code 输入 /usage 看官方百分比，用「当前费用 ÷ 官方百分比」算出真实限额，填进设置：
- 5h：当前 5h 费用 ÷ 5h 官方百分比
- 周：当前周累计费用 ÷ 周官方百分比
| 字段 | 说明 |
|---|---|
| 刷新间隔 | 5–3600 秒，默认 10 |
| 不透明度 | 40%–100% 滑块，实时预览 |
| 订阅档位 | Pro / Max5 / Max20 / Custom，切换时自动填手动限额预设 |
| 限额模式 | 自动校准（推荐）/ 手动 |
| 5h 费用限额 | 手动模式分母（USD）；自动模式作历史不足兜底 |
| 周费用限额 | 同上 |
| 按 /usage 校准 | 输入官方百分比一键反推真实限额（见下） |
| 周窗口重置 | 与你 /usage 显示的 "Resets …" 对齐（默认周三 19:00） |
| ccusage 命令 | 默认 npx -y ccusage；装了全局版可填 ccusage |
| 开机自动启动 | 写 HKCU\...\Run，无需管理员权限 |
- 打开 Claude Code 输入
/usage看官方 5h % 和 周 % - 在设置里填到「按 /usage 校准」两个输入框
- 点「应用」—— 工具按当前实测 cost 反推真实限额，写入手动限额并切到 Custom + 关闭自动校准
之后进度条占比就和官方对齐了。订阅档位变了或感觉飘了，再校准一次即可。
为什么用费用而不是 token？ ccusage 的
totalTokens把 cache read 按全额算（实测 cache 占 97%），而官方限流给 cache read 权重低得多，导致 token 算的占比会严重失真和漂移。费用天然按真实定价加权（cache read 打 0.1 折），更稳。
配置文件路径：%APPDATA%\ClaudeUsageWidget\config.json
git clone https://github.com/khscience/claude-usage-widget.git
cd claude-usage-widget
pip install -r requirements.txt
python main.pypip install pyinstaller pillow # 首次
build.bat # 或手动执行下面这行
python -m PyInstaller --noconfirm --onefile --noconsole --name ClaudeUsageWidget --icon app.ico --add-data "app.ico;." main.pyClaude Code 官方没有 /usage 数据的程序化接口，桌面端也不渲染 statusLine（已实测）、本地缓存里也不存限流百分比。所以本工具通过社区维护的 ccusage CLI 读取本地会话文件（~/.claude/projects/**/*.jsonl）来统计 token 用量。
[QTimer 每 N 秒] → [QThread 跑 npx ccusage --json]
├→ 解析活跃 5h 块 + 历史块
├→ 自适应算法推真实限额 (auto_limit.py)
└→ 更新进度条 + tooltip
Q：悬浮窗显示 ⚠ / 采集失败？
A：ccusage 调用失败。鼠标悬停看具体错误。常见原因：未装 Node.js / 未装 ccusage / 路径不对。Windows 上 npx 实为 npx.cmd，本工具已自动解析 .cmd/.bat 后缀。
Q：5h 显示「空闲」？ A：当前 5 小时窗口内没有任何 Claude Code 活动。一旦你用 Claude Code 发消息，下次刷新就会显示占比和重置时间。
Q：窗口找不到了 / 拖出屏幕了？
A：编辑 %APPDATA%\ClaudeUsageWidget\config.json，把 pos_x、pos_y 都改成 -1，重启后会自动回到右下角。
Q：自动模式的限额准吗？ A：取决于历史数据。撞限信号 ≥ 2 次时很准；不够则退到 P95 兜底；都不行就用手动默认。tooltip 里会写明限额来源，你可以判断。
Q：进度条占比和 Claude Code 里 /usage 不一致？
A：本工具是本地估算，与官方口径有差。自动模式靠你历史撞限行为推断；手动模式靠你自己校准。两者都不会和官方完全一致，但能反映趋势。
MIT