一款高性能的命令行工具及可视化仪表盘，用于跟踪多个 AI 编码代理的 token 使用量和成本。

[!TIP]

v2 已发布——原生 Rust TUI、跨平台支持等更多功能。每周我都会推出新的开源项目，别错过下一个哦。

	关注 GitHub 上的 @junhoyeo，了解更多项目。专注于 AI、基础设施以及相关领域的开发。
	欢迎加入我们的 Discord 社区，与全球顶尖开发者一起交流互动。

概览	模型

每日摘要	统计数据

前端（3D 贡献图）	Wrapped 2025

运行 bunx tokscale@latest submit，将你的使用数据提交到排行榜并创建公开个人资料！

概述

Tokscale 可帮助你监控和分析以下来源的 token 消耗情况：

标志	客户端	数据位置	支持情况
	OpenCode	~/.local/share/opencode/opencode.db (1.2+) 或/且 ~/.local/share/opencode/storage/message/ (旧版/未迁移)	✅ 是
	Claude Code	~/.claude/projects/	✅ 是
	OpenClaw	~/.openclaw/agents/ (+ 旧版：.clawdbot、.moltbot、.moldbot)	✅ 是
	Codex CLI	~/.codex/sessions/	✅ 是
	Gemini CLI	~/.gemini/tmp/*/chats/*.json	✅ 是
	Cursor IDE	通过 ~/.config/tokscale/cursor-cache/ 进行 API 同步	✅ 是
	Amp (AmpCode)	~/.local/share/amp/threads/	✅ 是
	Droid (Factory Droid)	~/.factory/sessions/	✅ 是
	Pi	~/.pi/agent/sessions/	✅ 是
	Kimi CLI	~/.kimi/sessions/	✅ 是
	Qwen CLI	~/.qwen/projects/	✅ 是
	Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/ (+ 服务器：~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/)	✅ 是
	Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/ (+ 服务器：~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/)	✅ 是
	Mux	~/.mux/sessions/	✅ 是
	Kilo CLI	~/.local/share/kilo/kilo.db	✅ 是
	Crush	$XDG_DATA_HOME/crush/projects.json (项目注册表；备用：~/.local/share/crush/projects.json)	✅ 是
	Synthetic	通过 hf: 模型前缀或 synthetic 提供商从其他来源重新归因而来 (+ Octofriend：~/.local/share/octofriend/sqlite.db)	✅ 是

使用 🚅 LiteLLM 的定价数据，获取实时定价计算，支持分层定价模型和缓存 token 折扣。

为什么叫“Tokscale”？

本项目灵感源自卡达谢夫量表（Kardashev scale），这是天体物理学家尼古拉·卡达谢夫提出的一种衡量文明技术发展水平的方法，其依据是该文明的能量消耗。I型文明能够利用其所在行星上的全部能量，II型文明则能捕获其恒星的全部能量输出，而III型文明则掌控整个星系的能量。

在人工智能辅助开发的时代，token就是新的能源。它们驱动我们的推理能力、提升生产力，并推动创意产出。正如卡达谢夫量表以宇宙尺度追踪能量消耗一样，Tokscale会根据你在 AI 增强开发领域的进步程度来衡量你的 token 消耗情况。无论你是普通用户，还是每天消耗数百万 tokens 的开发者，Tokscale 都能帮助你可视化自己的成长轨迹——从行星级开发者到银河系级别的代码架构师。

目录

• 概述
  • 为什么叫“Tokscale”？
• 功能
• 安装
  • 快速入门
  • 前提条件
  • 开发环境搭建
  • 构建原生模块
• 使用方法
  • 基本命令
  • TUI 功能
  • 按平台筛选
  • 按日期筛选
  • 价格查询
  • 社交功能
  • Cursor IDE 命令
  • 示例输出
  • 配置
  • 环境变量
• 前端可视化
  • 功能
  • 运行前端
• 社交平台
  • 功能
  • 开始使用
  • 数据验证
• Wrapped 2025
  • 命令
  • 包含内容
• 开发
  • 前提条件
  • 如何运行
• 支持的平台
  • 原生模块目标
  • Windows 支持
• 会话数据保留
• 数据来源
• 定价
• 贡献
  • 开发指南
• 致谢
• 许可证

功能

• 交互式 TUI 模式：由 Ratatui 提供支持的精美终端 UI（默认模式）
  • 4 个交互式视图：概览、模型、每日、统计
  • 键盘与鼠标导航
  • GitHub 风格的贡献图，提供 9 种配色主题
  • 实时过滤与排序
  • 无闪烁渲染
• 多平台支持：跟踪 OpenCode、Claude Code、Codex CLI、Cursor IDE、Gemini CLI、Amp、Droid、OpenClaw、Pi、Kimi CLI、Qwen CLI、Roo Code、Kilo、Mux、Kilo CLI、Crush 和 Synthetic 等平台的使用情况。
• 实时定价：从 LiteLLM 获取当前价格，缓存有效期为 1 小时；自动回退至 OpenRouter，并为新发布的模型提供 Cursor 模型定价。
• 详细拆分：输入、输出、缓存读写以及推理 token 的追踪。
• 原生 Rust 核心：所有解析和聚合操作均由 Rust 完成，处理速度提升 10 倍。
• Web 可视化：交互式贡献图，支持 2D 和 3D 视图。
• 灵活筛选：可按平台、日期范围或年份进行筛选。
• 导出为 JSON：生成数据以便用于外部可视化工具。
• 社交平台：分享你的使用情况、参与排行榜竞争并查看公开资料。

安装

快速入门

# 直接使用 npx 运行
npx tokscale@latest

# 或者使用 bunx
bunx tokscale@latest

# 轻量模式（仅表格显示）
npx tokscale@latest --light

就这么简单！无需任何设置即可获得完整的交互式 TUI 体验。

包结构：“tokscale” 是一个别名包（类似于 swc），它会安装 @tokscale/cli。两者都会安装相同的 CLI，并包含原生 Rust 核心 (@tokscale/core)。

前提条件

• Node.js 或 Bun
• （可选）Rust 工具链，用于从源码构建原生模块。

开发环境搭建

若需本地开发或从源码构建：

# 克隆仓库
git clone https://github.com/junhoyeo/tokscale.git
cd tokscale

# 安装 Bun（如果尚未安装）
curl -fsSL https://bun.sh/install | bash

# 安装依赖
bun install

# 以开发模式运行 CLI
bun run cli

注意：“bun run cli” 用于本地开发。通过 bunx tokscale 安装后，直接运行即可。下方的使用部分展示了已安装的二进制命令。

构建原生模块

原生 Rust 模块是 CLI 正常运行的必要条件。它通过并行文件扫描和 SIMD JSON 解析，将处理速度提升约 10 倍：

# 构建原生核心（在仓库根目录下运行）
bun run build:core

注意：通过 bunx tokscale@latest 安装时，预编译的原生二进制文件已包含在内。只有在本地开发时才需要从源码构建。

使用方法

基本命令

# 启动交互式 TUI（默认）
tokscale

# 启动特定标签页的 TUI
tokscale models    # 模型标签页
tokscale monthly   # 每日视图（显示每日明细）

# 使用旧版 CLI 表格输出
tokscale --light
tokscale models --light

# 显式启动 TUI
tokscale tui

# 导出贡献图数据为 JSON
tokscale graph --output data.json

# 输出数据为 JSON（用于脚本或自动化）
tokscale --json                    # 默认模型视图的 JSON 格式
tokscale models --json             # 模型明细的 JSON 格式
tokscale monthly --json            # 月度明细的 JSON 格式
tokscale models --json > report.json   # 保存到文件

TUI 功能

交互式 TUI 模式提供以下功能：

• 4 个视图：概览（图表 + 排行前几的模型）、模型、每日、统计（贡献图）。
• 键盘导航：
  • 1-4 或 ←/→/Tab：切换视图。
  • ↑/↓：浏览列表。
  • c/d/t：按成本/日期/token 数量排序。
  • s：打开源选择对话框。
  • g：打开分组选择对话框（按模型、客户端+模型、客户端+提供商+模型）。
  • p：循环切换 9 种配色主题。
  • r：刷新数据。
  • e：导出为 JSON。
  • q：退出。
• 鼠标支持：点击标签页、按钮和筛选器。
• 主题：绿色、万圣节、青蓝色、蓝色、粉色、紫色、橙色、单色、YlGnBu。
• 设置持久化：偏好设置会保存到 ~/.config/tokscale/settings.json 文件中（参见 配置）。

分组策略

在 TUI 中按 g 键，或在 --light/--json 模式下使用 --group-by 选项，可以控制模型行的聚合方式：

--group-by model（最整合）

--group-by client,model（CLI 默认）

--group-by client,provider,model（最细粒度）

按平台筛选

# 仅显示 OpenCode 的使用情况
tokscale --opencode

# 仅显示 Claude Code 的使用情况
tokscale --claude

# 仅显示 Codex CLI 的使用情况
tokscale --codex

# 仅显示 Gemini CLI 的使用情况
tokscale --gemini

# 仅显示 Cursor IDE 的使用情况（需先执行 `tokscale cursor login`）
tokscale --cursor

# 仅显示 Amp 的使用情况
tokscale --amp

# 仅显示 Droid 的使用情况
tokscale --droid

# 仅显示 OpenClaw 的使用情况
tokscale --openclaw

# 仅显示 Pi 的使用情况
tokscale --pi

# 仅显示 Kimi CLI 的使用情况
tokscale --kimi

# 仅显示 Qwen CLI 的使用情况
tokscale --qwen

# 仅显示 Roo Code 的使用情况
tokscale --roocode

# 仅显示 Kilo 的使用情况
tokscale --kilocode

# 仅显示 Mux 的使用情况
tokscale --mux

# 仅显示 Kilo CLI 的使用情况
tokscale --kilo

# 仅显示 Crush 的使用情况
tokscale --crush

# 仅显示 Synthetic (synthetic.new) 的使用情况
tokscale --synthetic

# 组合筛选条件
tokscale --opencode --claude

日期筛选

日期筛选适用于所有生成报告的命令（tokscale、tokscale models、tokscale monthly、tokscale graph）：

# 快速日期快捷键
tokscale --today              # 仅今天
tokscale --week               # 近 7 天
tokscale --month              # 当前日历月

# 自定义日期范围（包含起始与结束日期，本地时区）
tokscale --since 2024-01-01 --until 2024-12-31

# 按年份筛选
tokscale --year 2024

# 结合其他选项
tokscale models --week --claude --json
tokscale monthly --month --benchmark

注意：日期筛选使用您的本地时区。--since 和 --until 均为包含性范围。

定价查询

查询任意模型的实时定价：

# 查询模型定价
tokscale pricing "claude-3-5-sonnet-20241022"
tokscale pricing "gpt-4o"
tokscale pricing "grok-code"

# 强制指定提供商来源
tokscale pricing "grok-code" --provider openrouter
tokscale pricing "claude-3-5-sonnet" --provider litellm

查询策略：

定价查询采用多步骤解析策略：

1. 精确匹配 - 直接在 LiteLLM/OpenRouter 数据库中查找
2. 别名解析 - 解析友好名称（如 big-pickle → glm-4.7）
3. 去除等级后缀 - 移除质量等级（gpt-5.2-xhigh → gpt-5.2）
4. 版本标准化 - 处理版本格式（claude-3-5-sonnet ↔ claude-3.5-sonnet）
5. 匹配提供商前缀 - 尝试常见前缀（anthropic/、openai/ 等）
6. Cursor 模型定价 - 对尚未收录于 LiteLLM/OpenRouter 的模型硬编码定价（如 gpt-5.3-codex）
7. 模糊匹配 - 基于词边界对部分模型名称进行匹配

提供商优先级：

当存在多个匹配项时，原始模型开发者优先于转售商：

例如：grok-code 匹配 xai/grok-code-fast-1（$0.20/$1.50），而非 azure_ai/grok-code-fast-1（$3.50/$17.50）。

社交功能

# 登录 Tokscale（打开浏览器进行 GitHub 认证）
tokscale login

# 查看当前登录用户
tokscale whoami

# 提交使用数据至排行榜
tokscale submit

# 带筛选条件提交
tokscale submit --opencode --claude --since 2024-01-01

# 预览将要提交的内容（试运行）
tokscale submit --dry-run

# 注销
tokscale logout

Cursor IDE 命令

Cursor IDE 需要通过会话令牌单独认证（与社交平台登录不同）：

# 登录 Cursor（需要从浏览器获取会话令牌）
# --name 是可选的；它只是帮助您稍后识别账户
tokscale cursor login --name work

# 检查 Cursor 认证状态及会话有效期
tokscale cursor status

# 列出已保存的 Cursor 账户
tokscale cursor accounts

# 切换活动账户（控制哪个账户同步到 cursor-cache/usage.csv）
tokscale cursor switch work

# 从特定账户注销（保留历史记录；不计入汇总）
tokscale cursor logout --name work

# 注销并删除该账户的缓存使用数据
tokscale cursor logout --name work --purge-cache

# 从所有 Cursor 账户注销（保留历史记录；不计入汇总）
tokscale cursor logout --all

# 退出所有账户并删除缓存的使用数据
tokscale cursor logout --all --purge-cache

默认情况下，tokscale 会聚合所有已保存的 Cursor 账户的使用情况（即所有的 cursor-cache/usage*.csv 文件）。

当你注销时，tokscale 会将你的缓存使用历史移动到 cursor-cache/archive/ 目录下，这样它就不会被聚合。如果你希望直接删除这些缓存的使用数据，可以使用 --purge-cache 参数。

凭据存储：Cursor 账户信息存储在 ~/.config/tokscale/cursor-credentials.json 中。使用数据则缓存在 ~/.config/tokscale/cursor-cache/ 目录下（当前活跃账户的数据存储在 usage.csv 中，其他账户的数据则分别存储在 usage.<account>.csv 文件中）。

获取 Cursor 会话令牌的方法：

1. 在浏览器中打开 https://www.cursor.com/settings
2. 打开开发者工具（按 F12 键）
3. 选项 A - Network 标签页：在页面上执行任意操作，找到一个指向 cursor.com/api/* 的请求，在请求头中查找 Cookie 字段，复制 WorkosCursorSessionToken= 后面的值。
4. 选项 B - Application 标签页：进入 Application → Cookies → https://www.cursor.com，找到名为 WorkosCursorSessionToken 的 Cookie，复制其值（不是 Cookie 名称）。

⚠️ 安全提示：请将你的会话令牌视为密码一样对待。切勿公开分享或将其提交到版本控制系统中。该令牌可让你完全访问你的 Cursor 账户。

示例输出（--light 版本）

配置

Tokscale 将设置存储在 ~/.config/tokscale/settings.json 文件中：

{
  "colorPalette": "blue",
  "includeUnusedModels": false
}

环境变量

环境变量会覆盖配置文件中的值。适用于 CI/CD 或一次性使用场景：

# 示例：为超大数据集增加超时时间
TOKSCALE_NATIVE_TIMEOUT_MS=600000 tokscale graph --output data.json

注意：若需持久化更改，建议在 ~/.config/tokscale/settings.json 中设置 nativeTimeoutMs。环境变量更适合用于一次性覆盖或 CI/CD 场景。

无头模式

Tokscale 可以从 Codex CLI 的无头输出 中聚合 Token 使用情况，适用于自动化、CI/CD 流水线和批量处理。

什么是无头模式？

当你使用 JSON 输出标志运行 Codex CLI（例如 codex exec --json）时，它会将使用数据输出到标准输出，而不是存储在其常规会话目录中。无头模式允许你捕获并跟踪这些使用数据。

存储位置：~/.config/tokscale/headless/

在 macOS 上，如果未设置 TOKSCALE_HEADLESS_DIR，Tokscale 还会扫描 ~/Library/Application Support/tokscale/headless/ 目录。

Tokscale 会自动扫描以下目录结构：

~/.config/tokscale/headless/
└── codex/       # Codex CLI 的 JSONL 输出

环境变量：设置 TOKSCALE_HEADLESS_DIR 可自定义无头日志目录：

export TOKSCALE_HEADLESS_DIR="$HOME/my-custom-logs"

推荐（自动捕获）：

手动重定向（可选）：

诊断信息：

# 显示扫描位置和无头计数
tokscale sources
tokscale sources --json

CI/CD 集成示例：

# 在你的 GitHub Actions 工作流中
- name: 运行 AI 自动化
  run: |
    mkdir -p ~/.config/tokscale/headless/codex
    codex exec --json "review code changes" \
      > ~/.config/tokscale/headless/codex/pr-${{ github.event.pull_request.number }}.jsonl

# 稍后，跟踪使用情况
- name: 报告 Token 使用情况
  run: tokscale --json

注意：无头捕获仅支持 Codex CLI。如果你直接运行 Codex，请按照上述方法将标准输出重定向到无头目录。

前端可视化

前端提供了一种类似 GitHub 的贡献图可视化：

功能

• 2D 视图：经典的 GitHub 贡献日历
• 3D 视图：基于 Token 使用量的高度等距 3D 贡献图
• 多种配色方案：GitHub、GitLab、万圣节、冬季等
• 三重主题切换：浅色 / 深色 / 系统（跟随操作系统偏好）
• GitHub Primer 设计：采用 GitHub 官方颜色体系
• 交互式提示框：悬停可查看每日详细分解
• 每日分解面板：点击可查看各来源及各模型的详细信息
• 年份筛选：可在不同年份之间导航
• 来源筛选：可按平台筛选（OpenCode、Claude、Codex、Cursor、Gemini、Amp、Droid、OpenClaw、Pi、Kimi、Qwen、Roo Code、Kilo、Mux、Kilo CLI、Crush、Synthetic）
• 统计面板：总成本、Token 数量、活跃天数、连续天数
• FOUC 防止：在 React 水合之前应用主题（无闪烁现象）

运行前端

cd packages/frontend
bun install
bun run dev

打开 http://localhost:3000 即可访问社交平台。

社交平台

Tokscale 包含一个社交平台，你可以在其中分享自己的使用数据，并与其他开发者竞争。

功能

• 排行榜：查看跨平台使用最多 Token 的用户
• 用户个人资料：带有贡献图和统计数据的公开个人资料
• 周期筛选：可查看全部时间、本月或本周的统计数据
• GitHub 集成：使用 GitHub 账户登录
• 本地查看器：无需提交即可私下查看自己的数据

GitHub 个人资料嵌入小部件

你可以将你的公开 Tokscale 统计数据直接嵌入到你的 GitHub 个人主页 README 中：

[![Tokscale Stats](https://tokscale.ai/api/embed/<username>/svg)](https://tokscale.ai/u/<username>)

• 将 <username> 替换为你的 GitHub 用户名
• 可选查询参数：
  • theme=light 用于浅色主题
  • sort=tokens（默认）或 sort=cost 用于控制排名依据
  • compact=1 用于使用紧凑布局 + 紧凑数字表示法（例如 1.2M, $3.4K)
• 示例：
  • https://tokscale.ai/api/embed/<username>/svg?theme=light&sort=cost&compact=1

GitHub 个人资料徽章

你也可以使用 shields.io 风格的徽章来实现更紧凑的展示：

![Tokscale Tokens](https://tokscale.ai/api/badge/<username>/svg)

• 将 <username> 替换为你的 GitHub 用户名
• 可选查询参数：
  • metric=tokens（默认）、metric=cost 或 metric=rank
  • style=flat（默认）或 style=flat-square
  • sort=tokens（默认）或 sort=cost 来控制排名依据
  • compact=1 使用紧凑数字表示法（例如 1.2M、$3.4K）
  • label=<text> 覆盖左侧标签
  • color=<hex> 覆盖右侧颜色（例如 color=ff5733）
• 示例：
  • https://tokscale.ai/api/badge/<username>/svg?metric=cost&compact=1
  • https://tokscale.ai/api/badge/<username>/svg?metric=rank&sort=cost&style=flat-square

开始使用

1. 登录 - 运行 tokscale login 通过 GitHub 进行身份验证
2. 提交 - 运行 tokscale submit 上传你的使用数据
3. 查看 - 访问网页平台查看你的个人资料和排行榜

数据验证

提交的数据会经过一级验证：

• 数学一致性（总计匹配，无负值）
• 无未来日期
• 必填字段齐全
• 重复检测

Wrapped 2025

生成一张精美的年度回顾图片，总结你使用 AI 编码助手的情况——灵感来自 Spotify Wrapped。

bunx tokscale@latest wrapped	bunx tokscale@latest wrapped --clients	bunx tokscale@latest wrapped --agents --disable-pinned

命令

# 生成当前年的 Wrapped 图片
tokscale wrapped

# 生成特定年份的 Wrapped 图片
tokscale wrapped --year 2025

包含内容

生成的图片包括：

• 总 Token 数量 - 你全年的 Token 消耗总量
• 顶级模型 - 按成本排名的你最常用的 3 个 AI 模型
• 顶级客户端 - 你最常用的 3 个平台（OpenCode、Claude Code、Cursor 等）
• 消息数量 - 总共的 AI 交互次数
• 活跃天数 - 至少有一次 AI 交互的日子
• 成本 - 根据 LiteLLM 定价估算的总成本
• 连续活跃天数 - 你最长的连续活跃天数
• 贡献图 - 你全年活动的可视化热力图

生成的 PNG 已经优化，适合在社交媒体上分享。与社区分享你的编码之旅吧！

开发

快速设置：如果你只想快速开始，请参阅上方安装部分中的 开发设置。

先决条件

# Bun（必需）
bun --version

# Rust（用于原生模块）
rustc --version
cargo --version

如何运行

按照 开发设置 后，你可以：

# 构建原生模块（可选但推荐）
bun run build:core

# 在开发模式下运行（启动 TUI）
cd packages/cli && bun src/cli.ts

# 或者使用旧版 CLI 模式
cd packages/cli && bun src/cli.ts --light

# 测试原生模块（Rust）
cd packages/core
bun run test:rust      # Cargo 测试
bun run test           # Node.js 集成测试
bun run test:all       # 两者都运行

cd packages/core

# 以调试模式构建（编译更快）
bun run build:debug

# 以发布模式构建（优化版）
bun run build

# 运行 Rust 基准测试
bun run bench

# 将图表数据导出到文件
tokscale graph --output usage-data.json

# 按日期筛选（所有快捷方式均适用）
tokscale graph --today
tokscale graph --week
tokscale graph --since 2024-01-01 --until 2024-12-31
tokscale graph --year 2024

# 按平台筛选
tokscale graph --opencode --claude

# 显示处理时间基准测试
tokscale graph --output data.json --benchmark

tokscale --benchmark           # 显示默认视图的处理时间
tokscale models --benchmark    # 模型报告的基准测试
tokscale monthly --benchmark   # 月度报告的基准测试
tokscale graph --benchmark     # 图表生成的基准测试

# 导出数据用于可视化
tokscale graph --output packages/frontend/public/my-data.json

# 生成合成数据
cd packages/benchmarks && bun run generate

# 运行 Rust 基准测试
cd packages/core && bun run bench

支持的平台

原生模块目标平台

Windows 支持

Tokscale 完全支持 Windows。TUI 和 CLI 的使用方式与 macOS/Linux 相同。

Windows 上的安装：

# 安装 Bun（PowerShell）
powershell -c "irm bun.sh/install.ps1 | iex"

# 运行 tokscale
bunx tokscale@latest

Windows 上的数据存储位置

AI 编码工具会将会话数据存储在跨平台的位置。大多数工具在所有平台上都使用相同的相对路径：

注意：在 Windows 上，~ 会展开为 %USERPROFILE%（例如 C:\Users\YourName）。这些工具有意使用 Unix 风格的路径（如 .local/share），即使在 Windows 上也是如此，以实现跨平台一致性，而不是使用 Windows 原生路径（如 %APPDATA%）。

Windows 特定配置

Tokscale 将其配置存储在：

• 配置文件：%USERPROFILE%\.config\tokscale\settings.json
• 缓存：%USERPROFILE%\.cache\tokscale\
• Cursor 凭证：%USERPROFILE%\.config\tokscale\cursor-credentials.json

会话数据保留

默认情况下，一些 AI 编码助手会自动删除旧的会话文件。为了保留您的使用历史以便准确跟踪，您可以禁用清理功能或延长清理周期。

Claude Code

默认：30 天清理周期

在 ~/.claude/settings.json 中添加以下内容：

{
  "cleanupPeriodDays": 9999999999
}

设置一个极大的值（例如 9999999999 天 ≈ 2700 万年）可以有效禁用清理功能。

Gemini CLI

默认：已禁用清理（会话永久保存）

如果您启用了清理功能并希望将其禁用，请移除或在 ~/.gemini/settings.json 中将 enabled 设置为 false：

{
  "general": {
    "sessionRetention": {
      "enabled": false
    }
  }
}

或者设置一个极长的保留期限：

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "9999999d"
    }
  }
}

Codex CLI

默认：无自动清理（会话永久保存）

Codex CLI 没有内置的会话清理功能。~/.codex/sessions/ 中的会话将无限期保留。

注意：目前有一个关于此功能的公开请求：#6015

OpenCode

默认：无自动清理（会话永久保存）

OpenCode 也没有内置的会话清理功能。~/.local/share/opencode/storage/ 中的会话将无限期保留。

注意：请参阅 #4980

数据来源

OpenCode

位置：~/.local/share/opencode/opencode.db（v1.2+）或 storage/message/{sessionId}/*.json（旧版）

OpenCode 1.2+ 将会话存储在 SQLite 数据库中。Tokscale 会优先从 SQLite 读取数据，如果遇到旧版本则回退到旧版 JSON 文件。

每条消息包含：

{
  "id": "msg_xxx",
  "role": "assistant",
  "modelID": "claude-sonnet-4-20250514",
  "providerID": "anthropic",
  "tokens": {
    "input": 1234,
    "output": 567,
    "reasoning": 0,
    "cache": { "read": 890, "write": 123 }
  },
  "time": { "created": 1699999999999 }
}

Claude Code

位置：~/.claude/projects/{projectPath}/*.jsonl

JSONL 格式，包含助手消息及用量数据：

{"type": "assistant", "message": {"model": "claude-sonnet-4-20250514", "usage": {"input_tokens": 1234, "output_tokens": 567, "cache_read_input_tokens": 890}}, "timestamp": "2024-01-01T00:00:00Z"}

Codex CLI

位置：~/.codex/sessions/*.jsonl

基于事件的格式，包含 token_count 事件：

{"type": "event_msg", "payload": {"type": "token_count", "info": {"last_token_usage": {"input_tokens": 1234, "output_tokens": 567}}}}
``。

### Gemini CLI

位置：`~/.gemini/tmp/{projectHash}/chats/*.json`

会话文件包含消息数组：
```json
{
  "sessionId": "xxx",
  "messages": [
    {"type": "gemini", "model": "gemini-2.5-pro", "tokens": {"input": 1234, "output": 567, "cached": 890, "thoughts": 123}}
  ]
}

Cursor IDE

位置：~/.config/tokscale/cursor-cache/（通过 Cursor API 同步）

Cursor 数据会使用您的会话令牌从 Cursor API 获取，并本地缓存。运行 tokscale cursor login 进行身份验证。有关设置说明，请参阅 Cursor IDE 命令。

OpenClaw

位置：~/.openclaw/agents/*/sessions/sessions.json（同时扫描旧路径：~/.clawdbot/、~/.moltbot/、~/.moldbot/）

