AI Usage

ai-usage-mcp

问问你的编码 Agent 花了你多少钱——钱都花到哪里去了。 一个 MCP 服务，直接从 Claude Code、OpenCode 和 Codex CLI 已写入你电脑的数据中获取答案。数据不会上传，也不需要 API 密钥或账户。

> Where are my tokens going, and what should I change?
> Where did this session lose its prompt cache?
> Which of my projects is getting more expensive, day by day?
> What would last week have cost on Sonnet instead of Opus?

它有三项功能，是阅读对话记录无法做到的：

• 保留你的历史记录。 Claude Code 会在 30 天后删除对话记录（cleanupPeriodDays）。系统会在每轮对话被发现时将其复制到本地 SQLite 数据库，因此即使源文件已删除，上个季度的数据仍会保留—— 还可以将两台机器的数据合并为一个总数。
• 找出缓存失效的位置。 缓存令牌才是花费的大头——占开发机器上所有令牌的 94.7%。cache_health 可以找到会话丢失缓存前缀、不得不付费重新写入整个上下文的轮次，指出可能的原因（切换模型、空闲时间超过 5 分钟 TTL、编辑了 CLAUDE.md），并计算额外费用。
• 验证数字的准确性。 Claude Code 会为每个内容块写入一行 JSONL，每行都重复相同的 usage 对象，因此对行求和会使所有数值膨胀 2–3 倍。 ai-usage verify 会用_第二套独立实现_重新读取两个来源；这套实现与数据收集器不共享任何归约代码，并将结果与自己的数据库进行差异比较。

$ ai-usage verify

== claude-code ==
  MATCH    claude JSONL, deduped by stop_reason line (independent rule)
  INFO     claude JSONL, naive sum of every usage line (NOT used -- shows the double count)
           delta:  cache-read 990,824,820 ...

RESULT: every client reconciles exactly against at least one independent read of its source.

此外还支持：Pro/Max 套餐限额——Claude Code 报告的 5 小时和每周使用率，由状态行保存，并预测达到 100% 的时间；以及 counterfactual_cost（按另一模型的费率计算这些精确令牌的费用）、包含运行速率和预测的预算、按项目 × 日期划分的数据，以及 CSV/JSON 导出。它支持 Claude Code 和 OpenCode，并提供十二个 MCP 工具、资源、提示词，以及一个可打印工具返回相同文本的调试 CLI。

绝不捏造数字。 如果数据来源没有记录某项数据，系统会将其报告为不可用，而不是零。

$ ai-usage stats --today
Usage summary -- today (local time)
Subagent/sidechain turns: INCLUDED (3 main + 1 subagent turns).

Records: 4   Sessions: 2

Tokens (all clients):
  Input:        1,871
  Output:       16,909 (16.9K)
  Cache read:   2,452,000 (2.45M)
  Cache write:  37,300 (37.3K)
  Reasoning:    2,600
  Total:        2,508,080 (2.51M)

  Cost (reported by client, exact): $0.41  [1 records]
  Cost (estimated, API-equivalent):  $1.50  [3 records]

By client:
  claude-code  --  3 records, 1 sessions
    Cache read:   2,238,000 (2.24M)
    Total:        2,280,001 (2.28M)
    Cost (estimated, API-equivalent):  $1.50  [3 records]

  opencode  --  1 records, 1 sessions
    Cache read:   214,000 (214.0K)
    Total:        228,079 (228.1K)
    Cost (reported by client, exact): $0.41  [1 records]

一条命令即可试用

无需配置，也无需创建账户。它会读取 Claude Code 和 OpenCode 已写入这台机器的数据：

npx -y -p ai-usage-mcp ai-usage report

首次运行时会将你的历史记录复制到本地数据库，这需要几秒钟。报告会评估最近 7 天的情况，说明令牌的去向，并列出需要调整的内容。要向你的 Agent 提出上面那样的问题，请将其安装为 MCP 服务。

ai-usage 还是 ccusage？

