tokenarchive

每日快照你的 AI 编码使用情况，永久保存。

ccusage 可以告诉你 Claude Code、Codex、Gemini 等工具花费了多少——但仅限于你机器上日志所覆盖的范围，而这些日志会轮转。tokenarchive 每天对 ccusage 报告做一次快照，将每个快照作为仅追加的 JSON 存档保存，并据此渲染一个仪表盘。可选地，一个 Cloudflare Worker 会在你的机器之外保留一份存档副本，并通过通行密钥保护。

这里的一切都遵循两条原则：

• 任何内容都不会被删除。 快照就是存档；每个数据库都是派生副本，可以从快照重建。

• 缺失永远不会被报告为零。 没有快照的一天会明确显示出来。$0.00 会让人误以为我们检查过且你没有任何花费。

快速开始（macOS）

npx tokenarchive

安装程序会提示输入设备名称和可选的 Worker URL，将运行时放在 ~/.local/share/tokenarchive/app 下，安排每日任务（23:50 以及每次登录时——脚本是幂等的），让 security 提示输入摄取令牌，这样它就不会经过安装程序之手，并通过一次真实运行来验证整个过程。随时重新运行以重新配置；--uninstall 会删除除存档之外的所有内容。

快照存放在 ~/.local/share/tokenarchive/{device}/{date}.json。要试运行一次而不安装任何东西：

git clone https://github.com/ddyy/tokenarchive && cd tokenarchive && ./snapshot.sh

其他平台：除调度胶水外，所有内容都是可移植的。sync.js、导入器和仪表盘都是纯 Node；将 snapshot.sh 移植到 systemd 定时器或 cron 任务，其余部分自然就绪。

Related MCP server: Semantic Code Search MCP Server

仪表盘

generate-dashboard.js 构建一个自包含的 HTML 文件——无框架、无服务器、无外部请求。它首先将新快照导入本地 SQLite 读取模型（import-snapshots.js），因此重新生成是增量的。

每个面板都是一个过滤器：点击或拖拽模型、设备、代理、日期或计费窗口，页面其余部分会随之联动（⌘ 添加到选择，⇧ 扩展选择）。过滤器在维度间以 AND 组合，并存在于 URL 片段中，因此视图可以被收藏。

一个 显示方式 开关——位于总计上方，以及当它们滚动离开时再次出现在粘性栏中——以美元或令牌为单位衡量整个页面：图表及其坐标轴、覆盖阴影、计费窗口，以及每个列表（列表会重新排序以匹配）。悬停一行会显示它被截断的完整名称、成本、令牌、隐含的每百万费率、它在屏幕上的占比，以及——对于项目——会话计数和它们覆盖的时间跨度：

覆盖条显示每个日历日一个单元格，因此间隙可见为间隙——没有快照的日子永远不会被绘制为零使用日：

多设备

存档从文件系统层面就按设备分区：快照存放在 {data}/{device}/{date}.json，每个数据库行都带有设备标识，导入仅做 upsert。因此，机器之间永远不会合并或互相覆盖，任何将两台机器的文件放在同一数据目录下的方式都会给你一个合并的存档——Worker、同步文件夹或复制的目录都以相同方式工作。

健康状况按设备判断：每台设备都有自己的绿/黄/红点、自己的最后快照日期和自己的缺失天数列表，因此一台当前活跃的机器无法掩盖另一台已静默的机器。停止报告的设备会保留其所有历史——存档从不删除；它只是显示间隙。

下面的 Worker 是无需手动移动文件即可实现此目的的方式。

Worker（可选，推荐）

worker/ 目录是一个 Cloudflare Worker，它接受快照推送，并从 D1 提供相同的仪表盘，由 WebAuthn 通行密钥保护。原始快照按原样保存在 R2 中——这就是它成为备份而非视图的原因：/admin/replay 可以从存储桶重建 D1，而无需你的笔记本电脑。参见 worker/README.md 了解五命令部署。

部署后，在 /auth/ 注册一个通行密钥——第一个通行密钥认领存档；添加另一台设备的通行密钥需要已登录。然后在 /admin 生成每设备摄取令牌（令牌显示包含设置说明），每日快照任务会自动推送。从未同步的机器不会丢失任何东西：磁盘上的文件就是存档，下一次成功同步会赶上。过时的推送无法覆盖较新的数据——摄取会保留最新的快照。

/admin 管理其余部分：摄取令牌和只读 MCP 令牌（仅显示一次，可按设备撤销）、会话密钥轮换、快照清单，以及 /admin/replay，它从 R2 原始文件重建 D1。

要添加第二台机器，请在那里运行安装程序，使用相同的 Worker URL，并为其铸造自己的摄取令牌——令牌只能作为其铸造时的设备进行摄取，因此一台机器不能以另一台的身份写入，撤销一个令牌不会影响其他令牌。

MCP

向你的代理询问你自己的使用情况。两个服务器，相同的四个只读工具（usage_summary、usage_by_project、usage_by_day、archive_health），一个共享实现：

• 本地，通过此机器上的 SQLite 存档：

  claude mcp add tokenarchive node /path/to/tokenarchive/mcp-server.js

• 远程，由 Worker 在 /mcp 提供，适用于不持有存档的机器。在 /admin 铸造一个 mcp 令牌，然后：

  claude mcp add --transport http tokenarchive https://YOUR-WORKER/mcp \
    --header "Authorization: Bearer YOUR-TOKEN"

按构造只读：没有工具可以写入、删除或重写任何内容。

配置

所有内容都可以通过环境变量覆盖，没有什么是必需的：

测试

bash test/run.sh

大多数套件是封闭的。三个（static、interaction、tooltip）针对你上次生成的仪表盘运行，位于 ~/.local/share/tokenarchive/index.html，因此它们需要机器上有真实存档——先运行一次快照。

许可证

MIT