stormzhang/token-tracker

Claude Code & Codex 本地 token 追踪 — 状态栏（Codex 业界首创伪 statusline）、GitHub 风格热力图、多模型成本分析。 | Local token tracker for Claude Code & Codex — status line (industry-first Codex faux statusline), GitHub-style heatmap, multi-model cost analysis

Token Tracker (tt)

功能简介 – Token Tracker 是一个本地命令行工具，用于监控你在使用三个流行的代码助手代理（Claude Code、Codex 和 Kimi Code）时消耗的 AI 模型 token 数量。它读取代理的本地记录文件，汇总 token 数量，估算货币成本，并在几个方便的地方显示信息：

出现在代理自身终端 UI 中的自定义 StatusLine、
可固定在分屏窗口（iTerm2、Ghostty、tmux）中的实时“侧边栏”面板、
一组可按 tt daily、tt weekly 等调用的每日/每周/每月报告。

所有数据都保留在你的机器上 – 没有网络上传。

主要功能（来自 README）

功能	工作原理
三个代理的统一跟踪	读取 Claude Code JSONL 日志、Codex JSONL + SQLite 和 Kimi Code wire JSONL。token 按会话和模型汇总。
StatusLine 集成	• Claude Code – 使用官方 StatusLine API（四行布局）。 • Codex – 通过 Stop 钩子注入两行纯文本（较新版本无颜色）。 • Kimi Code – 使用官方 `status_line` 接口（单色行）。
实时侧边栏（`tt sidebar`）	一个窄面板，每 5 秒刷新一次，列出活动会话（最近 5 小时）、三城市时钟、最近提示、状态灯以及从最后 AI 回复中提取的“下一步”建议。点击一行可跳转到相应的 iTerm2/tmux 面板。
当前会话的自动分屏	在 Codex 或 Kimi Code 会话中输入 `$tt-sidebar`，工具会在右侧打开一个 1/3 宽度的面板，显示该会话的完整提示历史。
配额监控	显示典型 5 小时和 7 天限制的滑动窗口使用情况，带有进度条和重置倒计时。
成本分析	使用 LiteLLM 的定价数据和内置的备用表，涵盖主要模型（Claude Opus、Sonnet、Gemini、Grok、中国模型如 Kimi、GLM、Qwen 等）。计算每次会话、每日、每周和每月的成本。
主题输出	六种颜色主题（Catppuccin 系列、Nord、Dracula）。主题适用于 CLI 报告和代理的状态行。
零配置检测	首次运行时自动检测安装了哪些代理，并读取其本地数据目录。
隐私优先	数据不会发送到任何地方；所有内容都存储在 `~/.config/token-tracker` 下。

典型工作流程

安装 – 运行单行命令 curl … | bash。脚本会选择最佳的安装程序（uv、pipx 或私有 venv）。
设置 – tt setup 引导你完成一个简短的交互式向导（语言、主题、是否接管每个代理的状态行）。
使用 –
- tt 或 tt daily 显示过去一年 token 使用量的 GitHub 风格热力图。
- tt status 显示今天的总额和配额百分比。
- tt weekly / tt monthly 生成条形图报告。
- tt sidebar 打开实时面板；tt sidebar --once 打印单个快照。
- 在 Codex/Kimi 会话中，输入 $tt-sidebar 可获得自动分屏视图。
调整 – 使用 tt theme set <name> 更改主题，或重新运行 tt setup 修改状态行配置。
卸载 – tt unsetup 删除钩子/技能，并恢复以前的自定义状态行。

谁可能会觉得有用？

经常使用 AI 编码助手并需要关注 token 消耗以避免意外账单的开发者。
共享配额（例如 5 小时滑动窗口）并希望快速直观地了解接近限制程度的团队。
喜欢整洁终端 UI 的人 – 侧边栏和状态行无需打开单独的仪表板即可提供一目了然的指标。

限制 / 注意事项

仅适用于支持的三个代理；其他 LLM 前端被忽略。
所有成本计算都依赖于静态价格表；如果提供商更改定价，内置数据必须更新。
“下一步”建议基于规则，不是由模型生成的。
在 Windows 上，侧边栏会适应控制台的 GBK 编码，但某些颜色保真度可能会降低。

快速参考（命令）

tt setup          # 初始配置，安装状态行钩子和侧边栏技能
tt               # 与 `tt daily` 相同 – 年度热力图
tt daily          # token 使用量热力图
tt status         # 今天的总额 + 配额条
tt weekly         # 每周报告（成本、token、趋势）
tt monthly        # 每月报告
tt sessions       # 列出最近会话，可排序
tt sidebar        # 包含活动会话的实时面板
tt sidebar --once# 单个快照
tt theme …       # 显示 / 列出 / 预览 / 设置主题
tt unsetup        # 删除所有注入的钩子/技能

底线 – Token Tracker 是一个真正的开源 Python 工具，为开发者提供了对 AI 编码代理消耗的 token 数量、这些 token 的成本以及是否接近配额限制的具体可见性，所有这些都可以在终端中完成。