ccusage 是一款成熟且出色的工具：它支持的 Agent 多得多，而且它统计的 Claude Code 令牌数量与本软件包完全一致——在开发机器上针对 2026 年 9 月 21–25 日的数据，按每种令牌类别、每天逐项与 ccusage 20.0.26 核对。若要快速查看多个 Agent 的报告，请使用它。

如果你想要当前对话记录报告无法提供的功能，请使用本工具：保留超过 Claude Code 30 天清理期限的历史记录、发现并计算缓存失效的费用、反事实定价、预算、跨维度明细、将报告费用与估算费用分开，以及通过 verify 对照第二次读取结果来验证令牌总数。

安装

需要 Node.js 22.13+。无需编译器、构建工具或特定版本的 npm： 存储使用 Node 内置的 node:sqlite，从 22.13.0 起无需启用标志。没有必需的本机依赖。

_{better-sqlite3 仍是面向 Node 版本低于此要求的主机的可选回退方案。它并非必需——如果无法构建，npm 会跳过它，服务仍可运行。}

Claude Code

作为插件使用——推荐。 在 Claude Code 中运行以下两条命令：

/plugin marketplace add MohitBansal321/ai-usage-mcp
/plugin install ai-usage@ai-usage-mcp

这样会配置 MCP 服务，_并且_将三个提示词安装为真正的斜杠命令—— /ai-usage:daily-review、/ai-usage:why-was-today-expensive、/ai-usage:project-cost—— 而大多数客户端仅通过 MCP 提示词无法提供这些命令。如果安装摘要显示 Run /reload-plugins to activate.，请运行该命令。在 shell 中执行等效操作的命令是 claude plugin marketplace add MohitBansal321/ai-usage-mcp。

_{插件将 npx -y ai-usage-mcp 声明为其服务，因此服务本身仍通过 npm 获取，并在每次冷启动时重新解析。因此，更新插件和更新服务彼此独立——请参阅 更新。}

也可以作为普通 MCP 服务使用，如果你不想添加插件市场。无需预先安装任何内容——npx 会按需获取：

claude mcp add ai-usage -s user -- npx -y ai-usage-mcp

在原生 Windows（非 WSL）上，请改用 cmd /c 包装：

claude mcp add ai-usage -s user -- cmd /c npx -y ai-usage-mcp

_{原因：在 Windows 上，npx 是 npx.cmd，而 MCP TypeScript SDK 会使用 shell: false 启动服务。Node 无法以这种方式执行 .cmd 文件——其文档指出，这类文件“可以通过将 shell 选项设为 … 的 child_process.spawn() 调用，或通过启动 cmd.exe 并将 .bat 或 .cmd 文件作为参数传入”来调用。cmd /c 就是第二种形式。以下所有基于 SDK 的客户端都适用，不只是 Claude Code。}

-s user 会让所有项目都能使用此服务。移除它，则只会将服务添加到当前项目。然后在 Claude Code 中运行 /mcp，确认连接成功。

