token-tracker 0.3.8__tar.gz → 0.4.0__tar.gz

token_tracker-0.4.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: token-tracker
+Version: 0.4.0
+Summary: Track token usage across local AI agents (Claude Code, Codex)
+Author-email: stormzhang <stormzhang.dev@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 stormzhang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/stormzhang/token-tracker
+Project-URL: Repository, https://github.com/stormzhang/token-tracker
+Project-URL: Issues, https://github.com/stormzhang/token-tracker/issues
+Keywords: claude-code,codex,token,usage,cost,ai-agent,statusline,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: questionary>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# Token Tracker (tt)
+
+本地 AI Agent Token 消耗追踪/分析工具，支持 **Claude Code** 和 **Codex** 。
+
+自定义 StatusLine 状态栏 + CLI Dashboard，实时查看 token 用量、等效成本、限额状态。
+
+![Python](https://img.shields.io/badge/python-3.11+-blue) ![CI](https://github.com/stormzhang/token-tracker/actions/workflows/ci.yml/badge.svg) ![License](https://img.shields.io/badge/license-MIT-green)
+
+[English](README_EN.md)
+
+## StatusLine 状态栏
+
+自动为 Claude Code 和 Codex 配置状态栏，`tt setup` 一键配置，脚本更新时自动升级。
+
+**Claude Code**：基于官方自定义 StatusLine 接口，数据完全来自本地 Claude，准确无任何推测
+
+![Claude Code StatusLine](assets/screenshot-statusline-cc.png)
+
+状态栏共四行，从左到右：
+
+| 行 | 字段 | 说明 |
+|----|------|------|
+| 1 | `[项目](分支 +12 -3)` | 项目名（加粗）+ Git 分支（未提交修改标 `*`），括号内附工作区相对 HEAD 的增删行数 |
+| 1 | `Total: 1.2M` | 本次会话累计消耗 token（输入+输出+cache，解析 transcript 得出） |
+| 1 | `Cost: $35.51` | 本次会话等效成本（Claude Code 自带，按官方计费，准确） |
+| 1 | `Code: +208 -8` | 本会话 Claude 写 / 删的代码行数（`+` 绿 `-` 红，与 git 变动同配色） |
+| 2 | `Limit: 5h: ██░ 31% (1h19m)` | 5 小时滑动窗口配额（仅订阅模式；括号内重置倒计时） |
+| 2 | `7d: ██░ 11% (5d8h)` | 7 天滑动窗口配额 |
+| 2 | `1.0M Ctx: ██░ 20%` | 上下文窗口总大小及已用占比 |
+| 3 | `Tokens: in 392k, out 937, cache 388k` | **当前上下文窗口**的 token 构成（注意：非会话累计，会随 compact 变化） |
+| 3 | `Out TPS: 60 tokens/s` | 本轮 output token 生成速度（含 thinking；空闲帧保留上次值） |
+| 4 | `Model: Opus 4.8/xhigh/nofast` | 模型名 / reasoning 级别 / 是否 fast 模式 |
+| 4 | `Duration: 1h33m` | 当前会话已持续时间 |
+| 4 | `Remote: github` | 代码仓库 host（去顶级域） |
+
+> 终端宽度不足时会自动降级：先隐藏重置倒计时，再将进度条简化为百分比数字。**API 模式**无订阅配额，第 2 行只显示 Ctx。
+
+**Codex**：官方暂不支持自定义 StatusLine，`tt setup` 通过 Codex `Stop` hook 装一个**伪 statusline**——每次回答完成后在回答尾部追加**两行**彩色 status，仿 Claude Code 状态栏（不再接管 Codex 官方 `status_line`，伪 statusline 信息比官方字段更全）：
+
+![Codex StatusLine](assets/screenshot-statusline-codex.png)
+
+**伪 statusline 两行布局**：
+
+- **L1** `[项目](分支 +A -D) | Total: <会话累计 token> | Model: <模型 推理强度>` —— Total 橙、Model 红
+- **L2** `Limit: 5h <进度条> % (reset <倒计时>) | 7d <进度条> % (reset <倒计时>) | <窗口> Ctx <进度条> %`
+
+通过 `Stop` hook 注入 `systemMessage` 实现，渲染 24-bit 真彩色、**不进模型上下文**（实测），**配色跟随当前主题**（与 CLI 报表 / CC 状态栏同源，`tt theme` 切换三者一起变）。`tt unsetup` 一并移除。
+
+## Status 实时面板和 日/周/月 数据报表分析
+
+`tt`（无参）/ `tt status`：聚焦**过去 5 小时**的实时面板——顶部多 Agent **合并**概览（Token / Cost / Sessions / Messages / Top Model），中间 **5h / 7d 订阅额度**进度条（Claude Code / Codex 分开；都没订阅额度时换成 per-agent 的 token/cost/sessions/messages 统计），底部**近期会话**列表（CC + Codex 合并、带 Agent 列、按 Cost 倒序、Cost 前三名高亮）。所有时间按**系统时区**显示，配色跟随当前主题。
+
+![Token Tracker Status](assets/screenshot.png)
+
+![Token Tracker Daily](assets/screenshot-daily.png)
+
+![Token Tracker Weekly](assets/screenshot-weekly.png)
+
+![Token Tracker Monthly](assets/screenshot-monthly.png)
+
+## 功能
+
+- **多 Agent 追踪** — Claude Code + Codex 统一面板，左右键切换
+- **状态栏集成** — Claude Code statusLine + Codex status_line，首次运行自动配置，脚本更新自动升级
+- **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
+- **成本分析** — 按会话、日、周、月维度的等效成本统计，多 Agent 按来源分组展示
+- **定价识别** — litellm 在线定价 + 内置官方价双层兜底；同系列新模型自动套用本档定价（含 Claude Fable 5 / Opus 4.8），全新系列缺价时明确提示，不静默按 $0 统计
+- **会话洞察** — 项目、模型、时长、消息数一览
+- **多主题统一配色** — 6 套主题（Catppuccin Mocha/Latte/Frappe/Macchiato + Nord + Dracula），CLI 报表、CC 状态栏与 Codex 伪 statusline **三者同源**；`tt theme` 一键切换 / 预览，暗 / 亮终端自动选 Catppuccin，首次运行交互向导引导选择，`TT_THEME` 可覆盖；终端不支持 truecolor 时自动降级到 256 色近似
+- **零配置** — 自动检测已安装的 Agent，直接读取本地数据
+- **隐私安全** — 数据纯本地存储，不采集、不上传任何用户信息，极轻量无后顾之忧
+
+## 安装
+
+```bash
+curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash
+```
+
+或者通过 pip：
+
+```bash
+pip install --force-reinstall token-tracker && tt setup
+```
+
+## 使用
+
+```bash
+tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境自动全装
+tt                # 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话，= tt status）
+tt status         # 同上（tt 无参即进 status）
+tt daily          # 过去一年 token 贡献热力图（GitHub 风格）+ 年度分析卡片
+tt weekly         # 周报：本周分析卡片 + 每日趋势柱状图 + 周 / 项目 / 模型趋势
+tt monthly        # 按月汇总（多 Agent 分组展示）
+tt sessions       # 最近 20 条会话明细（按 cost 倒序展示；tt sessions <n> 改条数、--sort 改排序）
+tt theme          # 查看 / 切换配色主题（show / list / set / preview）
+tt unsetup        # 卸载并恢复安装前的配置
+```
+
+> 💡 `tt daily` 是 GitHub 风格的 token 贡献热力图（深浅绿方格）。在 Claude Code 会话里输入 `!tt daily` 即可看到彩色热力图 —— 用户主动用 `!` 执行的命令，Claude Code 会渲染其 24-bit 真彩色输出。
+
+### 首次运行向导
+
+第一次跑 `tt`（或通过 curl 一键安装脚本装完自动启动）会进入**交互式配置向导**，全程上下键选 + 回车确认：
+
+1. **选语言** — 中文 / English（落 `~/.config/token-tracker/config.json`，之后所有命令跟随）
+2. **选配色主题** — 6 套主题上下键选择，每个选项右侧内联色板预览
+3. **启用 Codex 伪 statusline** — Yes/No，默认 Yes（仅检测到 Codex 时）
+
+选完给一份键值对齐的配置总结 + 重启 / 下一步提示。CI / 非 tty 环境（Docker / 脚本）自动按默认全装：**语言跟随系统设置**（读系统语言、不被 CLI 的 `LANG` 误导）、主题 mocha、组件全开。装好后想改任何一项，再跑一次 `tt setup` 即可（终端里每次 `tt setup` 都进向导）。
+
+### 配色主题
+
+内置 6 套主题，CLI 报表、CC 状态栏与 Codex 伪 statusline **统一同源**（切主题三者一起变）：
+
+| 主题 | 说明 |
+|------|------|
+| `mocha` / `latte` / `frappe` / `macchiato` | Catppuccin 全家（暗 / 亮终端自动选 mocha / latte） |
+| `nord` | Nord |
+| `dracula` | Dracula |
+
+```bash
+tt theme               # 显示当前主题及来源
+tt theme list          # 列出全部主题 + 色块预览
+tt theme preview nord  # 预览某主题（CLI 样例 + 状态栏样例行）
+tt theme set nord      # 切换主题（持久化 + 重烘焙状态栏）
+tt monthly --theme nord  # 任意报表临时换主题渲染（不持久化、不动状态栏，适合对比）
+```
+
+- **首次运行**（终端内、非 AI 会话）会进入交互向导引导选主题；CI / 脚本 / 会话内自动跳过、静默用默认。
+- 切换持久化到 `~/.config/token-tracker/config.json`（主题 + 语言 + 组件意图统一存这一个文件）；优先级 `--theme` 参数 > `TT_THEME` 环境变量 > 配置文件 > 自动（`--theme` 和 `TT_THEME` 都只临时生效、不写配置）。
+- 终端支持 truecolor 用精确配色；不支持的（如 macOS 自带 Terminal.app）自动降级到当前主题的 **256 色近似**，8 色老终端不再适配。
+
+### 报告排序
+
+所有报告命令支持 `--sort` 和 `--asc/--desc` 参数：
+
+```bash
+tt weekly --sort cost --desc    # 按成本降序
+tt sessions --sort tokens --asc # 按 token 升序
+```
+
+可选排序字段：`tokens` / `cost` / `messages` / `time` / `input` / `output`
+
+### Dashboard 快捷键
+
+| 按键 | 功能 |
+|------|------|
+| `←` `→` | 切换 Agent |
+| `↑` `↓` | 滚动内容 |
+| `s` | 切换排序字段（时间 → Token → 等效成本 → 消息数） |
+| `r` | 反转排序方向 |
+| `+` / `-` | 调整会话显示条数（±10，最少 10 条） |
+| `q` | 退出 |
+
+## 数据来源
+
+| Agent | 路径 | 格式 |
+|-------|------|------|
+| Claude Code | `~/.claude/projects/*/` | JSONL（逐消息用量） |
+| Codex | `~/.codex/sessions/` | JSONL + SQLite |
+
+路径跨平台：Windows 下 `~` 解析到 `%USERPROFILE%`（如 `C:\Users\xxx\.claude`）。设了 `CLAUDE_CONFIG_DIR` / `CODEX_HOME` 环境变量（官方支持的自定义目录）时自动跟随。
+
+Token Tracker 对 Agent 数据**只读**，不做任何修改。
+
+## 环境要求
+
+- Python 3.11+
+- [Rich](https://github.com/Textualize/rich)（自动安装）
+
+## 开发
+
+```bash
+git clone https://github.com/stormzhang/token-tracker && cd token-tracker
+uv run --extra dev pytest                # 运行测试
+uv run --extra dev ruff check src tests  # Lint
+```
+
+包采用标准 src layout（`src/token_tracker/`）：发行名 `token-tracker`，导入名 `token_tracker`（0.4.0 起）。
+
+## TODO
+
+未来持续增加更多数据报表，多维度分析。
+
+## License
+
+Copyright (c) 2026 stormzhang. MIT License.

token_tracker-0.4.0/README.md

@@ -0,0 +1,187 @@
+# Token Tracker (tt)
+
+本地 AI Agent Token 消耗追踪/分析工具，支持 **Claude Code** 和 **Codex** 。
+
+自定义 StatusLine 状态栏 + CLI Dashboard，实时查看 token 用量、等效成本、限额状态。
+
+![Python](https://img.shields.io/badge/python-3.11+-blue) ![CI](https://github.com/stormzhang/token-tracker/actions/workflows/ci.yml/badge.svg) ![License](https://img.shields.io/badge/license-MIT-green)
+
+[English](README_EN.md)
+
+## StatusLine 状态栏
+
+自动为 Claude Code 和 Codex 配置状态栏，`tt setup` 一键配置，脚本更新时自动升级。
+
+**Claude Code**：基于官方自定义 StatusLine 接口，数据完全来自本地 Claude，准确无任何推测
+
+![Claude Code StatusLine](assets/screenshot-statusline-cc.png)
+
+状态栏共四行，从左到右：
+
+| 行 | 字段 | 说明 |
+|----|------|------|
+| 1 | `[项目](分支 +12 -3)` | 项目名（加粗）+ Git 分支（未提交修改标 `*`），括号内附工作区相对 HEAD 的增删行数 |
+| 1 | `Total: 1.2M` | 本次会话累计消耗 token（输入+输出+cache，解析 transcript 得出） |
+| 1 | `Cost: $35.51` | 本次会话等效成本（Claude Code 自带，按官方计费，准确） |
+| 1 | `Code: +208 -8` | 本会话 Claude 写 / 删的代码行数（`+` 绿 `-` 红，与 git 变动同配色） |
+| 2 | `Limit: 5h: ██░ 31% (1h19m)` | 5 小时滑动窗口配额（仅订阅模式；括号内重置倒计时） |
+| 2 | `7d: ██░ 11% (5d8h)` | 7 天滑动窗口配额 |
+| 2 | `1.0M Ctx: ██░ 20%` | 上下文窗口总大小及已用占比 |
+| 3 | `Tokens: in 392k, out 937, cache 388k` | **当前上下文窗口**的 token 构成（注意：非会话累计，会随 compact 变化） |
+| 3 | `Out TPS: 60 tokens/s` | 本轮 output token 生成速度（含 thinking；空闲帧保留上次值） |
+| 4 | `Model: Opus 4.8/xhigh/nofast` | 模型名 / reasoning 级别 / 是否 fast 模式 |
+| 4 | `Duration: 1h33m` | 当前会话已持续时间 |
+| 4 | `Remote: github` | 代码仓库 host（去顶级域） |
+
+> 终端宽度不足时会自动降级：先隐藏重置倒计时，再将进度条简化为百分比数字。**API 模式**无订阅配额，第 2 行只显示 Ctx。
+
+**Codex**：官方暂不支持自定义 StatusLine，`tt setup` 通过 Codex `Stop` hook 装一个**伪 statusline**——每次回答完成后在回答尾部追加**两行**彩色 status，仿 Claude Code 状态栏（不再接管 Codex 官方 `status_line`，伪 statusline 信息比官方字段更全）：
+
+![Codex StatusLine](assets/screenshot-statusline-codex.png)
+
+**伪 statusline 两行布局**：
+
+- **L1** `[项目](分支 +A -D) | Total: <会话累计 token> | Model: <模型 推理强度>` —— Total 橙、Model 红
+- **L2** `Limit: 5h <进度条> % (reset <倒计时>) | 7d <进度条> % (reset <倒计时>) | <窗口> Ctx <进度条> %`
+
+通过 `Stop` hook 注入 `systemMessage` 实现，渲染 24-bit 真彩色、**不进模型上下文**（实测），**配色跟随当前主题**（与 CLI 报表 / CC 状态栏同源，`tt theme` 切换三者一起变）。`tt unsetup` 一并移除。
+
+## Status 实时面板和 日/周/月 数据报表分析
+
+`tt`（无参）/ `tt status`：聚焦**过去 5 小时**的实时面板——顶部多 Agent **合并**概览（Token / Cost / Sessions / Messages / Top Model），中间 **5h / 7d 订阅额度**进度条（Claude Code / Codex 分开；都没订阅额度时换成 per-agent 的 token/cost/sessions/messages 统计），底部**近期会话**列表（CC + Codex 合并、带 Agent 列、按 Cost 倒序、Cost 前三名高亮）。所有时间按**系统时区**显示，配色跟随当前主题。
+
+![Token Tracker Status](assets/screenshot.png)
+
+![Token Tracker Daily](assets/screenshot-daily.png)
+
+![Token Tracker Weekly](assets/screenshot-weekly.png)
+
+![Token Tracker Monthly](assets/screenshot-monthly.png)
+
+## 功能
+
+- **多 Agent 追踪** — Claude Code + Codex 统一面板，左右键切换
+- **状态栏集成** — Claude Code statusLine + Codex status_line，首次运行自动配置，脚本更新自动升级
+- **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
+- **成本分析** — 按会话、日、周、月维度的等效成本统计，多 Agent 按来源分组展示
+- **定价识别** — litellm 在线定价 + 内置官方价双层兜底；同系列新模型自动套用本档定价（含 Claude Fable 5 / Opus 4.8），全新系列缺价时明确提示，不静默按 $0 统计
+- **会话洞察** — 项目、模型、时长、消息数一览
+- **多主题统一配色** — 6 套主题（Catppuccin Mocha/Latte/Frappe/Macchiato + Nord + Dracula），CLI 报表、CC 状态栏与 Codex 伪 statusline **三者同源**；`tt theme` 一键切换 / 预览，暗 / 亮终端自动选 Catppuccin，首次运行交互向导引导选择，`TT_THEME` 可覆盖；终端不支持 truecolor 时自动降级到 256 色近似
+- **零配置** — 自动检测已安装的 Agent，直接读取本地数据
+- **隐私安全** — 数据纯本地存储，不采集、不上传任何用户信息，极轻量无后顾之忧
+
+## 安装
+
+```bash
+curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash
+```
+
+或者通过 pip：
+
+```bash
+pip install --force-reinstall token-tracker && tt setup
+```
+
+## 使用
+
+```bash
+tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境自动全装
+tt                # 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话，= tt status）
+tt status         # 同上（tt 无参即进 status）
+tt daily          # 过去一年 token 贡献热力图（GitHub 风格）+ 年度分析卡片
+tt weekly         # 周报：本周分析卡片 + 每日趋势柱状图 + 周 / 项目 / 模型趋势
+tt monthly        # 按月汇总（多 Agent 分组展示）
+tt sessions       # 最近 20 条会话明细（按 cost 倒序展示；tt sessions <n> 改条数、--sort 改排序）
+tt theme          # 查看 / 切换配色主题（show / list / set / preview）
+tt unsetup        # 卸载并恢复安装前的配置
+```
+
+> 💡 `tt daily` 是 GitHub 风格的 token 贡献热力图（深浅绿方格）。在 Claude Code 会话里输入 `!tt daily` 即可看到彩色热力图 —— 用户主动用 `!` 执行的命令，Claude Code 会渲染其 24-bit 真彩色输出。
+
+### 首次运行向导
+
+第一次跑 `tt`（或通过 curl 一键安装脚本装完自动启动）会进入**交互式配置向导**，全程上下键选 + 回车确认：
+
+1. **选语言** — 中文 / English（落 `~/.config/token-tracker/config.json`，之后所有命令跟随）
+2. **选配色主题** — 6 套主题上下键选择，每个选项右侧内联色板预览
+3. **启用 Codex 伪 statusline** — Yes/No，默认 Yes（仅检测到 Codex 时）
+
+选完给一份键值对齐的配置总结 + 重启 / 下一步提示。CI / 非 tty 环境（Docker / 脚本）自动按默认全装：**语言跟随系统设置**（读系统语言、不被 CLI 的 `LANG` 误导）、主题 mocha、组件全开。装好后想改任何一项，再跑一次 `tt setup` 即可（终端里每次 `tt setup` 都进向导）。
+
+### 配色主题
+
+内置 6 套主题，CLI 报表、CC 状态栏与 Codex 伪 statusline **统一同源**（切主题三者一起变）：
+
+| 主题 | 说明 |
+|------|------|
+| `mocha` / `latte` / `frappe` / `macchiato` | Catppuccin 全家（暗 / 亮终端自动选 mocha / latte） |
+| `nord` | Nord |
+| `dracula` | Dracula |
+
+```bash
+tt theme               # 显示当前主题及来源
+tt theme list          # 列出全部主题 + 色块预览
+tt theme preview nord  # 预览某主题（CLI 样例 + 状态栏样例行）
+tt theme set nord      # 切换主题（持久化 + 重烘焙状态栏）
+tt monthly --theme nord  # 任意报表临时换主题渲染（不持久化、不动状态栏，适合对比）
+```
+
+- **首次运行**（终端内、非 AI 会话）会进入交互向导引导选主题；CI / 脚本 / 会话内自动跳过、静默用默认。
+- 切换持久化到 `~/.config/token-tracker/config.json`（主题 + 语言 + 组件意图统一存这一个文件）；优先级 `--theme` 参数 > `TT_THEME` 环境变量 > 配置文件 > 自动（`--theme` 和 `TT_THEME` 都只临时生效、不写配置）。
+- 终端支持 truecolor 用精确配色；不支持的（如 macOS 自带 Terminal.app）自动降级到当前主题的 **256 色近似**，8 色老终端不再适配。
+
+### 报告排序
+
+所有报告命令支持 `--sort` 和 `--asc/--desc` 参数：
+
+```bash
+tt weekly --sort cost --desc    # 按成本降序
+tt sessions --sort tokens --asc # 按 token 升序
+```
+
+可选排序字段：`tokens` / `cost` / `messages` / `time` / `input` / `output`
+
+### Dashboard 快捷键
+
+| 按键 | 功能 |
+|------|------|
+| `←` `→` | 切换 Agent |
+| `↑` `↓` | 滚动内容 |
+| `s` | 切换排序字段（时间 → Token → 等效成本 → 消息数） |
+| `r` | 反转排序方向 |
+| `+` / `-` | 调整会话显示条数（±10，最少 10 条） |
+| `q` | 退出 |
+
+## 数据来源
+
+| Agent | 路径 | 格式 |
+|-------|------|------|
+| Claude Code | `~/.claude/projects/*/` | JSONL（逐消息用量） |
+| Codex | `~/.codex/sessions/` | JSONL + SQLite |
+
+路径跨平台：Windows 下 `~` 解析到 `%USERPROFILE%`（如 `C:\Users\xxx\.claude`）。设了 `CLAUDE_CONFIG_DIR` / `CODEX_HOME` 环境变量（官方支持的自定义目录）时自动跟随。
+
+Token Tracker 对 Agent 数据**只读**，不做任何修改。
+
+## 环境要求
+
+- Python 3.11+
+- [Rich](https://github.com/Textualize/rich)（自动安装）
+
+## 开发
+
+```bash
+git clone https://github.com/stormzhang/token-tracker && cd token-tracker
+uv run --extra dev pytest                # 运行测试
+uv run --extra dev ruff check src tests  # Lint
+```
+
+包采用标准 src layout（`src/token_tracker/`）：发行名 `token-tracker`，导入名 `token_tracker`（0.4.0 起）。
+
+## TODO
+
+未来持续增加更多数据报表，多维度分析。
+
+## License
+
+Copyright (c) 2026 stormzhang. MIT License.

{token_tracker-0.3.8 → token_tracker-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "token-tracker"
-version = "0.3.8"
+version = "0.4.0"
 description = "Track token usage across local AI agents (Claude Code, Codex)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,6 +26,7 @@ classifiers = [
 ]
 dependencies = [
     "rich>=13.7",
+    "questionary>=2.0",
 ]
 
 [project.optional-dependencies]
@@ -44,10 +45,10 @@ Repository = "https://github.com/stormzhang/token-tracker"
 Issues = "https://github.com/stormzhang/token-tracker/issues"
 
 [project.scripts]
-tt = "src.cli:main"
+tt = "token_tracker.cli:main"
 
 [tool.setuptools.packages.find]
-include = ["src*"]
+where = ["src"]
 
 [tool.ruff]
 line-length = 120

{token_tracker-0.3.8/src → token_tracker-0.4.0/src/token_tracker}/adapters/claude.py

@@ -3,10 +3,10 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from .types import AgentInfo, UsageEntry
-from .util import iter_jsonl_dicts, project_from_cwd
+from .util import claude_home, iter_jsonl_dicts, project_from_cwd
 
 CLAUDE_DIRS = [
-    os.path.expanduser("~/.claude/projects"),
+    os.path.join(claude_home(), "projects"),
     os.path.expanduser("~/.config/claude/projects"),
 ]
 

{token_tracker-0.3.8/src → token_tracker-0.4.0/src/token_tracker}/adapters/codex.py

@@ -4,16 +4,29 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 from .types import AgentInfo, RateLimits, UsageEntry, normalize_pct
-from .util import iter_jsonl_dicts, project_from_cwd
+from .util import codex_home, iter_jsonl_dicts, project_from_cwd
 
-CODEX_DIR = os.path.expanduser("~/.codex")
+CODEX_DIR = codex_home()
 SESSIONS_DIR = os.path.join(CODEX_DIR, "sessions")
 STATE_DB = os.path.join(CODEX_DIR, "state_5.sqlite")
 _RATE_LIMIT_SCAN_FILES = 5  # 只扫最近改动的 N 个 session 文件找限额信息
 
+# Codex 内部虚拟 model 改写到背后真实 model，避免它们在 Model Trend / sessions 等报表里独占行；
+# 同时让 cost 走真实 model 的精确定价（cost.py 的 codex- 系列兜底是双保险）。
+# 已知虚拟 model：
+#   codex-auto-review —— stop-time auto-review gate，背后跑当前主 codex 模型（gpt-5.5）
+_VIRTUAL_MODEL_REWRITE = {
+    "codex-auto-review": "gpt-5.5",
+}
+
+
+def _rewrite_virtual_model(model: str) -> str:
+    return _VIRTUAL_MODEL_REWRITE.get(model, model)
+
 
 def detect() -> AgentInfo | None:
-    if Path(SESSIONS_DIR).is_dir():
+    # 以 ~/.codex 目录判断是否安装（与 hooks._has_codex 一致；不要求已产生 sessions/）
+    if Path(CODEX_DIR).is_dir():
         return AgentInfo(id="codex", name="Codex")
     return None
 
@@ -45,7 +58,7 @@ def _load_thread_models() -> dict[str, str]:
         conn = sqlite3.connect(f"file:{STATE_DB}?mode=ro", uri=True)
         rows = conn.execute("SELECT id, model FROM threads WHERE model IS NOT NULL").fetchall()
         conn.close()
-        return {row[0]: row[1] for row in rows}
+        return {row[0]: _rewrite_virtual_model(row[1]) for row in rows}
     except (sqlite3.Error, OSError):
         return {}
 
@@ -137,9 +150,19 @@ def _parse_jsonl(
     model = "unknown"
     last_usage = None
     msg_count = 0
+    session_end_ts: datetime | None = None
 
     for data in iter_jsonl_dicts(path):
         row_type = data.get("type")
+        # 取所有事件里最大的 timestamp 作会话结束时间（与 session 开始的差 = 真实跨度，供 sessions 报表）
+        ts_raw = data.get("timestamp")
+        if ts_raw:
+            try:
+                et = datetime.fromisoformat(ts_raw.replace("Z", "+00:00"))
+                if session_end_ts is None or et > session_end_ts:
+                    session_end_ts = et
+            except (ValueError, AttributeError):
+                pass
 
         if row_type == "session_meta":
             payload = data.get("payload", {})
@@ -197,4 +220,5 @@ def _parse_jsonl(
         project=project,
         agent_id="codex",
         message_count=msg_count,
+        session_end=session_end_ts,
     ))

{token_tracker-0.3.8/src → token_tracker-0.4.0/src/token_tracker}/adapters/rate_limits.py

@@ -4,7 +4,8 @@ from datetime import UTC, datetime
 
 from .types import RateLimits, normalize_pct
 
-STATUS_FILE = os.path.expanduser("~/.claude/tt-status.json")
+# 与 hooks.STATUS_FILE 一致：tt 自己的产物集中放 ~/.config/token-tracker（XDG）
+STATUS_FILE = os.path.join(os.path.expanduser("~/.config/token-tracker"), "tt-status.json")
 
 
 def load_rate_limits() -> RateLimits | None:

{token_tracker-0.3.8/src → token_tracker-0.4.0/src/token_tracker}/adapters/types.py

@@ -29,6 +29,8 @@ class UsageEntry:
     project: str
     agent_id: str
     message_count: int = 1
+    # 仅 codex：单条 entry 即整段会话，记录会话结束时间，让 aggregate_sessions 能算真实跨度（claude 留 None 走多条 entry）
+    session_end: datetime | None = None
 
     @property
     def total_tokens(self) -> int:
@@ -57,6 +59,7 @@ class DailyStats:
     session_count: int = 0
     message_count: int = 0
     models: dict[str, int] = field(default_factory=dict)
+    projects: dict[str, int] = field(default_factory=dict)
     agent_id: str = ""
 
 
@@ -74,6 +77,7 @@ class WeeklyStats:
     session_count: int = 0
     message_count: int = 0
     models: dict[str, int] = field(default_factory=dict)
+    projects: dict[str, int] = field(default_factory=dict)
     agent_id: str = ""
 
 
@@ -84,7 +88,8 @@ class SessionStats:
     model: str
     start_time: datetime
     end_time: datetime
-    duration_minutes: float
+    duration_minutes: float  # 会话跨度（首尾时间差），仅用于显示
+    active_minutes: float = 0.0  # 活跃时长：相邻 entry 间隔 ≤ CAP 才累加、大空隙丢弃；也用于过滤 <5min 短会话
     input_tokens: int = 0
     output_tokens: int = 0
     cache_creation_tokens: int = 0
@@ -93,6 +98,8 @@ class SessionStats:
     cost_usd: float = 0.0
     message_count: int = 0
     agent_id: str = ""
+    # 会话内各 model 的 output_tokens（按生成量降序），渲染时取前若干个展示
+    models: dict[str, int] = field(default_factory=dict)
 
 
 @dataclass
@@ -107,6 +114,7 @@ class MonthlyStats:
     session_count: int = 0
     message_count: int = 0
     models: dict[str, int] = field(default_factory=dict)
+    projects: dict[str, int] = field(default_factory=dict)
     agent_id: str = ""
 
 
@@ -142,3 +150,17 @@ class SessionBlock:
     is_active: bool = False
     burn_rate: float = 0.0
     is_gap: bool = False
+
+
+@dataclass
+class StatusSummary:
+    """tt status 头图面板：当天多 agent 合并的消耗汇总（add_token_fields 累加用）。"""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+    message_count: int = 0
+    session_count: int = 0
+    models: dict[str, int] = field(default_factory=dict)