Tokdash：本地追踪 AI 编程工具的 token 与配额
开源本地看板 Tokdash，支持 Claude Code、Gemini CLI、Codex 等客户端的 token 拆…
Show HN 上亮相的 Tokdash 是一款面向 AI 编程工具的本地化用量看板，主打「不动数据出门」——所有 token、配额与成本数据都留在本机，服务默认只绑定 loopback 地址。它已支持 Claude Code、Gemini CLI、Codex、Antigravity 等客户端，并提供状态栏集成、订阅窗口配额倒计时等新特性。
它能做什么
Tokdash 的核心功能是把散落在各 AI 编程客户端本地的会话日志聚合起来，做成可视化看板：
- 精确 token 拆分：按 Input / Output / Cache 维度展示每一会话的消耗；
- 状态栏集成：可作为 Claude Code 状态栏的实时 token 用量指示器，也可被任何能访问本地 HTTP 端点的 agent 复用；
- 贡献日历：提供 2D 热力图与 3D 等距视图，指标可在 Tokens / Cost / Messages 间切换；
- Session Explorer：下钻到单次会话级别查看明细；
- 配额 Tab（新增）：Codex、Claude Code、Antigravity 的订阅窗口条与重置倒计时，Codex 窗口可直接从本地日志读取，其余需要 opt-in 实时轮询；
- 主题与体验：内置 10 套主题，浅色 / 深色模式自适应，支持作为 PWA 安装。
平台与安装
平台覆盖方面，Linux（含 WSL2）与 macOS 为正式支持，Windows 原生为实验性支持。运行环境要求 Python 3.10+ 并至少安装一个被支持的客户端。
推荐使用 pipx 进行隔离安装：
- pipx install tokdash
- 无 pipx 时回退：python3 -m pip install --user tokdash
首次运行 tokdash setup 会启动引导向导：可选用平台自带的服务管理器注册一个可逆的用户级后台服务，并输出仪表盘 URL（默认 http://127.0.0.1:55423）。向导默认仅监听 loopback，不需要 sudo，卸载时可通过 --purge 一并清理历史。非交互场景可使用 tokdash setup --auto --json；预览改动可用 --dry-run。
安装后建议运行 tokdash doctor 检查运行时、后台服务、端口、数据路径与更新状态；自动化场景可加 --json。
性能与历史保留
项目方公布的本地基准显示，相比 0.6.0 之前的版本，冷启动用量扫描提速约 30 倍，相比同类工具 ccusage 提速约 15 倍。需要注意的是，Claude Code 与 Gemini CLI 默认会在约 30 天后清理本地会话，这会导致 Tokdash 历史曲线出现「静默缩水」。项目方在文档中给出对应客户端的一行配置改动即可避免。
远程访问与安全
Tokdash 默认仅绑定 loopback，需要远程访问时建议通过交互式 setup 选择显式的 Tailscale Serve 步骤，或使用 SSH 端口转发（ssh -L 55423:127.0.0.1:55423 <user>@<host>）。Tailscale Serve 路径使用 /tokdash 子路径，不会抢占根域名。需要注意的是，Serve 代理下的写操作会被 loopback 写入闸门拒绝，因此该通道只读；涉及写入请改用 SSH 转发。
更新与迁移
项目提供 tokdash update 升级受管运行时并在可行时重启服务，tokdash uninstall 反向撤销 setup 创建的内容，默认保留用量历史。若运行时由 Tokdash 不可控的包管理器安装，更新命令会打印明确的手动指引而不会改动该环境。v1.0 之前的安装需要先升级包再运行 doctor 与 setup；对于已存在的手写 systemd / launchd 服务，setup 默认不会静默覆盖未标记的 tokdash.service / plist，用户可选择自行管理、删除后重跑，或使用 --dry-run 预览后再 --force 重写。
总体而言，Tokdash 定位偏个人/小团队开发者的本地可观测性工具，对同时使用多款 AI 编程客户端、又希望统一管理 token 与订阅配额的场景比较实用。