ai-token-usage

一个可分发的本地 CLI，用来聚合常见 AI 编码工具的本地 token 使用日志。

当前内置支持：

• Claude Code
• Codex
• OpenCode
• Cursor（实验性，只有本地确实落下 token 字段时才会统计出来）

当前会额外扫描但暂不解析：

• Gemini CLI
• Aider
• Roo
• Goose
• Qwen Code

安装与运行

本地直接运行：

node ./bin/ai-token-usage.mjs

通过 npm scripts 运行：

npm run usage
npm run usage -- --report daily --since 2026-04-01
npm run usage -- --report weekly

如果你要把它作为命令分发：

npm link
ai-token-usage

常用命令

默认汇总：

ai-token-usage

按天查看：

ai-token-usage --report daily

按周查看：

ai-token-usage --report weekly

统计后提交到 Qingflow：

export QINGFLOW_SUBMIT_COOKIE='你的 cookie'
export QINGFLOW_SUBMIT_TOKEN='你的 token'
export QINGFLOW_SUBMIT_WSID='你的 wsid'
ai-token-usage --report weekly --submit-qingflow

运行这条命令时，CLI 会先提示“正在统计本地 token 消耗，请稍候...”。如果没有通过 --username 传姓名，会在统计完成后再提示输入姓名，然后继续提交到 Qingflow。

如果不想交互输入名称，也可以直接传：

ai-token-usage --report weekly --submit-qingflow --username lgc

查看最耗 token 的会话：

ai-token-usage --report sessions --limit 15

只看部分工具：

ai-token-usage --tools claude,codex

输出 JSON：

ai-token-usage --json

查看本机发现了哪些工具目录：

ai-token-usage --report discover

参数

• --tools <list>: 逗号分隔，支持 claude,codex,opencode,cursor
• --since <YYYY-MM-DD>: 起始日期，含当天
• --until <YYYY-MM-DD>: 结束日期，含当天
• --report <summary|daily|weekly|sessions|discover>
• --timezone <IANA>: 日维度分组时区
• --limit <n>: session 报表的行数上限
• --config <path>: 可选 JSON 配置文件
• --username <name>: Qingflow 提交时使用的名称
• --submit-qingflow: 统计完成后把“名称 + token 总量”提交到 Qingflow
• --json: 输出 JSON

配置文件

可以用 JSON 覆盖默认根目录，或者添加额外的“只发现不解析”目录：

{
  "tools": {
    "claude": {
      "roots": ["~/.claude", "~/.config/claude"]
    },
    "codex": {
      "roots": ["~/.codex"]
    },
    "opencode": {
      "roots": ["~/.local/share/opencode"]
    }
  },
  "discover": [
    {
      "name": "my-tool",
      "label": "My Tool",
      "roots": ["~/.my-tool"],
      "note": "Detected local data, but no built-in parser is configured for this tool yet."
    }
  ]
}

运行方式：

ai-token-usage --config ./usage.config.json

说明

• Codex 的 cache read 是输入 token 的子集，所以 Total 不会再重复把它加一次。
• Claude Code 和 OpenCode 的 cache 字段按独立列展示，并计入 Total。
• Cursor 适配器会扫描本地 workspaceStorage 数据库，递归寻找 token 相关字段；如果某个 Cursor 版本只存 prompt 历史、不存 token 计数，就不会产生统计结果。
• Qingflow 提交支持通过 QINGFLOW_SUBMIT_COOKIE、QINGFLOW_SUBMIT_TOKEN、QINGFLOW_SUBMIT_WSID 覆盖默认提交配置。
• 这个脚本依赖各工具是否真的在本地落下可解析日志；如果工具只暴露远端账单或本地格式不稳定，就只能先做发现，不能保证统计准确。