{
  "mcpServers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

{
  "mcpServers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

OpenCode

opencode mcp add ai-usage       # choose a local server, command: ai-usage-mcp

或者将其添加到 ~/.config/opencode/opencode.jsonc：

{
  "mcp": {
    "ai-usage": {
      "type": "local",
      "command": ["npx", "-y", "ai-usage-mcp"],
    },
  },
}

运行 opencode mcp list 确认。

Codex CLI

codex mcp add ai-usage -- npx -y ai-usage-mcp

Codex 使用记录从 ~/.codex/sessions（或 $CODEX_HOME）读取。Codex 不记录费用，因此其费用是等效 API 费用估算；如果定价表中没有相应模型，则无法提供估算。 这项支持刚推出，目前仅通过两个会话验证；运行 ai-usage verify 可在你的环境中检查。

其他 MCP 客户端

Cursor、Google Antigravity、Windsurf 和 Claude Desktop 使用相同的 npx -y ai-usage-mcp 配置块，只有配置文件不同。你提问时使用的客户端不必是你要统计的客户端：在 Cursor 中提问，仍然可以获取 Claude Code 的数据。路径和详情请参阅 docs/INSTALL.md。

调试 CLI

MCP 服务无需安装。若要将 ai-usage CLI 也添加到 PATH：

npm install -g ai-usage-mcp
ai-usage status

或者无需安装即可运行：

npx -y -p ai-usage-mcp ai-usage stats --today

**Windows：**不再需要特定版本的 npm。过去会导致安装失败的 node-gyp 错误来自原生依赖项 better-sqlite3；该依赖项现在是可选的，在 Node 22.13+ 上不会使用。如果 npm 仍报告该依赖项的构建失败，那只是跳过了可选依赖项，并非安装失败——ai-usage status 会显示 SQLite driver: node:sqlite，一切都能正常工作。

更新

npx -y ai-usage-mcp 会在每次冷启动时重新解析版本，因此重启客户端即可获取新版本。全局安装会固定版本：npm install -g ai-usage-mcp@latest。 ai-usage status 和 MCP 服务都会告知你当前版本是否落后。 docs/INSTALL.md 说明了每种安装方式的要求，并介绍了版本检查会发送的一条请求。

兼容性

这两种源格式都是内部格式，且没有版本号，因此客户端更新可能会改变它们。以下是已检查的内容和检查方式：

“已验证”是指 ai-usage verify 将每种 token 类型与对客户端自身数据的独立重新读取结果逐一比对，且完全匹配（715 MB 的 Claude Code 转录记录、251 MB 的 opencode.db，以及 Codex 的会话记录）。它比较的是同步读取的同一批字节，因此仍在写入的会话不会被判定为不匹配。 如果客户端更新导致数据采集失效，ai-usage status 会警告客户端仍在写入数据，但没有新回合到达。

向它提问

连接后，可以使用自然语言提问：

How many tokens have I used today?
Show my usage for this session.
Which model consumed the most tokens?
How much did Claude Code cost me today?
Show all usage from the last 7 days.
Which repository is my spend going to?
Break my last 7 days down day by day.

MCP 工具

从这里开始：usage_report

对于 Pro、Max 或 Team 计划，价格是固定的，所以“花了多少钱”不是该问的问题。更有用的问题是，你的限额有多少用在了实际工作上。usage_report（或 ai-usage report）默认会回答过去 7 天的情况：

Verdict: High waste -- a large share of this usage re-read or rebuilt old context.

Where it went (share of usage, weighted by API-equivalent price):
   37.1%  re-reading context above 100k tokens (1,021 turns; largest context 735.2K)
   10.2%  rebuilding a lost cache (12 times, 12 after an idle break)

What to change:
  1. Compact earlier. ... 5 session(s) grew past 200k tokens of context ...
  2. Don't resume a session that has gone cold. ...

Heaviest sessions:
   47.7%  Admission transfer tariff services and roles linking  [development, claude-code]

它仅根据令牌数量衡量两种浪费。上下文延续之所以存在，是因为每条消息都会重新发送整个对话，因此在 300k 上下文中进行一轮操作，就要重新读取 300k 个令牌才能迈出一步；超过 100k 的部分，就是如果早点压缩上下文便不会继续携带的内容。缓存重建指缓存前缀丢失、整个上下文被重新写入的轮次（检测方式与 cache_health 相同）。会话名称由客户端提供的标题和运行时所在的 git 分支组成；如果 Claude Code 没有记录分支，则显示为 no branch（通常是因为会话在 git 仓库之外启动）。我们并不声称这两种浪费都完全可以避免；这些占比只是用量去向的参考，并不代表精确的限额消耗：Anthropic 没有公布订阅限额如何计算不同类型令牌的权重。

计划限额、状态行和上下文警告

Claude Code 不会将 Pro/Max 的 5 小时和每周限额写入任何文件，但会将它们传递给状态行。如果你使用 ai-usage statusline 作为状态行，就会记录这些限额、重置时间，以及按当前速度达到 100% 的时间。旁边还会显示今日费用、会话缓存命中率和中断情况；plan_usage 则可在对话中提供相同信息。ai-usage hook 会在提示词发送前发出警告，提醒会话上下文已变得代价高昂，不适合再次发送。ai-usage status 会说明每项功能是否已启用。设置方法和详情见docs/STATUS_LINE.md。

资源和提示词

可以通过 @ 提及将三种资源加入对话，而不必请求调用工具：

在支持显示提示词的客户端中，三个提示词会以斜杠命令的形式出现：

每个提示词都会指定要调用的工具，并附带报告值与估算值的费用规则，避免改写后的摘要悄悄混合两种费用口径。

大多数客户端不会显示 MCP 提示词，因此 Claude Code 插件也将相同的三个提示词作为真正的斜杠命令提供（/ai-usage:daily-review 等）。这是通过两个界面提供的同一项功能，并且有测试确保两处列表不会出现差异。

调试 CLI

使用相同的服务层，只是前端不同，因此两者永远不会出现结果不一致的情况。

ai-usage report      # start here: verdict, where usage went, what to change (last 7 days)
ai-usage status      # collectors, data stores, db path, record counts, last sync, hooks on/off
ai-usage sync        # run the collectors
ai-usage stats       # totals   (--today, --days N, --since/--until)
ai-usage models      # per-model
ai-usage clients     # per-client
ai-usage projects    # per-project  (--limit N)
ai-usage sessions    # recent sessions
ai-usage session ID  # one session in detail
ai-usage daily       # per-day breakdown
ai-usage counterfactual  # these tokens on another model (--target-models a,b)
ai-usage verify      # re-read the sources and diff them against the local database
ai-usage hook        # Claude Code UserPromptSubmit hook: warns when context is large

为任意命令添加 --json，即可获得机器可读的输出。

更多内容见 docs/CLI.md：

• 按多个项目、模型或客户端缩小范围
• 导出 CSV 和 JSON
• 在 Claude Code 清理 30 天数据后保留历史记录，并合并两台机器的数据
• 缓存成本分析
• 配合运行速率和预测设置预算
• 为脚本和警报提供单个值和退出码
• 按项目 × 天细分、趋势、时段比较和分页

费用如何报告

费用绝不会是一个混合在一起的数字。每个数值都标明了依据：

此外，每份报告都会统计模型没有对应定价表条目的记录，因此可以区分真正免费的模型和从未有人定价的模型。客户端自行报告费用时，会将未定价模型的费用准确记录为 $0，否则这看起来就和免费完全一样：

opencode  --  6,841 records, 280 sessions
  Cost (reported by client, exact): $0.48  [6,841 records]
  No estimate attempted for 6,813 record(s) -- no price in table builtin-2026-10-23 for
  that model: big-pickle, gpt-5.5, z-ai/glm-5.2 and 16 more. Any $0 above covers only what
  was reported, not those records.

在 --json 和 MCP structuredContent 中，这些字段分别是 cost.unpricedRecords 和 cost.unpricedModels。如果调用方没有提供定价模型列表，这两个字段会直接省略，而不是设为 0： “未询问”不等于“没有”。

Claude Code 显示的是“API 等效预估费用”——这些 token 按 Anthropic API 标价计算的费用。如果你订阅了 Claude Pro 或 Max，每次请求的边际费用为 $0，这个数字并非你的实际支出。它适合用于比较工作负载，但不能用于核对账单。

报告费用和预估费用会分行显示，不应相加。

缓存 token 会按实际价格计费，不会与输入 token 混为一谈：

• 缓存读取按输入费率的 0.1× 计费；Opus 5.5 / Sonnet 5.5 为 0.05×，Fable 5.1 / Mythos 5.1 为 0.025×
• 缓存写入按 1.25×（5 分钟 TTL）或 2×（1 小时 TTL）计费

两种缓存写入 TTL 会分开跟踪，因为实际使用中两者都很常见——在开发此工具所用的机器上，2,720 万个缓存写入 token 中有 1,800 万个使用了 1 小时 TTL，因此对费率取平均会大幅低估费用。

哪些模型随附价格、新版软件包发布后模型如何自动定价，以及如何自行添加或修正价格，请参阅 docs/PRICING.md。

为什么此处的令牌计数值得信赖

这两种源格式都是内部格式，且没有文档说明；如果不加甄别地照单全收，两者都有可能导致结果严重偏差。此工具对此做了以下处理：

• Claude Code 每个内容块写一行，并重复写入同一个 usage 对象，其中的 output_tokens 是累计值。把这些行相加会让每项数值膨胀 2.15×-3.05×，具体取决于令牌类别（实测数据）。记录按 requestId + message.id 去重，并对每个字段取最大值。
• usage.iterations[] 已包含在顶层总计中，绝不会重复累加。
• 子 Agent 轮次存储在单独的文件中（<session>/subagents/…），而不是通过 isSidechain 标记区分——实际上该标记从未设置。此工具根据路径进行分类。
• <synthetic> 不是模型，因此会被排除。
• OpenCode 的 session 汇总列可能已过时。 这些列是缓存的汇总值；在开发机器上，4 个会话共丢失了 545,977 个输入令牌。此工具改为读取 message 粒度的数据，且独立的 part 表逐字节地佐证了这些数据。OpenCode 2.x 会将该粒度的数据写入 session_message，且不再写入 part 行，因此无法通过第二张表佐证较新的轮次。
• 不同客户端的推理令牌含义不同。 在 Claude Code 中，思考令牌_包含在_ output_tokens 中；在 OpenCode 中，reasoning 与 output 同级。因此总计会按客户端分别计算，不会重复计算推理令牌。
• 缓存令牌的数量远超其他令牌（缓存读取 800M 对比输入 24K，这一比例确实如此），因此始终会分别列出各类令牌，而不会合并为一个总数。

运行 ai-usage verify 即可自行检查。该命令会使用_第二种独立实现_重新读取这两个数据源；它与采集器不共享任何归并代码，并将结果与数据库进行比较：

== opencode ==
  MATCH    opencode.db message grain (what we collect)
  MATCH    opencode.db part/step-finish grain (independent corroboration)
  INFO     opencode.db session rollup grain (what `opencode stats` headline shows)
           delta:  input -545,977 ...

== claude-code ==
  MATCH    claude JSONL, deduped by stop_reason line (independent rule)
  INFO     claude JSONL, naive sum of every usage line (NOT used — shows the double count)
           delta:  cache-read 990,824,820 ...

RESULT: every client reconciles exactly against at least one independent read of its source.

verify 会先同步，然后只比较共同截止时间之前的活动——我们读取数据时，两个客户端都会继续向各自的存储中追加内容，因此若不设截止时间，源数据总会比数据库多出几个请求。

它只比较源数据中仍保留的会话。两个客户端都会删除各自的历史记录——Claude Code 默认会在 30 天后移除记录稿（由 cleanupPeriodDays 控制）——而本地数据库会保留已采集的数据，因此一个月后，数据库中合理地会有比源数据更多的内容。这些会话会单独列在 Retained, not compared 行，而不会被计为不匹配。任何在数据库中缺失的源记录仍会导致检查失败，因为源数据一侧不会缩小范围。

子 Agent 轮次

默认包含，因为它们确实会产生费用。每份报告都会说明是否包含；使用 --no-subagents / includeSubagents: false 可将其排除。session_usage 始终会分别显示主会话和子 Agent 的用量。

哪些内容会保留在你的设备上

所有内容。 你的使用数据绝不会离开设备。

• 不收集遥测数据、不做分析、不报告崩溃，也不会向外发送信息。
• 不进行云同步、不需要账户或 API 密钥——该工具绝不会调用大模型 API。
• 存在两个对外请求，均为普通 GET 请求，用于获取公开文件，不会发送任何使用数据或标识符；每天最多各请求一次，且都可通过 AI_USAGE_NO_UPDATE_CHECK=1 禁用：
  • 更新检查会向 npm registry 查询最新发布版本号 （ai-usage status，以及完成握手后在后台运行的 MCP 服务）；
  • 价格刷新会下载 LiteLLM 的公开价格列表，以便为内置表格之后发布的模型定价 （ai-usage sync，以及完成握手后在后台运行的 MCP 服务）。AI_USAGE_NO_PRICING_REFRESH=1 只会关闭此项。
• 对话内容不会读入数据库。 收集器会提取令牌计数、模型 ID、时间戳、会话 ID 和项目路径。提示词、补全内容、工具输入和文件内容都会被跳过。
• 源数据以只读方式打开。运行中的 OpenCode 不会受到干扰：收集器会通过只读连接打开其数据库，只有在此操作失败时才会回退到临时快照副本（.db + -wal + -shm）。
• 所有内容都存储在一个本地 SQLite 文件中：

~/.local/share/ai-usage-mcp/usage.db          # override with AI_USAGE_DB

删除该文件即可清除该工具掌握的所有信息。

注意：数据库路径会刻意忽略 XDG_DATA_HOME。沙盒启动器（例如 VSCode snap）会导出自己的 XDG_DATA_HOME，这正是开发机器上 OpenCode 历史记录被拆分到两个数据库的原因。MCP 服务和 CLI 必须始终使用同一个文件。

故障排除

docs/TROUBLESHOOTING.md 涵盖以下问题：

• 收集器被报告为不可用
• 数值低于 opencode stats
• 其他数据存储
• /mcp 显示服务失败
• node-gyp 错误
• 没有估算值的模型
• 重新同步后总数发生变化
• 没有新回合到来，但客户端仍在持续写入

开发

npm install
npm run check          # typecheck, lint, format check, build, tests -- what CI runs

分别运行：

npm run typecheck      # tsc, covering src and tests
npm run lint           # eslint (type-aware)
npm run format         # prettier --write
npm run build          # emit dist/
npm test               # collectors, services, formatter, MCP integration, parity, packaging
npm run test:coverage  # with coverage report

架构——最重要的一条规则是：MCP 永远不会知道数据来自何处：

MCP tools ─┐
           ├─> UsageService ─> collectors ─> Claude Code JSONL / OpenCode SQLite
debug CLI ─┘        │
                    └─> local SQLite

业务逻辑位于 src/services/。MCP 处理程序和 CLI 命令都是基于 UsageService 的轻量前端，并通过同一个格式化程序进行呈现。

请参阅 docs/DATA_SOURCES.md，了解两个数据源经过验证的磁盘格式，包括通过检查真实数据发现并纠正的所有问题；有关发布流程，请参阅 docs/PUBLISHING.md。

贡献

欢迎提交问题和拉取请求。本项目有两项特别要求：

1. 绝不捏造数字。 如果某个数据源没有记录某项内容，该项必须显示为不可用，而不是零。
2. 如果你的更改涉及收集器，ai-usage verify 仍必须报告零差值；如果更改涉及对磁盘格式的理解，还必须在同一个更改中更新 docs/DATA_SOURCES.md。这两种数据源格式都是内部格式，且没有版本管理，因此该文件是实际观测结果的唯一记录。

npm run check 会运行 CI 中的所有检查。CONTRIBUTING.md 包含环境设置、项目结构和拉取请求检查清单。

链接

• CHANGELOG.md — 发布历史
• CONTRIBUTING.md — 环境设置、项目结构以及如何提交更改
• docs/DATA_SOURCES.md — 经验证的磁盘格式，以及已证实有误的记录假设
• docs/PUBLISHING.md — 发布流程
• SECURITY.md — 威胁模型和漏洞报告方式

许可证

MIT — 详见 LICENSE。