claude-token-dashboard

一个零依赖的本地 Claude Code token 消耗大盘。扫描 ~/.claude/projects/**/*.jsonl,统计 4 维 token(输入 / 输出 / 缓存读 / 缓存写),生成可交互的 HTML 报表。

跨平台:Windows / macOS / Linux 全部走 Node os.homedir() 解析路径,无任何硬编码。

安装

# 全局安装
npm i -g claude-token-dashboard

# 或者 npx 直接跑(无需安装)
npx claude-token-dashboard --open

入口命令:claude-token-dashboard 或短别名 cctok。

用法

# 一键生成大盘 + 终端摘要,产物在当前目录的 dist/report.html
claude-token-dashboard

# 生成后自动打开浏览器
claude-token-dashboard --open

# 指定输出路径
claude-token-dashboard --out /tmp/claude.html

# 同时导出聚合 JSON(便于二次加工 / 接 BI)
claude-token-dashboard --json report.json

# 显式指定扫描目录
claude-token-dashboard --root ~/.claude/projects

# 只看自动发现的候选路径
claude-token-dashboard --list-roots

目录发现规则

不写死路径,按以下优先级解析:

1. --root <dir> 命令行参数
2. 环境变量 CLAUDE_CONFIG_DIR → $CLAUDE_CONFIG_DIR/projects
3. 默认 ~/.claude/projects(由 Node os.homedir() 解析,自动适配三大平台)

第一个存在的目录会被选中,全部不存在时给出清晰的诊断信息。

输出内容

终端:总览 KPI、Token 总量(4 维)、按模型、主会话 vs 子代理、近 14 天日度、Top 10 会话。

HTML 大盘(dist/report.html,单文件无后端,双击即可):

• 顶部 KPI 卡:输入 / 输出 / 缓存读 / 缓存写 / 合计、会话数、会话总耗时、消息数
• 4 维趋势折线:日 / 周 / 月切换
• 合计趋势折线:4 维之和单独成线,看总量节奏
• 模型堆叠条形图、主 / 子代理环形图
• 项目分布 Top 15 横向条形(点击条目可联动筛选会话)
• 会话明细表:
  • 默认 最新优先,可改最早 / Token 多 / 耗时长几种快捷排序,表头点击也能排
  • 项目下拉筛选 / 关键字搜索
  • 点击某行弹出会话详情:含 5 维 KPI + 3 种内部折线视图(累积趋势 / 每条消息 / 合计单线)

数据口径

• 只统计 type=assistant 且带 message.usage 的记录
• 按 message.id 去重(同一消息流式分片会出现多条),token 字段取最大值,避免重复计数
• 子代理(isSidechain=true)token 默认并入所属主会话,但保留 subAgentRatio 维度可单独查看
• 时间桶:日按本地时区切;周用 ISO 8601(周一为周首);月用 YYYY-MM
• 会话耗时 = 该会话内首条 → 末条 assistant 消息时间差

目录结构

claude-token-dashboard/
├── index.mjs              # CLI 入口
├── lib/
│   ├── paths.mjs          # 跨平台 Claude root 解析
│   ├── scanner.mjs        # 流式读 + 解析 + 按 message.id 去重
│   ├── aggregator.mjs     # 多维聚合 + 每会话 timeline
│   └── renderer.mjs       # 终端摘要 + HTML 模板
├── dist/report.html       # 运行产物(已 gitignore)
├── package.json
└── LICENSE

零运行时依赖,Chart.js 通过 CDN(cdn.jsdelivr.net)加载。要求 Node ≥ 18。

许可证

MIT © codeYang