tokscale 是一款面向 AI 编程代理场景的高性能命令行工具与可视化仪表盘，核心用途是帮助用户追踪和分析来自多个 AI 编程代理的 token 使用量与费用。其设计灵感来自卡尔达肖夫等级（Kardashev scale），将 token 视为 AI 辅助开发时代的“能量”，用以衡量个人在 AI 增强开发中的使用规模。
主要能力
- 多平台支持：可追踪 OpenCode、Claude Code、Codex CLI、Prime Agent、Copilot CLI、Cursor IDE、Gemini CLI、Amp、Codebuff、Droid、OpenClaw、Hermes Agent、Pi、Kimchi Coding、Reasonix、Kimi CLI、Kimi Work、Qwen CLI、Roo Code、Kilo、Mux、Kilo CLI、Crush、Goose、Antigravity 系列、Zed、Kiro、Trae、Warp/Oz、Cline、Gajae-Code、Grok Build、Jcode、MiMo Code、Command Code、Junie、ZCode、OpenCodeReview、CodeBuddy、WorkBuddy、Devin 系列、Augment Code、Synthetic、Cherry Studio、LM Studio、Unsloth Studio、Hindsight、fx、Oh My Pi、Muse Code 等众多代理（原文列出长清单，此处不逐一改代码或安装命令）。
- 实时定价：从 LiteLLM 获取当前定价数据，带 1 小时磁盘缓存；支持 OpenRouter 回退以及 Cursor 模型定价，以覆盖新发布的模型。
- 详细细分：追踪输入、输出、缓存读/写和推理 token。
- 原生 Rust 核心：所有解析和聚合在 Rust 中完成，处理速度约提升 10 倍。
- Web 可视化：交互式贡献图，含 2D 与 3D 视图。
- 灵活过滤：可按平台、日期范围或年份过滤。
- 任务归因报告：基于 LLM 的会话摘要与任务分组，支持多种后端（Apple FM、Claude、Codex、Gemini、Kiro、MiniMax）。
- 导出 JSON：生成数据供外部可视化工具使用。
- 社交平台：分享用量、参与排行榜、查看公开资料。
使用方式
- 安装与运行（安装命令保留原文）：可通过
bunx tokscale@latest submit向排行榜提交用量数据并创建公开资料。 - 包结构：tokscale 是一个别名包（类似 swc），会安装 @tokscale/cli；两者安装同一 CLI，并包含原生 Rust 核心（@tokscale/core）。
- 交互式 TUI 模式（默认模式）：提供 10 个交互视图（Overview、Usage、Models、Daily、Hourly、Monthly、Sessions、Projects、Stats、Agents，另有可选 Minutely 视图通过 minutelyTabEnabled 开启）。支持键盘与鼠标导航、GitHub 风格贡献图（可配置色主题）、实时过滤与排序、零闪烁渲染。
- 快捷键示例：←/→/Tab/BackTab 切换视图；↑/↓ 或 Home/End 导航列表；Enter 打开详情；Esc/Backspace 关闭对话框或退出详情；c/d/t 按费用/日期/token 排序；j 跳转到今天；s 打开来源选择对话框；g 打开分组选择对话框（model、client+model、client+provider+model、workspace+model、session+model、client+session+model）；h 切换 Daily/Hourly 图表粒度；v 切换 Table/Profile 视图；b 切换子代理会话上卷；y 复制选中行；p 循环切换色主题；L 切换浅色模式；r 刷新数据，Shift+R 切换自动刷新，+/- 调整间隔；e 导出 JSON；q 或 Ctrl+C 退出。
- 分组策略：可在 TUI 按 g 或使用
--group-by。--group-by model（最合并）、--group-by client,model（CLI 默认）、--group-by client,provider,model（最细粒度）、--group-by session,model（按会话归因费用）、--group-by client,session,model、--group-by workspace,model（按工作目录归因）。TUI 中按 g → Workspace + Model，再按 w 切换 worktree 上卷。 - 客户端过滤：使用
--client（短-c）将报告限定到一个或多个客户端，可重复、接受逗号分隔值，适用于所有报告命令。可能值包括 opencode、claude、codex、copilot、gemini、cursor、amp、codebuff、droid、openclaw、hermes、pi、prime-agent、kimchi、kimi、qwen、roocode、kilocode、kilo、mux、crush、goose、antigravity、antigravity-cli、antigravity-extension、zed、kiro、trae、warp、cline、gjc、grok、jcode、micode、micode-desktop、commandcode、junie、zcode、opencodereview、codebuddy、augment、synthetic、cherrystudio、lmstudio、unsloth、hindsight、muse。 - 破坏性变更（v4.0.0）：每客户端布尔标志（如
--opencode、--claude、--codex）已移除并会报错，改用规范化的--client/-c，例如tokscale --client opencode,claude。 - 日期过滤：适用于生成报告的所有命令（
tokscale、tokscale models、tokscale monthly、tokscale graph）。使用本地时区，--since与--until均为包含式。 - 定价查询：可查询任意模型的实时定价。解析策略为多步：自定义定价覆盖（来自
~/.config/tokscale/custom-pricing.json）、精确匹配、别名解析（如 big-pickle → glm-4.7）、层级后缀剥离（gpt-5.2-xhigh → gpt-5.2）、版本规范化、提供商前缀匹配、Cursor 模型定价、模糊匹配。 - 自定义定价：可在 Tokscale 配置目录创建 custom-pricing.json（macOS/Linux 默认
~/.config/tokscale/custom-pricing.json；设置了 TOKSCALE_CONFIG_DIR 时以该目录为准）以覆盖上游定价数据库尚未正确覆盖的模型 ID。覆盖价格以每百万 token 的美元数输入，Tokscale 内部转换为每 token 费率；至少需提供 input_cost_per_million_tokens 或 output_cost_per_million_tokens 之一，缓存读/创建字段可选；显式 0 允许，用于声明免费模型（与省略字段不同，省略意味着费率未知、用量不计价）。也支持 LiteLLM 风格的每 token 字段名，如 input_cost_per_token、output_cost_per_token、cache_read_input_token_cost。
适用场景
适合需要跨多个 AI 编程代理统一监控与比较 token 消耗的开发者、团队或个人；希望了解不同模型/客户端/项目的成本归属；需要按会话或工作区归因费用；或希望参与用量排行榜与生成年度报告。
限制
- 部分客户端不记录工作区，其用量会归入单一 Unknown workspace 行，无法按目录归因（原文称约一半支持的客户端如此，包括 gemini、cursor、amp、droid、roocode、kilocode、goose 以及 Copilot 的 OTEL 路径）。
- 不同客户端对工作区的记录格式不一致（如 Claude Code 使用破折号转义的目录 slug，Codex 与 OpenCode 存真实路径），tokscale 会尝试解析回真实路径；但通过两种不同路径拼写（符号链接与其目标）到达的同一仓库仍会显示为两行，因为工作区身份按字符串比较；总数不受影响。
- 未提供收费/价格信息（除定价数据与自定义定价机制外，暂未提供产品本身的收费说明）。
