open-index/open-npm huggingface dataset:
npm package: @qingflow-tech/ai-token-usage-cli
Description: CLI to aggregate local token usage across AI coding tools
Latest version: 0.2.0

# ai-token-usage

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

当前内置支持：

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

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

- `Gemini CLI`
- `Aider`
- `Roo`
- `Goose`
- `Qwen Code`

## 安装与运行

本地直接运行：

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

通过 `npm scripts` 运行：

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

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

```bash
npm link
ai-token-usage
```

## 常用命令

默认汇总：

```bash
ai-token-usage
```

按天查看：

```bash
ai-token-usage --report daily
```

按周查看：

```bash
ai-token-usage --report weekly
```

统计后提交到 Qingflow：

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

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

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

查看最耗 token 的会话：

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

只看部分工具：

```bash
ai-token-usage --tools claude,codex
```

输出 JSON：

```bash
ai-token-usage --json
```

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

```bash
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 覆盖默认根目录，或者添加额外的“只发现不解析”目录：

```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."
    }
  ]
}
```

运行方式：

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

## 说明

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