指向 JSONL 会话文件的索引文件：

{
  "agent:main:main": {
    "sessionId": "uuid",
    "sessionFile": "/path/to/session.jsonl"
  }
}

包含模型变更事件和助手消息的会话 JSONL 格式：

{"type":"model_change","provider":"openai-codex","modelId":"gpt-5.2"}
{"type":"message","message":{"role":"assistant","usage":{"input":1660,"output":55,"cacheRead":108928,"cost":{"total":0.02}},"timestamp":1769753935279}}

Pi

位置：~/.pi/agent/sessions/<encoded-cwd>/*.jsonl

带有会话头和消息条目的 JSONL 格式：

{"type":"session","id":"pi_ses_001","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/tmp"}
{"type":"message","id":"msg_001","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-3-5-sonnet","provider":"anthropic","usage":{"input":100,"output":50,"cacheRead":10,"cacheWrite":5,"totalTokens":165}}}

Kimi CLI

位置：~/.kimi/sessions/{GROUP_ID}/{SESSION_UUID}/wire.jsonl

带有 StatusUpdate 消息的 wire.jsonl 格式：

{"type": "metadata", "protocol_version": "1.3"}
{"timestamp": 1770983426.420942, "message": {"type": "StatusUpdate", "payload": {"token_usage": {"input_other": 1562, "output": 2463, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "chatcmpl-xxx"}}}

Qwen CLI

位置：~/.qwen/projects/{PROJECT_PATH}/chats/{CHAT_ID}.jsonl

格式：JSONL — 每行一个 JSON 对象，每个对象包含 type、model、timestamp、sessionId 和 usageMetadata 字段。

令牌字段（来自 usageMetadata）：

• promptTokenCount → 输入令牌
• candidatesTokenCount → 输出令牌
• thoughtsTokenCount → 推理/思考令牌
• cachedContentTokenCount → 缓存输入令牌

Roo Code

位置：

• 本地：~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json
• 服务器（尽力而为）：~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json

每个任务目录还可能包含 api_conversation_history.json 文件，其中包含用于模型/代理元数据的 <environment_details> 块。

ui_messages.json 是一个 UI 事件数组。Tokscale 只统计：

• type == "say"
• say == "api_req_started"

text 字段是包含令牌/成本元数据的 JSON：

{
  "type": "say",
  "say": "api_req_started",
  "ts": "2026-02-18T12:00:00Z",
  "text": "{\"cost\":0.12,\"tokensIn\":100,\"tokensOut\":50,\"cacheReads\":20,\"cacheWrites\":5,\"apiProtocol\":\"anthropic\"}"
}

Kilo

位置：

• 本地：~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json
• 服务器（尽力而为）：~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json

Kilo 使用与 Roo Code 相同的任务日志结构。Tokscale 应用相同的规则：

• 只统计 ui_messages.json 中的 say/api_req_started 事件
• 从 text JSON 中解析 tokensIn、tokensOut、cacheReads、cacheWrites、cost 和 apiProtocol
• 在可用时，从同级的 api_conversation_history.json 中丰富模型/代理元数据

Mux

位置：

• ~/.mux/sessions/{WORKSPACE_ID}/session-usage.json

Mux 将每会话的累计令牌用量存储在 session-usage.json 文件中。每个文件包含一个 byModel 映射，其中按模型细分了以下用量：

• input、cached（缓存读取）、cacheCreate（缓存写入）、output、reasoning
• 模型名称采用 provider:model 格式（例如 anthropic:claude-opus-4-6），Tokscale 会去除提供商前缀以识别模型
• 子代理的用量会由 Mux 自动汇总到父会话中，因此不会出现重复计算

Kilo CLI

位置：~/.local/share/kilo/kilo.db

Kilo CLI 将会话数据存储在一个类似于 OpenCode 的 SQLite 数据库中。每条消息记录都包含按消息细分的令牌用量（输入、输出、缓存读写、推理），并注明模型和提供商。

Crush

位置：通过 $XDG_DATA_HOME/crush/projects.json 发现的项目级 SQLite 数据库（备用：~/.local/share/crush/projects.json）

Crush 将用量存储在每个项目的 SQLite 数据库（crush.db）中。Tokscale 只从根会话中导入会话级别的总成本，因为 Crush 不提供可靠的每条消息或每模型的令牌核算。记录显示为 model=session-total，且无令牌细分。

Synthetic (synthetic.new)

Synthetic 的用量是通过对现有代理会话文件进行后处理检测到的。当消息使用 hf: 模型 ID 或合成提供商（synthetic、glhf、octofriend）时，这些消息会被重新归因于 synthetic。

Tokscale 还会检查位于 ~/.local/share/octofriend/sqlite.db 的 Octofriend SQLite 数据库，并在可用时解析带有令牌信息的记录。

定价

Tokscale 会从 LiteLLM 的定价数据库 获取实时定价。

动态回退：对于 LiteLLM 中尚未收录的模型（例如最近发布的模型），Tokscale 会自动从 OpenRouter 的 endpoints API 获取定价。这确保您可以从模型的原始提供商处获得准确的定价（例如 Z.AI 对 glm-4.7 的定价），而无需等待 LiteLLM 更新。

Cursor 模型定价：对于尚未出现在 LiteLLM 或 OpenRouter 中的非常新发布的模型（例如 gpt-5.3-codex），Tokscale 会包含硬编码的定价，该定价来源于 Cursor 的模型文档。这些覆盖会在所有上游来源之后、模糊匹配之前被检查，因此一旦实际的上游定价可用，它们就会自动生效。

缓存：定价数据会以 1 小时 TTL 的形式缓存在磁盘上，以便快速启动：

• LiteLLM 缓存：~/.cache/tokscale/pricing-litellm.json
• OpenRouter 缓存：~/.cache/tokscale/pricing-openrouter.json（缓存来自受支持提供商的模型的原始定价）

定价包括：

• 输入令牌
• 输出令牌
• 缓存读取令牌（折扣价）
• 缓存写入令牌
• 推理令牌（适用于 o1 等模型）
• 分级定价（超过 20 万令牌）

贡献

欢迎贡献！请按照以下步骤操作：

1. 克隆仓库并创建分支
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试 (cd packages/core && bun run test:all)
5. 提交更改 (git commit -m '添加惊人功能')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开拉取请求

开发指南

• 遵循现有代码风格
• 为新功能添加测试
• 根据需要更新文档
• 保持提交内容专注且原子化

致谢

• 感谢 ccusage、viberank 和 Isometric Contributions 提供的灵感
• 感谢 Ratatui 提供的终端 UI 框架
• 感谢 Solid.js 提供的响应式渲染能力
• 感谢 LiteLLM 提供的定价数据
• 感谢 napi-rs 提供的 Rust/Node.js 绑定
• 感谢 github-contributions-canvas 提供的 2D 图表参考

许可证

MIT © Junho Yeo

如果你觉得这个项目很有趣，请考虑给它点个赞 ⭐，或者 在 GitHub 上关注我，一起加入这场旅程吧（目前已有 1,100 多位小伙伴同行）。我几乎全天候都在编程，并且定期发布令人惊叹的作品——你的支持绝不会白费。

Tokscale 快速上手指南

Tokscale 是一款高性能命令行工具（CLI）和可视化仪表盘，专为追踪和分析多个 AI 编程助手（如 Claude Code, Cursor, OpenCode 等）的 Token 消耗与成本而设计。它基于 Rust 构建，提供极速的数据处理和精美的终端界面（TUI）。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：支持 macOS, Linux, Windows (WSL 推荐)。
• 运行时环境（二选一）：
  • Node.js (推荐 LTS 版本)
  • Bun (速度更快，推荐)
• 可选依赖：如果你需要从源码构建或进行二次开发，需要安装 Rust 工具链。

提示：国内用户若下载 Bun 或 Node 较慢，可配置相应的国内镜像源加速安装。

安装步骤

Tokscale 无需复杂的全局安装，推荐使用 npx 或 bunx 直接运行最新版本。

方式一：使用 npx (Node.js 用户)

npx tokscale@latest

方式二：使用 bunx (Bun 用户 - 推荐)

bunx tokscale@latest

轻量模式

如果只需要表格数据而不需要交互式界面，可以添加 --light 参数：

npx tokscale@latest --light

说明：首次运行时，工具会自动下载包含原生 Rust 核心的二进制文件，无需手动编译。

基本使用

安装完成后，Tokscale 会自动扫描你本地常见的 AI 工具数据目录（如 ~/.claude, ~/.cursor, ~/.opencode 等），并计算 Token 用量和预估费用。

1. 启动交互式界面 (TUI)

直接在终端输入运行命令即可进入主界面：

bunx tokscale@latest

界面功能概览：

• Overview (概览)：查看总消耗、成本及贡献热力图。
• Models (模型)：按模型维度统计 Token 使用情况。
• Daily (每日)：查看每日消耗趋势。
• Stats (统计)：详细的输入/输出/缓存/推理 Token 细分数据。

操作方式：

• 使用 方向键 或 鼠标 进行导航。
• 按 q 或 Esc 退出。

2. 查看支持的平台

Tokscale 默认支持以下主流 AI 编程工具的数据读取（只需它们已在本地产生过数据）：

3. 常用命令示例

• 查看帮助信息：

  bunx tokscale@latest --help
  

• 仅查看特定平台数据 (例如只看 Claude Code)：

  bunx tokscale@latest --platform claude
  

• 导出数据为 JSON：

  bunx tokscale@latest --export json
  

• 提交数据到排行榜 (可选)： 如果你想参与社区排名或生成个人年度总结，可以提交匿名化数据：

  bunx tokscale@latest submit
  

4. 价格计算

Tokscale 内置了来自 LiteLLM 的最新定价数据，支持分层定价和缓存 Token 折扣计算。价格数据会缓存在本地（有效期 1 小时），确保查询速度飞快且准确。

现在，运行 bunx tokscale@latest 开始监控你的 AI 开发能耗吧！