Claude Usage

claudeusage

根据本地日志衡量 Claude 订阅是否物有所值，无需上传数据，也无需集成 Git。

状态：已完成（2026 年 10 月）。 这是一个个人研究项目。项目可用并会继续公开，但不再维护，问题也可能无人回复。以下测量结果来自一个账号，为期约五周（2026-09-01 → 10-08）。

한국어 문서: README.ko.md — 韩语版本是工作笔记本，记录了完整的测量结果，以及我们在过程中犯下的错误。

为什么要做这个项目

订阅服务不按 token 收费，因此没有什么能告诉你使用得是否合理。大多数个人工具统计的是你用了多少。但这个数字不对：原地打转地消耗 token 也能得高分。Meta 曾运行过类似的内部排行榜，后来将其关闭——人们开始让 AI 空转来提高排名。一些免费的分析工具确实会查找浪费，但它们按 API 美元计价；而订阅服务真正会耗尽的是限额指示器，它对 token 的计量方式大不相同（见下文）。

确实有衡量质量的工具，但它们都是为团队打造的：需要你的 Git 仓库、PR 和问题跟踪器。这就留下了一个空缺。

	团队工具	claudeusage
衡量对象	负责人衡量团队	你衡量自己
所需条件	Git 仓库、PR、跟踪器	一个本地日志目录
衡量内容	团队投资回报	订阅是否物有所值
价格	SaaS 或可自托管	免费，在本地运行

基于 Git 的工具通过 git blame 跟踪代码，因此任何从未提交的内容对它们来说都是不可见的。本工具会重建编辑历史本身，因此实验性修改，以及提交前重写的代码也会计入。

衡量内容

保留下来的代码行。 按时间顺序合并每次编辑，因此只有会话结束时仍然存在的内容才会计入。三轮之后被重写的代码会自动剔除。你无法靠空转刷分。

以金额计的浪费。 返工、失败和拒绝在这里合计为 4.1%。对话变长造成的花费：12.3%。两者都是按 API 美元计算的。重新开始对话是否真的能节省限额尚未得到证实——新对话需要重新读取上下文，因此要付出成本——所以请把 12.3% 视作参考，而非保证。

限额实际消耗在哪里。 真正的限制因素是限额指示器，而非金额。缓存读取占大部分成本，但相对于新输入，它对限额的权重约为 1/70。省钱和省限额是两种不同的技能。

聊天消耗了多少。 限额适用于整个账号，因此 claude.ai 聊天和移动应用也会消耗同一个限额指示器，却不会留下本地记录。任何只分析日志的工具都会低估。本工具会从限额指示器的实际变化中减去日志能够解释的部分，并将估算结果与 Anthropic 返回的按产品划分明细进行核对。

一个账号的数据说明了什么

测量数据来自约 52,000 条状态行样本和 33,000 条记录的请求。每个倍率都注明了其除数。

• 缓存读取相对于新输入，每个 token 对限额的权重约为 1/70（按 token 计算，通过 107 个五小时窗口拟合）。它们占所有 token 的 97%，也是大部分金额成本的来源，但最终限额消耗在输出、新输入和缓存读取之间的占比相近。基于金额的浪费报告会高估缓存读取的影响。
• 周限额变化只会显示在限额指示器上。 周涨幅 ÷ 五小时涨幅从 0.099（40 个窗口，09-01→13）变为 0.125（41 个窗口，09-15→10-02）：1.26×。Anthropic 公布的变化（额外额度 +50% → +25%）预测为 1.20×。这只能确认已公布的变化；单个账号的数据误差约为 ±3%。
• 每个输出 token 的模型权重，以 Opus 5 = 1 计： Fable 5.1 ≈ 3.8×，Opus 4.8 ≈ 1.7×（可用的干净窗口较少；变化方向可靠，具体数值不确定）。
• Claude Code 之外的聊天约占限额的 10%，与 Anthropic 返回的按产品划分明细中的 8–9% 相符。

安装

需要 Python 3.9+（仅使用标准库，无依赖），实时限额工具还需要 macOS。

git clone https://github.com/syk8015/claudeusage && cd claudeusage
./install.sh                   # package + skill + MCP server (user scope)
claude mcp list                # claudeusage … ✔ Connected

install.sh 会安装此软件包（依次尝试 uv、pipx、pip，然后使用专用虚拟环境——新版 Python 会阻止系统级安装），将 Claude Code 技能放入 ~/.claude/skills/，并注册 MCP 服务。运行 ./install.sh --uninstall 可撤销这些操作。

这样你就能使用 claudeusage 命令和 claudeusage-mcp 服务。本项目尚未发布到 PyPI；请从克隆的仓库安装。

使用限额工具前还需一步

