claude-usage-report

把本机 Claude Code(以及 Codex、Gemini CLI、Antigravity 等)的 Token 用量和估算费用,变成一个实时更新的本地看板。数据来自 ccusage,页面不联网、不依赖任何外部资源。

• 每 10 分钟自动更新,页面上有“立即刷新”按钮
• 日 / 周 / 月 / 年 四种粒度,近 30 天 / 近 90 天 / 今年 / 全部 四种范围,费用 / Token 两种指标
• 按模型堆叠的趋势图、活跃日历热力图、星期分布、Token 构成
• 周期明细、按模型、按项目、费用最高的 10 天和 10 个会话,共 5 张表
• 浅色 / 深色自动跟随系统,手机宽度可用

费用是按 API 公开价折算的估算值,不是账单上实际扣费的金额。

一键启动

需要先装好 Node.js(用来运行 ccusage)和 Python 3。macOS 自带 Python 3,装过 Xcode 命令行工具即可。

curl -fsSL https://raw.githubusercontent.com/Carry3/claude-usage-report/main/run.sh | bash

浏览器会自动打开 http://localhost:8765/。按 Ctrl+C 停止。

想先看看脚本再运行,或者改端口、间隔:

curl -fsSL https://raw.githubusercontent.com/Carry3/claude-usage-report/main/run.sh -o run.sh
less run.sh
bash run.sh --port 9000 --interval 5

不用 curl,自己 clone

git clone https://github.com/Carry3/claude-usage-report.git
cd claude-usage-report
python3 scripts/build_report.py --serve --open

Windows 用 python scripts\build_report.py --serve --open(我没有在 Windows 上测试过)。

参数

参数	作用
--serve	启动本机实时看板。不加这个参数则只生成一个 HTML 文件
--port 8765	看板端口,被占用时自动顺延到下一个
--interval 10	自动更新间隔,单位分钟,最小 1
--open	启动后用默认浏览器打开
--since YYYY-MM-DD / --until YYYY-MM-DD	只取这段日期的数据
--timezone Asia/Shanghai	按这个时区分天,默认本机时区
--offline	用 ccusage 缓存的模型价格,不联网查价
--out FILE	不加 --serve 时的输出路径,默认 claude-usage-report.html
--host 127.0.0.1	监听地址。默认只有本机能访问;改成 0.0.0.0 后同一网络里的人都能看到你的用量和项目名

只生成静态文件:

python3 scripts/build_report.py --out ~/claude-usage-report.html --open

数据和隐私

• 全程只读本机日志(~/.claude/projects 等),不修改文件,也不上传任何数据。
• 看板默认只监听 127.0.0.1,并拒绝 Host 不是 localhost 的请求,防止被网页通过 DNS 重绑定读取。
• 页面里会出现你的项目目录名和费用。项目名取自会话日志里的工作目录,只显示目录名;没选文件夹的会话归入“临时工作区”,Claude Code 的 git worktree 合并到所在项目。截图或分享前请留意。
• 为什么没有“公共网站”:用量日志在每个人自己的电脑上,网站读不到;要在线看就得把数据上传,这里选择不这么做。

作为 Claude Code 的 skill 使用

git clone https://github.com/Carry3/claude-usage-report.git ~/.claude/skills/usage-report

之后在 Claude Code 里说“打开用量看板”“生成用量报表”,它会按 SKILL.md 里的说明运行脚本。

常见问题

• 提示找不到 npx:安装 Node.js 后重试。
• 第一次启动要十几秒:ccusage 要先下载并汇总全部日志,之后每次刷新约 5 秒。
• 刷新失败:页面会保留上一次的数据,并在状态栏提示失败原因,下一个周期自动重试。
• 改页面外观:改 assets/template.html,数据以 JSON 注入到 DATA,重启服务即可。

English

A zero-dependency Python script that turns local AI-coding usage logs (via ccusage) into a live dashboard on localhost. It refreshes every 10 minutes and has a manual refresh button; day/week/month/year views; fully offline page. Requires Node.js (for npx ccusage) and Python 3.

curl -fsSL https://raw.githubusercontent.com/Carry3/claude-usage-report/main/run.sh | bash

Costs are estimates at public API prices, not your actual bill. Data never leaves your machine; the server binds to 127.0.0.1 by default.

License

MIT