ccusage vs Claude Code Usage Monitor: 32 Tools, Two Numbers

ccusage told me this Mac mini spent $3,261.24 on Claude Code between 28 July and 6 September. The bill for that period was two months of a $200 Max subscription. Both numbers are correct, and the distance between them is why "ccusage vs Claude Code Usage Monitor" is a query people type: the two most-starred tools answer different questions, and neither README says so on the first screen.

I collected 32 Claude Code usage monitors from GitHub, read each README for what the tool actually reads, and ran the biggest one against my own transcripts next to my own counting script. What follows is the classification, the comparison, and the one number none of the local tools can give an unattended machine.

What I collected

Ten GitHub searches on 6 September ("claude code usage", "ccusage", "claude usage monitor", "claude code cost" and six variants, 50 results each, sorted by stars) returned 435 distinct repositories. I kept the 67 with 30 or more stars and a usage-related name or description, read the READMEs of the 45 most-starred by hand, and dropped 13 that are not monitors: a context compressor, a behaviour enforcer, a leaderboard, two token reducers, Anthropic's own monitoring guide, and a few whose data source the README never states. That leaves 32, and every one reads one of six sources.

Source the tool reads	Tools	What it can show	Examples (stars)
~/.claude/projects/**/*.jsonl	12	Tokens per message, model, project; dollars at list price	ccusage (18,382), phuryn/claude-usage (2,200), claude-lens (245), claudelytics (88), cclens (87)
api.anthropic.com/api/oauth/usage via the stored OAuth token	8	5-hour and 7-day percentage, reset times	Clawdmeter (2,145), CodeZeno monitor (446), claude-code-usage-bar (364), claudecodeusage (336)
Both of the above	6	Both, in one window	Claude-Code-Usage-Monitor (8,674), ccseva (806), CCMeter (115)
Status line rate_limits JSON	2	The same percentages, no credential access	claude-codex-usage-dashboard (171), ccburn (95)
OpenTelemetry export	2	Tokens, estimated cost, tool events	claude-code-otel (495), lumo (147)
claude.ai settings page, or a proxy	2	Percentage by scraping; tokens by intercepting	mnapoli/claude-usage-bar (116), claude-meter (93)

The JSONL group parses the transcripts Claude Code writes to disk, sums the usage block on each assistant message, and multiplies by a price table. ccusage, with 18,382 stars and 381,310 npm downloads in the 30 days to 29 August, is most of the group's gravity. Their output is a token count and a dollar figure. None of them can see a rate limit, because the transcript does not contain one.

The OAuth group does something else. It reads the token Claude Code stores at login (the macOS Keychain item Claude Code-credentials, or ~/.claude/.credentials.json elsewhere) and calls the usage endpoint that /usage inside Claude Code calls. Back comes the five-hour and seven-day utilisation as a percentage, computed on Anthropic's side across every device on the account. Clawdmeter, an ESP32 desk display with 2,145 stars, and seven others read only this and never see a token count.

Six tools read both, and the biggest is the one in the search query. Claude-Code-Usage-Monitor (8,674 stars, pip install claude-monitor) parses JSONL as its primary source and puts the OAuth endpoint behind an opt-in --api flag its README labels experimental. Two tools skip credentials altogether and consume the rate_limits object Claude Code passes to a status line script; two are OpenTelemetry stacks, one opens a hidden browser window to scrape the claude.ai settings page, and one is a pass-through proxy in front of the API.

The dollar figure is a counterfactual

Here is what the JSONL group produced on this machine. ccusage 20.0.20 through npx, monthly --json and daily --json, no other flags:

Period	ccusage cost	Note
2026-07	$167.41	From 28 July; older transcripts are gone
2026-08	$2,545.30	Includes $62.25 of Codex sessions
2026-09	$548.53	To 6 September
Total	$3,261.24	34 days with data across 41 calendar days

Three things in that table are not in the headline. Version 20 reads every agent CLI it finds, so the August line carries $62 of Codex sessions from ~/.codex; the README lists 18 CLIs it unifies. The dollar column is API list price applied to a subscription: the official costs page says the session cost in /usage "is intended for API users" and that for Max and Pro subscribers "the session cost figure isn't relevant for billing purposes", and ccusage's own cost-modes page says the figure is the transcript's costUSD field when present, otherwise tokens times LiteLLM's price table. On this disk 5 of 2,791 transcript files carry a costUSD at all, so it is the price table. And nine dates in the range have no Claude usage; six of them are the two outages I have already written up, the OAuth expiry from 20 to 24 August and the FileVault lock from 29 August to 1 September. The other three I did not trace.

So the number means "what this would cost on an API key", and it is the one the community argues about. The ccusage thread on Hacker News has a $100 Max subscriber reporting "$600-800/mo in terms of usage", and the CodeBurn thread in April has its author correcting a reader who took "$1,400/week" as money spent: "not $1,400 out of pocket, thats the API equivalent cost of the tokens. I am on the $200/month Max plan". For my 7 August to 6 September window the ratio is $2,650 of Claude-only list price against $200 billed, thirteen to one, the arithmetic of my subscription versus API cost post with a different tool multiplying.

Checking ccusage against my own count