Claude Code 会显示你的限额仪表，但不会保存数据。claudeusage limit 和 claudeusage chat 需要这些历史记录，因此必须在状态栏上运行一个收集器。将以下内容添加到 ~/.claude/settings.json：

"statusLine": {
  "type": "command",
  "command": "claudeusage statusline --print"
}

已经有自己喜欢的状态栏？删掉 --print，并将输出管道传给它——收集器会原样传递 JSON：

"command": "claudeusage statusline | bash ~/.claude/my-statusline.sh"

不会有任何程序替你修改设置——你的状态栏由你做主。

claudeusage value 和 claudeusage usage 可立即使用，无需收集器。收集几天样本后，限额分析才会更有用。

样本保存在 ~/.claudeusage/ 中（可通过 CLAUDEUSAGE_DATA 更改）。从克隆的仓库运行时，会继续使用仓库自身的 data/ 目录，因此现有历史记录不会丢失。

在 Claude 中使用

用日常语言提问——“我的订阅费花得值吗？”、“为什么我的限额耗得这么快？”、“聊天用掉了多少限额？”技能会选择合适的工具。

MCP 工具	可回答的问题
subscription_value	保留下来的代码行数、浪费情况、各项活动的成本
limit_breakdown	哪些因素影响 5 小时限额和每周限额
chat_share	聊天用掉了多少限额
current_limits	当前限额，以及按产品细分的情况

在 Shell 中使用

claudeusage value --all              # all projects
claudeusage value --project PATH --waste
claudeusage limit                    # limit burn per 5-hour window
claudeusage limit --fit              # fit: what the gauge weighs
claudeusage chat                     # chat's share, weekly
claudeusage usage                    # live limits + product breakdown
claudeusage check                    # both consistency checkers

默认以英文输出。设置 CLAUDEUSAGE_LANG=ko 可切换为韩文。

聊天用量估算的工作原理

该估算结合了三个来源，每个来源都有各自的盲区：

来源	提供的数据	以下情况会有盲区
状态栏样本（claudeusage statusline）	带重置时间的仪表读数	Claude Code 未运行时
Claude 桌面应用历史记录	每 15 分钟一次的仪表读数	应用未运行时
OAuth 用量端点	按产品划分的真实用量（Claude Code / 聊天 / Cowork）	仅限当前每周周期

估算通过相减得出：chat = 仪表读数上升值 − 本地日志所能解释的部分。“可解释”部分使用 claudeusage limit 拟合的各模型权重；拟合时只使用没有疑似日志外用量的窗口，否则聊天用量会抬高权重，使估算器无法识别自身的偏差。

通过真实数据运行后，发现并修正了两个问题：

1. 只观测到部分时段的窗口会使相减结果偏斜。 如果只在某个窗口的一部分时间内监测仪表，读数增幅会偏低，而归因成本会偏高。现在只统计重置时间已知、且从零开始监测的窗口（此处为 107 个窗口中的 55 个）。
2. 从日志推算的成本低了 6–9%——后台调用从未写入日志。如果不作处理，这一差额就会被当成虚假的聊天用量。现在会根据状态栏自身的总量对每个窗口进行缩放。

claudeusage check 会验证 15 项不变量，其中包括一个锚点：一个经人工确认聊天用量的真实窗口。

准确性说明

• 按产品细分的数据是事实依据，但只收集了其中两个每周时间窗口的数据。要称估算器为“已验证”，还需要更多数据。
• Opus 5.5 的按 Token 拟合不稳定：使用 40 个时间窗口时，输出 Token 权重会降至零，这显然不合理。输入之间存在相关性；按美元计算的数值比按 Token 计算的数值更稳定。
• Claude Code 默认会在 30 天后删除对话日志（cleanupPeriodDays）。超过这一时限的仪表样本会丢失所需的请求数据，因此限额拟合只能查看最近一个月的数据。
• 较少使用的模型，其权重仅根据 5–7 个干净的时间窗口计算得出。趋势可靠，但具体倍率仍会变化。
• 限额仪表读数是整数。一个变点的精度较粗；结果是约 1,200 个变点的平均值。
• claudeusage usage 会从 macOS 钥匙串读取 Claude Code 的凭据，只将其发送到 api.anthropic.com，绝不会打印或存储这些凭据。它记录的内容仅限于允许列表：时间戳、限额类型、模型名称、百分比、重置时间和产品占比。

范围

仅支持 Claude。最初计划是合并 ChatGPT 和 Gemini 导出数据，以“结合编码和聊天”；但我们有意放弃了这个计划。此处的所有内容都是围绕一个 Claude 账号及其速率限制构建的。

注册表

已列入官方 MCP 注册表，名称为 io.github.syk8015/claudeusage。

也已列入 Glama。

许可证

MIT