See what Claude Code actually costs you with ccusage — then decide how to pay
'Feels expensive this month' is not data. ccusage reads your local session logs and prices them at list rates: one command to start, what the number actually means, and the usage shape that answers subscription vs. usage-based.
Everyone who uses Claude Code has the same moment of doubt: did I overdo it this month? The doubt usually stops at a feeling, because the next step is awkward — subscribers see no bill, only a progress bar; API users see a bill, but only remember to look at month's end. The answer has been on your own machine the whole time: Claude Code writes every session's usage into local logs, and ccusage is the simplest tool that reads that ledger aloud. This is not another ccusage manual — the command is one line and needs no manual. This is about what to do after you measure: which price the number uses, which numbers matter, and how a week of measurement answers 'how should I be paying for this?'
Disclosure up front: I operate Teapot Router, a usage-based API gateway. Writing 'how to decide between subscription and usage-based' is obviously in my interest — so the first four sections are provider-agnostic and only about your own numbers; the interested party shows up in the last section, and every criterion there is public and re-computable.
'Feels expensive' is not data; the local logs are
Every Claude Code session is written to JSONL files under ~/.claude: which requests, which models, how many input and output tokens, how much cache hit. The log starts the day you install — barring accidents, your entire past few weeks of usage are in there.
ccusage does something disarmingly simple: it reads that log, multiplies by a price table, and lays the result out by day, week, and session. It uploads nothing, asks for no API key, changes no configuration — it doesn't need to: the ledger and the arithmetic both stay on your machine.
One command to start, three views worth knowing
No install needed — npx ccusage daily runs as-is. Three views worth knowing day to day, each answering one question:
- daily: what each day cost — answers 'which day burned it';
- blocks: split into 5-hour billing blocks — the subscription-limit view; shows where your heavy work lands;
- monthly: the month rolled up — look here before asking 'should I change how I pay'.
It prices at list price — the step everyone skips
ccusage multiplies by the official list-price table. That carries a crucial distinction: if you are a subscriber, the number is not what you paid (you paid a flat monthly fee) — it is 'what this usage would have cost at API list price', a yardstick for measuring usage, not a bill. If you are an API user, it is an approximation of your bill — an approximation, because cache read/write pricing can differ from your provider's exact ledger; the per-request ledger remains the source of truth.
The distinction is not pedantry; it is the entrance to the next step: read ccusage's output as a usage shape, not a bill, and the numbers start making decisions for you.
Run it for a week; you get more than a total
A total tells you whether it's expensive; a shape tells you why, and whether a different billing model would be cheaper. Run it for a week and pull out four parameters: focused hours per day (the span of your blocks), task intensity (flagship or balanced model dominating), cache hit ratio (same context, hit versus cold differs by an order of magnitude), and burstiness (steady daily, or two blow-up days). These four numbers are far more useful than the monthly total, because every billing model's differences unfold along these four axes.
From shape to decision: what the arithmetic looks like
With a shape in hand, subscription versus usage-based stops being a team-sport argument and becomes an assignable multiplication: hours per day × intensity into a cost calculator, out comes the usage-based monthly figure, set it next to the subscription price. Below it, usage-based saves money; above, you are paying usage prices for uncapped flow — which can still make sense, but now it's an informed choice.
The interested-party part, stated plainly: our calculator and per-request ledger do exactly this — rates fetched live from the public price endpoint, every request's cost inspectable and exportable after the fact. But you don't have to use us: any provider offering a machine-readable price list and a per-request ledger can run the same arithmetic; one who won't offer either, however cheap the rate table looks, should have 'unverifiable' booked as a cost.
ccusage's value isn't the command; it's replacing a feeling with a shape. Measure a week, remember four numbers: hours, intensity, hit rate, peaks. With those four in hand, any billing pitch — including ours — loses its power to spook you, because the answer is one you multiplied yourself.
FAQ
Is ccusage free? Does it need internet or an API key?
Free and open source. It only reads the session logs under ~/.claude and computes locally — nothing uploaded, no key needed, runs straight through npx with no install.
I'm on a subscription — is the number my bill?
No. Subscribers see 'this usage at official API list price' — a yardstick for your usage shape. You actually pay the flat monthly fee. API users see an approximation of the bill; the per-request ledger from your provider is the exact source of truth.
How is it different from Claude Code's built-in /usage?
/usage shows the current limit window's remaining and consumed — a 'right now' gauge. ccusage aggregates your history logs into day/month/block views. One manages the present, the other the past — deciding how to pay needs the latter.