I had a reason to trust ccusage less than its star count. When I first read these JSONL files in July, Claude Code was writing several lines per assistant message with the same message.id and the same usage block, so a naive sum overcounts. ccusage issue #888 is about the opposite failure, undercounting when one request is logged twice, and the cchubber README says outright that the files "contain ~50% duplicates from session resume". So I wrote a forty-line script that walks every transcript on the disk, keeps assistant records timestamped 7 August to 6 September in Korea time, and sums usage three ways.

Method	Records	Cache read tokens	Output tokens
Raw sum of every usage line	39,933	4,058.8M	56.48M
Last record per message.id	16,574	1,720.1M	20.90M
Last per message.id + requestId	16,574	1,720.1M	20.90M
ccusage 20.0.20, Claude models only	n/a	1,722.8M	20.94M

58.5 percent of the usage-bearing lines are duplicates, a little above cchubber's estimate, and summing them raw inflates cache reads 2.36 times. Deduplicating on message.id alone gives the same 16,574 records as the id-plus-request pair, because no request spans two message ids in these files. Against that baseline ccusage lands within 0.16 percent on cache reads and output and 0.4 percent on input, which I read as the same dedup with a timezone edge somewhere. The token count under the dollar figure is right. It is the price that does not apply.

The number none of them can give my fleet

What stops this machine is not a dollar. It is the five-hour window reaching 100 percent, after which the day's remaining scheduled slots fail until the reset, which is why I built an auto-continue at the usage limit in August. A JSONL tool cannot see that window. Claude-Code-Usage-Monitor's answer is to estimate it: its README table sets the five-hour allowance at 19,000 tokens for Pro, 88,000 for Max 5x and 220,000 for Max 20x, and defaults to a "P90-based" custom plan that learns a limit from your last 192 hours. The same README's usage examples say "Pro plan (~44,000 tokens)" three screens further down. On the launch thread in June 2025 the author said "machine learning to understand your actual token limits, not hardcoded solution" was coming; the repository's last commit is 27 June 2026, ten weeks before this post, and the plan table is still there. My own measurement points the other way. In the 5-hour limit reset post, 128 of 128 reset times sat on a ten-minute grid, and the same afternoon a 29.2M-token session survived while a 21.2M one was refused. I have never found a token sum that predicts when the window closes.

The OAuth group reads the real percentage, and Claude Code now hands the same object to any status line script for nothing: rate_limits.five_hour.used_percentage, seven_day, and since v2.1.251 spend_limit, for Pro and Max subscribers after the first API response of a session. If you run Claude Code interactively, a status line script is the cheapest correct monitor on this list, and Claude-Code-Usage-Monitor's own --statusline flag exists to capture it. I did not run any of the OAuth tools here, and that was a decision, not an omission. They work by reading the Keychain item I found two copies of in the login post, and I am not going to hand a third-party binary the credential that keeps an unattended machine logged in, on the machine it keeps logged in. Headless claude -p does not run a status line either, so this fleet's only honest signal stays the /usage check each slot already makes, as described in the check usage limit post.

Which one to run

If the question is "how much would this cost on an API key", or "which project or model eats my tokens", ccusage is the answer and the count is right; read its dollar column as a counterfactual. If the question is "how close am I to being cut off", a JSONL tool cannot know and Claude-Code-Usage-Monitor's default mode is guessing; use its --statusline mode, ccburn, a status line script of your own, or one of the eight OAuth-only monitors, and read the credentials section of the README first. Nothing in the 32 is wrong about what it measures. Eighteen measure a price, sixteen measure the wall, and the search query treats them as rivals because both call it usage.

FAQ

Is the ccusage cost real money on a Claude Max plan?

No. ccusage multiplies the token counts in your local transcripts by API list prices from LiteLLM's table, so on a Pro or Max subscription the figure is what the same usage would have cost on an API key. On this machine it reported $2,650 for a 30-day window billed at $200, and the official costs page says the equivalent figure inside /usage "isn't relevant for billing purposes" for subscribers.

What is the difference between ccusage and Claude Code Usage Monitor?

ccusage reads transcript JSONL files and reports tokens and list-price cost, with no view of rate limits. Claude Code Usage Monitor reads the same files and estimates your five-hour limit from hardcoded per-plan token allowances or a P90 fit of your last eight days; its experimental --api flag and its --statusline mode read the real percentage instead, and those are the modes to use if the limit is what you want.

How do I check my Claude Code usage limit without a third-party tool?

Run /usage inside Claude Code, which shows the five-hour and seven-day bars for Pro and Max plans, or configure a status line script: Claude Code passes rate_limits.five_hour.used_percentage and seven_day.used_percentage to it as JSON on stdin after the first API response of a session. Neither route requires giving anything access to your stored OAuth token.

Sources and method: the census is ten gh search repos queries run on 6 September 2026 (435 unique repositories), filtered to 67 with 30 or more stars and a usage-related name or description; I read the 45 most-starred READMEs by hand and classified 32 by the sentence that names what each reads, dropping 13 that are not usage monitors. Star counts are from the GitHub API that afternoon; the npm figure is api.npmjs.org for 31 July to 29 August. The ccusage numbers come from npx -y ccusage@latest (20.0.20) on this Mac mini's ~/.claude/projects and ~/.codex; the comparison script deduplicates assistant records by message.id over 2,791 transcript files. Quotes are from the Claude-Code-Usage-Monitor README at its 27 June 2026 commit, the Claude Code costs and status line documentation, and Hacker News comments via the Algolia items API. I did not run any tool that reads the OAuth credential, so that group is classified from documentation only; Reddit threads were not used because they redirect to login for me.