ai-token-usage-lite

v0.2.0

Published

16 days ago

Local token usage dashboard for Codex, Claude Code, and Cursor.

0High
0Medium
0Low

gap-l

ai token usage dashboard codex claude-code cursor

AI Token Usage Lite

本地版多工具 AI 用量看板。当前支持：

Codex、Claude Code：Token 用量统计 + 轮次级 Skills / MCP / 耗时明细
Cursor：参照 tokentracker-cli，通过 Cursor 用量 CSV / API 统计真实 Token，并区分命中缓存与缓存写入

v0.2.0 更新

Cursor 接入改为参照 tokentracker-cli 的 CSV / API 真实 Token 口径。
总览移除“估算 Token”，只展示精确 Token 统计。
缓存输入拆分为“命中缓存”和“未命中缓存”。
移除 WorkBuddy / Credits 相关统计展示。

支持平台：

macOS
Windows

要求：

Node.js >= 20
本机已安装并使用过至少一种已支持工具（Codex、Claude Code、Cursor）
Claude / Codex 扫描本地日志；Cursor 会读取本地登录态并请求 Cursor 用量 CSV API，也可用 CURSOR_USAGE_CSV_PATH 指定已导出的 CSV

通过 npx 使用

npx ai-token-usage-lite@latest serve --port 7790

打开看板：

http://127.0.0.1:7790

常用命令：

npx ai-token-usage-lite@latest sync
npx ai-token-usage-lite@latest serve --port 7790
npx ai-token-usage-lite@latest status --json
npx ai-token-usage-lite@latest doctor
npx ai-token-usage-lite@latest export --format csv

默认数据来源：

macOS / Linux
- Claude Code：~/.claude/projects
- Codex：~/.codex/sessions
- Cursor：~/Library/Application Support/Cursor/User/globalStorage/state.vscdb（macOS）或 ~/.config/Cursor/User/globalStorage/state.vscdb（Linux）
- 聚合结果：~/.ai-token-usage-lite/usage.json
Windows
- Claude Code：%USERPROFILE%\\.claude\\projects
- Codex：%USERPROFILE%\\.codex\\sessions
- Cursor：%APPDATA%\\Cursor\\User\\globalStorage\\state.vscdb
- 聚合结果：%USERPROFILE%\\.ai-token-usage-lite\\usage.json

如需覆盖默认目录，可通过以下方式指定：

CLI 参数：--home、--data-dir
环境变量：AI_TOKEN_USAGE_LITE_DATA_DIR、CLAUDE_CONFIG_DIR、CLAUDE_PROJECTS_DIR、CODEX_HOME、CODEX_SESSIONS_DIR、CURSOR_APP_DIR、CURSOR_USAGE_CSV_PATH

团队内推荐用法

npx ai-token-usage-lite@latest serve --port 7790

如果需要只刷新本地聚合结果：

npx ai-token-usage-lite@latest sync

如果需要排查为什么没有统计到数据：

npx ai-token-usage-lite@latest doctor

本地开发与发布检查

npm test
npm run pack:check
npm run smoke:npx
npm run release:check
node bin/ai-token-usage-lite.js sync
node bin/ai-token-usage-lite.js serve --port 7790

发布到公开 npm：

npm login
npm run release:check
npm run publish:public

说明：

仓库内已固定 npm cache 到 ./.npm-cache，避免受全局 ~/.npm 权限问题影响。
smoke:npx 会先打 tarball，再用 npm exec --package=<tgz> 验证公开安装路径对应的 CLI 入口。

统计内容

总览：消耗总 Token、输入 Token、输出 Token、命中缓存、未命中缓存、对话次数。
Provider 面板：展示各工具来源的精确 Token 占比。
按来源：Codex、Claude Code、Cursor 的精确用量分布。
按模型：不同模型的 Token 和对话次数。
按日期：每日用量趋势。
按项目：从本地日志里能识别到的项目引用。
按 Skills：每个 skill 的调用轮次、总耗时、总 Token、平均 Token、平均耗时。
最近对话轮次：每轮对话的来源、模型、耗时、Skills、输入/输出/缓存/消耗总 Token。

各工具统计方式

Claude Code / Codex：基于本地日志里的 usage 字段做 Token 聚合。
Cursor：优先读取 CURSOR_USAGE_CSV_PATH 指定的 CSV；未指定时读取 Cursor 本地登录态，请求 export-usage-events-csv?strategy=tokens，按 Input (w/o Cache Write)、Input (w/ Cache Write)、Cache Read、Output Tokens 计算真实 Token。

Token 口径

输入 Token：发送给模型的上下文消耗，通常包括你的请求、历史上下文、工具结果、系统提示等。
输出 Token：模型生成回答、工具调用参数、推理输出等产生的消耗。
命中缓存：命中上下文缓存的输入 Token。它仍然属于模型上下文规模，但计费口径通常会和普通输入不同，具体以各工具或模型服务商为准。
未命中缓存：缓存写入 Token，对应 Cursor CSV 中 Input (w/ Cache Write) - Input (w/o Cache Write)。
消耗总 Token：当前看板主口径，按 输入 + 输出 + 命中缓存 + 未命中缓存 计算，与 tokentracker-cli 对 Cursor 的 token 标准化逻辑一致。

Skills 识别说明

Skill 识别分为：
- explicit：对话文本中明确出现正在使用某个 skill，例如 Using \superpowers:brainstorming`，或中文表达如“按 diagnose的路子看”“用tdd` 先补测试”。
- inferred：从读取 SKILL.md 等本地 skill 文件路径推断；除了结构化的 file_path 字段，也会从工具命令参数里的 .../SKILL.md 路径推断。
- superpowers 路径会规范化为 superpowers:<name>，例如 .../superpowers/skills/test-driven-development/SKILL.md 会识别为 superpowers:test-driven-development。
- 对于 imagegen、caveman 这类单词型 skill，工具会优先从会话中的 ### Available skills inventory 动态学习，减少对硬编码名单的依赖。

隐私边界

工具只落地聚合后的统计信息：来源、模型、时间桶、项目引用、Token 数、轮次耗时和 Skill 名称。不会保存 prompt、assistant response、工具调用参数、工具结果或文件内容。Cursor 接入会使用本地登录态请求 Cursor 官方用量 CSV API。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme