tokentab 的功能
tokentab 是一款本地报告工具，可帮助你了解编程助手如何消耗 Token 并产生预估成本。它读取受支持工具已存储在你计算机上的会话日志，然后按模型、提供商、项目、日期和推断的活动类型对用量进行分组。
无需账户或 API 密钥。所有处理都在你的计算机上完成，tokentab 不会上传会话信息，也不会连接定价服务。
支持的工具和日志位置
tokentab 目前为三款工具提供了可用的解析器：
- Claude Code：
~/.claude/projects/**/*.jsonl - Codex：
~/.codex/sessions/**/rollout-*.jsonl - Gemini CLI：
~/.gemini/tmp/**/session-*.json
项目中已为 Cursor 预留提供商位置，但其解析器尚未完成。如果某款受支持的工具未安装，tokentab 会直接跳过它。因此，报告只会包含你的计算机上存在日志的工具。
主要功能
- 直接从现有的本地会话日志中读取 Token 数量。
- 使用本地手动维护的价格表估算成本。
- 按提供商、模型、项目、日期和活动对数据进行分组。
- 支持每日、每月、全部时间和自定义日期范围。
- 生成终端表格或机器可读的 JSON。
- 提供仅绑定到 localhost 的浏览器仪表板。
- 通过管道传输输出时自动移除终端颜色。
- 不使用 Web 框架；仪表板运行在 Python 标准库的 HTTP 服务器上。
唯一的第三方依赖项是 Rich，用于渲染终端表格。解析、JSON 处理和本地 Web 服务器均使用 Python 标准库。
安装 tokentab
标准安装
克隆仓库，进入其目录，然后将软件包安装到当前激活的 Python 环境中：
git clone https://github.com/damejan80/tokentab
cd tokentab
pip install .
python cli.py安装过程会将 tokentab 命令添加到你的 PATH 中。之后，你可以直接运行已安装的命令：
tokentab可编辑源码安装
如果你计划查看或修改代码，请以可编辑模式安装：
git clone https://github.com/damejan80/tokentab
cd tokentab
pip install -e .
tokentab可编辑安装会让命令与工作副本保持关联，因此本地代码更改无需重新安装软件包即可生效。
运行第一份报告
在仓库目录中，不带任何选项运行 CLI：
python cli.py默认报告涵盖过去七天内检测到的所有提供商和项目。如果已安装命令，对应的调用方式为：
tokentab由于 tokentab 会读取各提供商现有的日志目录，因此无需设置账户或配置凭据。如果不存在受支持的日志，报告中就不会包含相应的用量。
按时间筛选用量
今天的活动
python cli.py -today当前自然月
python cli.py -month全部可用历史记录
python cli.py -p all指定日期范围
python cli.py --from 2026-06-01 --to 2026-06-15当你希望将用量与某个冲刺周期、计费周期、实验或其他指定时间段对应起来时，自定义时间范围非常有用。
按提供商或项目筛选
若只显示 Claude 用量，请传入提供商筛选参数：
python cli.py --provider claude若要聚焦于某个项目，请使用其项目名称：
python cli.py --project myapp这些筛选条件有助于将特定代码库或工具的成本与整体活动区分开来。
导出机器可读的 JSON
当其他程序需要读取报告时，请使用 --json：
python cli.py --json例如，如果已安装 jq，可通过管道将 JSON 传给它，以便格式化或进一步处理：
python cli.py --json | jq .当普通输出通过管道传输时，tokentab 会自动移除终端颜色，便于将报告粘贴到拉取请求、聊天消息、文件或其他命令中，且不会包含 ANSI 转义码。
使用本地 Web 仪表板
使用以下命令启动浏览器界面：
python cli.py -webtokentab 会打开 http://localhost:4747，并以月度账单的形式呈现数据，顶部显示总计，下方列出明细。
仪表板会在每次请求时从磁盘读取日志，而不是缓存结果，因此新记录的会话无需维护独立数据库即可显示。它仅绑定到 localhost，且不会上传数据。它也不使用外部字体服务，因此即使网络断开，界面仍可正常运行。
若要选择其他端口，请使用 --port。若要启动服务器但不自动打开浏览器，请添加 --no-open：
python cli.py -web --port 8080 --no-open了解 Token 和成本计算方式
Token 数量
Token 总数直接来自受支持工具的日志，而不是根据文本估算。tokentab 还会处理缓存报告方式的差异。Claude 会分别记录缓存读取和写入，而 Gemini 报告的输入量包含已缓存的 Token。tokentab 会在必要时扣除缓存部分，以免对同一批 Token 重复计价。
模型定价
价格以每百万 Token 的美元价格存储在本地 tokentab/pricing/prices.py 中。该工具有意使用静态价格表，而不会通过网络请求实时价格。
模型名称采用模糊匹配，因此带日期的模型标识符（例如 claude-opus-4-6-20260514）可以匹配更通用的 claude-opus-4-6 条目。如果某个模型的成本显示为 $0.00，其名称很可能未能匹配价格表。CLI 会报告这种情况，而不会默认假定该模型免费。
定价仅为尽力估算。当供应商调整价格或推出尚未识别的模型名称时，请更新本地价格表。
活动类别
编程、调试、重构、测试、聊天和探索等活动标签，是根据所用工具以及会话首条消息的措辞推断得出的。此分类过程是确定性的，不会调用其他 AI 模型。
请将活动标签视为有用的提示，而非最终判断。它们有助于揭示整体模式，但只有你了解工作的完整背景。
解读报告
- 缓存命中率持续低于约 80%：你的上下文可能频繁变化，或者缓存尚未启用。与持续数周的模式相比，单次异常会话的参考意义较小。
- 昂贵模型占据大量小型调用：报告可能显示，大模型正在处理频繁但有限的任务。tokentab 会展示这一模式，方便你调查这种用法是否符合预期。
- 聊天或探索类别占比较大：记录的活动大多涉及讨论或阅读，而不是编辑。这可能是合理的，但也可能表明某些会话偏离了目标。
这些模式是调查的起点，而不是结论。请将报告与相关会话期间你实际进行的工作进行对照。
进阶技巧：添加其他提供商
每个提供商都以模块形式实现在 tokentab/providers/ 下。提供商需要公开一个 collect() 函数，该函数返回由 UsageRecord 对象组成的扁平列表。共享记录结构定义在 tokentab/types.py 中。
- 在
tokentab/providers/中创建提供商模块。 - 读取并解析该提供商的本地会话文件。
- 将每条相关用量记录转换为共享的
UsageRecord结构。 - 通过
collect()返回记录。 - 将该提供商添加到
tokentab/providers/__init__.py。
记录采用通用结构后，现有的定价、分组、CLI 输出和仪表板就能对其进行处理。README 建议将 Claude 解析器作为最简单的模板，并参考其他可用的解析器获取更多示例。
实用技巧
- 定期运行默认的七天报告，以发现近期变化。
- 查看更广泛的支出模式时，使用月度视图。
- 调查特定代码库前，先按项目筛选。
- 围绕 tokentab 数据构建脚本或自定义报告时，导出 JSON。
- 每当模型成本显示为
$0.00时，请检查价格表。 - 使用仪表板进行可视化查看，使用 CLI 实现自动化或共享。
总结
tokentab 可将本地 Claude Code、Codex 和 Gemini CLI 日志转换为实用的 Token 与成本报告，既不需要凭据，也不会将数据发送到你的计算机之外。你可以先使用默认的七天 CLI 视图，再通过时间、提供商和项目筛选条件缩小结果范围；需要其他展示方式时，则可使用 JSON 或 localhost 仪表板。该项目采用 MIT 许可证发布。