stormzhang/token-tracker 项目理解报告

仓库：stormzhang/token-tracker · 当前版本：0.3.5 · Python ≥ 3.11 · License: MIT

一句话：这是一个本地 AI Agent Token 用量追踪工具，命令名 tt，读取 Claude Code 与 Codex 的本地会话数据，展示 token、成本、限额、会话与日/周/月报表，并可配置状态栏。

本地只读统计Claude CodeCodexRich TUIStatusLineMIT

1. 项目定位

token-tracker 面向长期使用 Claude Code / Codex 的开发者，解决“我到底用了多少 token、成本大概多少、限额快到哪里、哪些项目/会话消耗最多”的问题。

不是代理网关：它不拦截请求、不转发 API、不改变模型调用路径。
不是云端监控：核心数据都从本机文件读取，README 强调不上传用户信息。
更像本地 usage dashboard：把 Claude/Codex 各自的日志格式标准化成统一 UsageEntry 后聚合展示。

2. 支持的数据源

Agent	读取路径	格式/依据	说明
Claude Code	`~/.claude/projects` `~/.config/claude/projects`	JSONL assistant message usage	解析 assistant 消息中的 `message.usage`、`costUSD`、`model`、`sessionId`。
Codex	`~/.codex/sessions` `~/.codex/state_5.sqlite`	JSONL + SQLite	JSONL 里读 token_count，SQLite threads 表补模型名。

3. 功能概览

交互式 Dashboard

tt 或 tt dashboard，左右键切换 Claude Code / Codex，上下滚动，按 token/成本/消息数排序。

报表

tt daily、tt weekly、tt monthly、tt sessions，支持 --sort、--asc、--desc。

StatusLine

tt setup 配置 Claude Code 自定义 statusLine 与 Codex 官方 status_line。

限额监控

Claude 读取 ~/.claude/tt-status.json；Codex 从 session token_count 事件读取 5h/7d rate limit。

成本估算

Claude 优先用日志里的 costUSD；否则按 LiteLLM pricing 缓存或 fallback pricing 估算。

会话洞察

按 session 聚合项目、模型、持续时间、输入/输出/cache token、消息数、成本。

4. 技术栈与代码结构

项目非常轻量：约 16 个 Python 源文件，核心代码约 2.9k 行；依赖只有 rich>=13.7。

路径	作用
`src/cli.py`	命令入口；解析 `setup/unsetup/dashboard/daily/weekly/monthly/sessions`。
`src/adapters/claude.py`	检测与读取 Claude Code 数据。
`src/adapters/codex.py`	检测与读取 Codex session 与 rate limit。
`src/adapters/types.py`	统一数据结构：UsageEntry、DailyStats、SessionStats、RateLimits 等。
`src/analyzer/aggregator.py`	日/周/月/会话聚合。
`src/analyzer/cost.py`	按模型价格计算成本，缓存 LiteLLM 价格表。
`src/analyzer/blocks.py`	5 小时窗口 block 分析与 P90 fallback。
`src/hooks.py`	Claude/Codex status line 安装、升级、卸载与恢复。
`src/ui/tables.py`	Rich 表格/面板渲染。

5. 工作流

本地日志/SQLite
  ├─ Claude adapter 解析 ~/.claude/projects/*.jsonl
  ├─ Codex adapter 解析 ~/.codex/sessions/*.jsonl + state_5.sqlite
  ↓
统一 UsageEntry
  ↓
Aggregator 聚合 daily / weekly / monthly / sessions
  ↓
Rich UI 渲染 dashboard / tables
  ↓
可选 setup：写 Claude settings.json 与 Codex config.toml 的 status_line

6. 安装与使用

curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/master/install.sh | bash
# 或
pip install --force-reinstall token-tracker
tt setup

常用命令：

tt                # 交互式 dashboard
tt claude         # 只看 Claude Code
tt codex          # 只看 Codex
tt daily          # 日报
tt weekly         # 周报
tt monthly        # 月报
tt sessions       # 最近会话
tt unsetup        # 恢复安装前配置

7. 关键实现细节

去重：Claude 用 message_id:request_id，Codex 用 session_id 避免重复统计。
Codex token 取值：读取每个 session 最后的 total_token_usage，并把 cached input 从 input 中扣出，cached 单独统计。
成本：有真实 costUSD 就用真实值；没有则根据模型名匹配价格表。
StatusLine：Claude 写入 ~/.claude/settings.json，并创建 ~/.claude/tt-statusline.py；Codex 修改 ~/.codex/config.toml 的 status_line。
恢复：hooks.py 里维护 backup key 和 Codex backup 文件，支持 tt unsetup 恢复。

8. 优点与局限

优点

极轻量，依赖少。
纯本地读取，隐私风险低。
同时支持 Claude Code 与 Codex。
StatusLine + Dashboard + 报表覆盖日常使用。
对 cache token、5h/7d 限额、成本都有关注。

局限/风险

依赖 Claude/Codex 本地日志格式，官方格式变化会破。
成本估算依赖模型名匹配，未知模型会显示 0 或不准。
tt setup 会修改 Claude/Codex 配置，需要信任其备份/恢复逻辑。
Codex 自定义 statusline 能力有限，README 也说明使用官方默认样式。
没有测试目录，当前成熟度更像个人效率工具。

9. 适用场景

个人或小团队频繁使用 Claude Code/Codex，希望知道 token 和成本趋势。
想监控 5h/7d 限额，避免突然触顶。
需要按项目/会话找出高消耗任务。
希望在终端状态栏实时看到当前会话 token/context/cost。

不适合：需要服务端统一计费、多用户审计、跨机器集中监控、或支持任意 OpenAI-compatible Agent 的场景。

10. 我的判断

这是一个实用、轻量、偏个人工作流的本地统计工具。 对 Claude Code/Codex 用户很有用，特别是 statusLine 和本地 dashboard 的组合。

如果放到我们的 Hermes 环境：它不能直接统计 Hermes，因为 Hermes 的 session 格式不同；但它的 adapter → UsageEntry → aggregator → Rich UI 架构可以借鉴，未来可新增 Hermes adapter 读取 ~/.hermes/sessions 或 Hermes SQLite session store。

落地建议：如果只是个人查看 Claude/Codex 用量，可以直接安装；如果要接入 Hermes，需要先写适配器而不是直接使用。

本报告基于 README、pyproject、核心源码与目录结构静态检查生成。