令牌跟踪器

环境要求

• Python 3.11+
• Rich（自动安装）

安装

curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash

脚本自动选最优安装方式（uv / pipx / 私有 venv），绕开 PEP 668、不污染系统 Python。

升级：重跑上面的命令即可（脚本幂等、自动升到最新）。包含新 Agent 集成的版本升级后，再运行一次 tt setup；例如 $tt-sidebar 需要由 setup 安装到 Codex 用户级 Skill 目录。 卸载：tt unsetup

升级后 tt --version 还是旧版？ 多半是旧版装在别的 Python 环境里遮蔽了新版（常见于 Windows、或早期用 pip install 装过）。卸载旧版后重装一次即可：

pip uninstall token-tracker
curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash

使用

tt setup          # 配置状态栏，并安装 Codex / Kimi Code 的 tt-sidebar Skill / 提示词 Hook
tt                # 过去一年 token 热力图 + 顶部三段概览（= tt daily）
tt daily          # 同上（tt 无参即进 daily）
tt status         # 今日消耗、5h/7d 额度与今日会话
tt weekly         # 周报
tt monthly        # 月报
tt sessions       # 最近 20 条会话明细（tt sessions <正整数> 改条数、--sort 改排序）
tt sidebar        # 常驻侧边栏：活跃会话总览 + 提示词历史 + 状态灯 + 点击跳转（--once 一帧快照）
tt theme          # 查看 / 切换配色主题（show / list / set / preview）
tt unsetup        # 卸载并恢复安装前的配置
tt --version      # 查看版本（-v / -V 同义）

多 agent 环境下想只看某一个 agent 的报表，加 --claude / --codex / --kimi 即可（互斥），对 status / daily / weekly / monthly / sessions 均生效。例如 tt daily --kimi 只显示 Kimi Code 的热力图。会话内的 daily / weekly 默认已自动跟随当前会话的 agent，显式 flag 会覆盖该行为。

💡 tt daily 是 GitHub 风格的 token 贡献热力图（深浅绿方格）。在 Claude Code 会话里输入 !tt daily 即可看到彩色热力图 —— 用户主动用 ! 执行的命令，Claude Code 会渲染其 24-bit 真彩色输出。

首次运行向导

第一次跑 tt（或在独立终端跑 tt setup）会进入交互式配置向导，全程上下键选 + 回车确认：

1. 选语言 — 中文 / English（落 ~/.config/token-tracker/config.json）
2. 选配色主题 — 6 套主题上下键选择，每个选项右侧内联色板预览
3. 接管 Claude Code 状态栏 — Yes/No（仅检测到 Claude Code 时；已有自定义 statusLine 会先备份、选 No 完全不碰）
4. 启用 Codex 伪 statusline — Yes/No（仅检测到 Codex 时）
5. 启用 Kimi Code 状态栏 — Yes/No（仅检测到 Kimi Code 时；已有自定义 status_line.command 默认不覆盖）

CI / 非 tty 环境（Docker / 脚本 / curl|bash）自动按推荐默认配置：语言跟随系统设置、主题 mocha、组件默认开启但不替换已有自定义 statusLine。装好后想改任何一项，再跑一次 tt setup 即可。

Claude Code（官方接口）

基于 Claude Code 官方自定义 StatusLine 接口，数据完全来自本地 Claude，无任何推测。

状态栏接管是可选的：已有自定义 statusLine 时默认保留你的配置（向导里也可随时选 No），报表命令完全不受影响。注意：不接管时 tt status 的 CC 订阅额度段将没有数据来源（CC 配额只经状态栏脚本落盘）。

<details> <summary>四行布局字段详解</summary>

终端宽度不足时会自动降级：先隐藏重置倒计时，再将进度条简化为百分比数字。API 模式无订阅配额，第 2 行只显示 Ctx。

</details>

Kimi Code（官方接口）

基于 Kimi Code 官方 status_line 接口（tui.toml），单行真彩色状态栏：

[项目](分支* +A -D ?U) | Total: 21.2M | Cost: $9.08 | 5h: 18% | 7d: 15% | Model: K3/high/auto（与 CC 状态栏同风格；5h/7d 限额走云端 /usages 缓存，每 2 分钟后台刷新一次）

• 项目 / 分支 / 模型 / 权限模式来自 Kimi 官方快照（快照无思考档位，effort 取自会话 wire 里实际请求的 thinkingEffort），分支段的未提交增删行 / 未跟踪数按 git diff --numstat + git ls-files 统计（同 CC 状态栏）；Total 与 Cost 由状态栏脚本按会话 wire.jsonl 增量累计（offset 缓存，每秒级调用只读新增部分），成本按内置 Kimi 官方定价估算
• macOS / Linux / Windows 全平台支持（Windows 控制台 GBK 编码、后台刷新进程 detach 方式均已适配）
• 已有自定义 status_line.command 时默认不覆盖（向导里选 No 也完全不碰）；tt unsetup 精确还原