Purpose
This is a personal research project for answering a question common among subscription users: is my Claude subscription actually worth it? In subscription mode you don't pay per token, so there is no ready-made metric telling you whether you are using it efficiently. Most personal tools only count "how much was used," but this article points out that this is the wrong number: spinning in place and burning tokens can also score high (which is why Meta's internal leaderboard was shut down). A few free analyzers look for waste, but price it in API dollars; under a subscription, what actually runs out is the limit table, and limits weight tokens completely differently from dollars. Quality tools aimed at teams in turn require Git repositories, PRs, and issue trackers, making them unsuitable for individuals. This tool fills that gap: it reconstructs edit history from local logs, so uncommitted experiments and code rewritten before committing can also count.
Main capabilities
- Surviving lines of code: merge each edit in chronological order, and only code that still exists at the end of the session counts; code rewritten after three turns is automatically excluded, so you can't farm points by idling.
- Waste measured in money: in the sample, rework, failures, and rejections together account for 4.1%; money spent because conversations got longer accounts for 12.3%. Both are API dollar figures. "Whether starting a new conversation actually saves limits" has not been proven (a new conversation has to pay to reread context), so 12.3% can only be treated as a hint, not a promise.
- What rate limits actually eat up: the real constraint is the limit table rather than dollars. Cache reads account for the bulk of cost, but relative to limits they are about 1/70 of fresh input (per token, based on a fit over 107 five-hour windows). Saving money and saving limits are two different skills.
- Chat consumption: limits apply to the entire account, and claude.ai chat and the mobile app consume the same limit table, yet leave no local trace. This tool estimates chat usage with "limit table increase − the part explainable by local logs," and cross-checks it against the per-product breakdown returned by Anthropic.
Data observations from a single account
Based on a sample of about 52,000 status lines and 33,000 logged requests: cache reads are about 1/70 of fresh input relative to limits; cache reads account for 97% of all tokens and most dollar cost, but limits ultimately split roughly evenly among output, fresh input, and cache reads. Waste reported in dollars would overestimate them. Weekly limit changes can be seen from the limit table: weekly increase ÷ five-hour increase went from 0.099 (40 windows, 09-01→13) to 0.125 (41 winmouth, 09-15→10-02), i.e. 1.26×; the change announced by Anthropic (bonus +50% → +25%) is predicted at 1.20×, which merely confirms the announced change, with a single-account error of about ±3%. Per output token model weight, with Opus 5 = 1: Fable 5.1 ≈ 3.8×, Opus 4.8 ≈ 1.7× (few clean windows, direction reliable, exact value uncertain). Chat outside Claude Code accounts for about 10% of the limit, consistent with the 8–9% per-product breakdown returned by Anthropic.
How to use
Requires Python 3.9+ (standard library only, no dependencies); the rate-limit real-time tool requires macOS. install.sh installs the package (trying uv, pipx, pip in order, and finally using a dedicated venv, because modern Python blocks system installation), places the Claude Code skill into ~/.claude/skills/, and registers the MCP server. ./install.sh --uninstall undoes it. After installation you get the claudeusage command and the claudeusage-mcp server. There is no PyPI release; you need to install from a cloned repository.
The rate-limit tool requires an extra step: Claude Code displays the limit table but discards it, and does not store it. claudeusage limit and claudeusage chat need that history, so a collector must be placed in the status line, configured in ~/.claude/settings.json; if you already have a status line you like, you can remove --print and pipe into it, and the collector will pass the JSON through directly. It will not edit the settings for you. claudeusage value and claudeusage usage work without the collector; rate-limit analysis only becomes useful after accumulating a few days of samples. Samples are stored in ~/.claudeusage/ (can be overridden with CLAUDEUSAGE_DATA). Running from the cloned directory will continue to use the repository's own data/ directory and will not orphan existing history.
It can be used from Claude in natural language (e.g. "Is my money well spent?" "Why is the limit dropping so fast?" "How much of the limit is chat eating up?"), and the skill will choose the right tool. It can also be used from the shell, with English output by default, CLAUDEUSAGE_LANG=ko Switch to Korean.
How chat estimation works
All three sources have blind spots, so they are used in combination. The estimation formula is: chat = limit table increase − the portion explainable by local logs. The "explainable" portion uses per-model weights fitted by claudeusage limit, and is fitted only on windows with no suspicious gaps in log usage; otherwise chat usage would inflate the weights and blind the estimator to itself. Both corrections were discovered from real data: semi-observed windows distort the subtraction (only windows with a known reset time and observed from zero are counted, 55 out of 107); log-derived costs run 6–9% low because background calls never enter the logs — otherwise that gap would turn into phantom chat usage, scaled per window by the status line's own total. claudeusage check verifies 15 invariants, including an anchor from one manually confirmed chat window.
Limitations and accuracy
The per-product breakdown is ground truth, but only two weekly windows have been collected; calling the estimator "validated" needs more data. The per-token fit for Opus 5.5 is unstable: 40 windows push the output token weight to zero, which cannot be correct. The inputs are correlated, and dollar figures are more stable than token figures. Claude Code deletes conversation logs by default after 30 days (cleanupPeriodDays), and earlier limit-table samples lose the required request data, so the limit fit can only see the most recent month. The less-used model weights come from 5–7 clean windows; the direction is reliable, but the exact multiplier still fluctuates. The limit table is integer-valued, a single change point is coarse, and the answer is an average over about 1,200 change points. claudeusage usage reads Claude Code credentials from the macOS keychain and sends them only to api.anthropic.com, and never prints or stores them; what it records is an allowlist: timestamp, limit type, model name, percentage, reset time, and product share. Only Claude is supported; the original plan to merge ChatGPT and Gemini exports to "combine coding and chat" was deliberately abandoned. The project is listed in the official MCP registry under the ID io.github.syk8015/claudeusage, and is also listed on Glama. The project status is complete (October 2026); it is a personal research project that runs and remains public, but is no longer developed, and issues may go unanswered.
