Measure the real value and cost of Claude Code usage from local logs.
subscription_value: Report surviving lines, waste (rework/failures/context bloat), cost by activity, and per-file detail for all projects or a specific project.
limit_breakdown: Analyze what drives the 5-hour and weekly rate limits—burn per window, fitted model weights, every change point, and weekly windows.
chat_share: Estimate how much of the shared rate limit was eaten by claude.ai chat/mobile (which leave no local logs), with weekly, per-window, and data-source coverage views.
current_limits: Query Anthropic for current 5-hour/weekly/per-model limits plus the per-product breakdown (Claude Code/chat/Cowork), and optionally record a sample for later analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claudeusage Am I getting my money's worth from my Claude subscription?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Measure whether your Claude subscription is actually paying off — from local logs, with no upload and no Git integration.
한국어 문서: README.ko.md — the Korean version is the working notebook, with the full measurements and the mistakes we made getting there.
On a subscription you don't pay per token, so nothing tells you whether you are using it well. Existing personal tools count how much you used. That is the wrong number: burning tokens in circles scores high. Meta ran an internal leaderboard like that and shut it down — people started idling AI to climb it.
Tools that measure quality do exist, but they are all built for teams: they need your Git repo, your PRs, your issue tracker. That leaves a gap.
Team tools | claudeusage | |
Who is measured | A lead measures the team | You measure yourself |
Needs | Git repo, PRs, tracker | One local log directory |
Measures | Return on team investment | Whether your subscription pays off |
Price | SaaS or self-hosted | Free, runs locally |
Git-based tools track code with git blame, so anything you never committed is invisible to them. This reconstructs the edit history itself, so experiments and code you rewrote before committing still count.
Related MCP server: claudeusage-mcp
Lines that survived. Every edit is folded in time order, so only what was still there at the end of the session counts. Code you rewrote three turns later drops out by itself. You cannot game the score by idling.
Waste, in money. Rework, failures and rejections add up to 4.1% here. Money spent because conversations got long: 12.3%. So the useful advice is not "make fewer mistakes" — it's "start fresh conversations more often."
What the rate limit actually eats. Your real constraint is the limit gauge, not dollars. Cache reads are most of the cost but weigh about 1/70 of fresh input against the limit. Saving money and saving limit are different skills.
What chat ate. Limits apply to the whole account, so claude.ai chat and the mobile app drain the same gauge — while leaving no local trace. Any log-only tool undercounts. This one subtracts what the logs explain from what the gauge actually did, and checks that estimate against the per-product breakdown Anthropic returns.
Requires Python 3.9+ (standard library only, no dependencies) and macOS for the live-limit tool.
git clone https://github.com/syk8015/claudeusage && cd claudeusage
./install.sh # package + skill + MCP server (user scope)
claude mcp list # claudeusage … ✔ Connectedinstall.sh installs the package (trying uv, pipx, pip, then a dedicated venv — modern Pythons block system installs), drops the Claude Code skill in ~/.claude/skills/, and registers the MCP server. ./install.sh --uninstall reverses it.
That gives you the claudeusage command and the claudeusage-mcp server. A PyPI release (pip install claudeusage) is built and tested but not published yet.
Claude Code shows your limit gauge and throws it away — nothing stores it. claudeusage limit and claudeusage chat need that history, so a collector has to sit on your status line. Add this to ~/.claude/settings.json:
"statusLine": {
"type": "command",
"command": "claudeusage statusline --print"
}Already have a status line you like? Drop --print and pipe into it — the collector passes the JSON straight through:
"command": "claudeusage statusline | bash ~/.claude/my-statusline.sh"Nothing edits your settings for you — your status line is yours.
claudeusage value and claudeusage usage work right away, with no collector. The limit analysis gets useful after a few days of samples.
Samples live in ~/.claudeusage/ (override with CLAUDEUSAGE_DATA). Running from a clone keeps using the repo's own data/ directory, so an existing history is never orphaned.
Ask in plain language — "am I getting my money's worth?", "why is my limit draining so fast?", "how much of my limit did chat eat?" The skill picks the right tool.
MCP tool | What it answers |
| Lines that survived, waste, cost by activity |
| What drives the 5-hour and weekly limits |
| How much of the limit chat ate |
| Limits right now, plus the per-product breakdown |
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 checkersOutput is English by default. CLAUDEUSAGE_LANG=ko switches it to Korean.
Three sources, each blind in a different way, so they are merged:
Source | Gives | Blind when |
Status line samples ( | Gauge readings with reset times | Claude Code isn't running |
Claude desktop app history | Gauge readings every 15 min | The app isn't running |
OAuth usage endpoint | Per-product truth (Claude Code / chat / Cowork) | Only the current weekly window |
The estimate is a subtraction: chat = gauge rise − what local logs explain. The "explained" part uses per-model weights fitted by claudeusage limit, fitted only on windows with no suspected off-log usage — otherwise chat usage inflates the weights and the estimator goes blind to itself.
Two things had to be corrected, both found by running it on real data:
Half-observed windows tilt the subtraction. If the gauge is only watched for part of a window, the rise reads low while the attributed cost reads high. Only windows with a known reset time, watched from zero, are counted (55 of 107 here).
Log-derived cost runs 6–9% low — background calls never reach the logs. Left alone, that gap becomes fake chat usage. Each window is scaled against the status line's own total.
claudeusage check verifies 15 invariants, including an anchor: a real window where chat was confirmed by hand.
The per-product breakdown is ground truth, but only one weekly window of it has been collected so far. Calling the estimator "validated" needs more.
Model weights come from 5–7 clean windows for the less-used models. Direction is solid; the exact multiplier still moves.
Limit gauges are integers. One change point is coarse; answers are averages over ~1,200 of them.
claudeusage usage reads Claude Code's credentials from the macOS keychain, sends them only to api.anthropic.com, and never prints or stores them. What it records is an allowlist: timestamp, limit kind, model name, percentage, reset time, product shares.
Other vendors. Merging ChatGPT and Gemini exports was the original plan for "combine coding and chat"; this covers the Claude account only. That part is about subscription money rather than rate limits, so it needs its own metrics.
Listed on the official MCP registry as io.github.syk8015/claudeusage.
Also listed on Glama.
MIT
Asks Anthropic what is left right now: the 5-hour, weekly and per-model (Fable) limits, plus the per-product breakdown (Claude Code / chat / Cowork). Reads Claude Code's credentials from the macOS keychain and sends them only to api.anthropic.com. record=true appends one sample to data/usage-log.jsonl — the breakdown covers only the current weekly window and is gone once that window rolls over, so it is worth recording now and then.
| Name | Required | Description | Default |
|---|---|---|---|
| record | No | Append one sample to the log file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it well. It discloses the security-sensitive behavior (reads credentials from macOS keychain, sends them only to api.anthropic.com), the side effect of record=true appending to a log file, and the data volatility of the breakdown (gone after the weekly window rolls over). This is rich, useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every clause earns its place: purpose first, then security, then the record side effect and its rationale. It is front-loaded with the primary function and well-structured, though slightly dense with the parenthetical breakdown details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single optional parameter and no output schema, the description covers the essentials: what is queried, security behavior, side effects, and data lifecycle. The only gap is that it does not describe the shape of the return value, but given no output schema exists and the tool is simple, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single record parameter, so the baseline is 3. The description goes beyond the schema by explaining what record=true accomplishes (appends one sample to data/usage-log.jsonl) and why it is worth setting — the breakdown is lost after the window rolls over. This adds genuine value beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Asks Anthropic what is left right now' — covering 5-hour, weekly, and per-model (Fable) limits plus a per-product breakdown (Claude Code / chat / Cowork). This is specific and clear about scope. It doesn't explicitly name siblings like limit_breakdown to differentiate itself, but the per-product breakdown detail implies a distinct scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or reference to alternatives. The only usage hint is 'worth recording now and then', which implies periodic use but does not explain when to choose this tool over subscription_value, limit_breakdown, or chat_share. No exclusions or alternative routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works out what drives the 5-hour and weekly rate limits. On a subscription the real constraint is the limit gauge, not dollars. Cache reads are most of the cost but weigh about 1/70 of fresh input against the limit, so saving money and saving limit are different skills. view: windows (burn per window), fit (per-model weights and multipliers), steps (every change point), weekly (7-day windows).
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Which angle to report | windows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It does add useful interpretive context, like cache reads weighing 1/70 of fresh input and the distinction between saving money and saving limit, which informs how to interpret results. But it does not explicitly state read-only behavior, side effects, or how the computation is performed, leaving gaps for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact four-sentence paragraph with no filler. It front-loads the core purpose, then provides contextual insight, and finally maps each view option. The sentence about cache weights and money-vs-limit earns its place by explaining a nuance that affects interpretation, though it could arguably be more concise without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single optional parameter and no output schema, the description is largely complete: it states what the tool does, the available views, and even offers conceptual background on rate limit behavior. It does not describe the output shape, which an agent might need to parse, but the simplicity of the tool keeps this a minor gap rather than a crippling one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% because the parameter 'view' has an enum and a description, so the baseline is 3. The description adds significant meaning by defining each view value: windows (burn per window), fit (per-model weights and multipliers), steps (every change point), weekly (7-day windows). This goes well beyond the schema's generic 'Which angle to report' and helps an agent select the correct value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Works out what drives the 5-hour and weekly rate limits.' It then enumerates the four view modes, making the tool's purpose unmistakable and clearly distinct from siblings like current_limits or subscription_value, which sound like they report current values rather than explain their drivers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool is useful—when trying to understand what drives rate limits rather than just the limits themselves—and provides helpful domain context ('On a subscription the real constraint is the limit gauge, not dollars'). However, it never explicitly contrasts this tool with sibling tools or states when not to use it, so guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measures what Claude Code usage actually left behind. Edits are folded in time order, so only lines that survived to the end of the session count — code rewritten three turns later drops out. view: summary (surviving lines and cost), waste (rework, failures, rejections and context bloat priced in dollars), mix (cost by activity), files (per-file detail). scope=project requires project_path.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Which angle to report | summary |
| scope | No | all = every project, project = one project | all |
| project_path | No | Absolute path of the project, when scope=project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It transparently explains the key algorithmic behavior (edits folded in time order, only surviving lines count) and describes what each view reports (e.g., waste includes rework, failures, rejections, context bloat). It does not mention output format or side effects, but for a read-only analysis tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: leads with the core concept, uses bold for emphasis, and lists views compactly. No redundant sentences; every phrase adds information about behavior, scope, or view options.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, no-output-schema tool, the description covers the purpose, key behavior, all views, and the scope constraint. It lacks explicit return format or edge cases, but the views imply what is returned. Given the sibling set, the description is sufficient for an agent to decide when and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining each view's meaning (summary = surviving lines and cost; waste = rework, failures, rejections, context bloat in dollars; etc.) and reiterating the scope/project_path constraint. This enriches the schema descriptions significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific purpose: measures surviving Claude Code usage (edits that persist to session end) and cost. This clearly distinguishes it from sibling tools about limits and sharing. The description defines the core metric ('survived to the end of the session') and lists the view modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains internal usage conditions: each view's purpose and the scope=project requirement (project_path). However, it does not explicitly contrast with sibling tools (limit_breakdown, chat_share, current_limits) or state when this tool is preferred over them. The context implies it's for value/waste assessment, but no explicit when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0chat_sharecurrent_limitslimit_breakdownsubscription_valueScored across 4 tools
subscription_value and current_limits are clearly distinct, and the detailed descriptions make limit_breakdown and chat_share distinguishable as mechanism analysis vs. cross-product attribution. An agent skimming names alone could conflate the two rate-limit tools, but the descriptions resolve the ambiguity.
All four names are lowercase snake_case compound nouns, which gives the set a consistent shape. The convention is not verb_noun like typical action tools, and chat_share is a bit ambiguous semantically, but there is no jarring style mixing.
Four tools is compact but each one earns its place: local usage value, limit drivers, chat attribution, and live limit status. The server scope is narrow enough that this feels well-scoped rather than thin.
The set covers the core workflows: measuring local value, explaining limit consumption, attributing non-local usage, and querying current limits. The main gap is that current_limits can record samples to a log, but no tool reads that history back for time-series analysis.
Exact Claude API cost calc with real cache economics, plus a tiktoken-misuse scanner.
Anthropic organization usage and cost reporting through an admin API key connected by the user.
OpenAI organization usage and cost reporting through an admin API key connected by the user.
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
