ccusage in 2026: what the Cost column actually measures

Quick answer

The Cost column in ccusage is a counterfactual. It is what your token volume would have cost at pay-per-use list prices, computed locally on your machine, and if you are on a Claude subscription it is not your bill and never was. This is not a bug and nobody is hiding it: ccusage's own introduction frames the question it answers as "What would I be paying on a pay-per-use plan?", and Anthropic's own documentation says the equivalent figure in Claude Code "isn't relevant for billing purposes" for Max and Pro subscribers. The number is real, it is useful, and it answers a different question than a dollar sign in a terminal implies. If you are on a subscription, the two things that answer your actual question are ccusage blocks and Claude Code's own /usage.

I ran npx ccusage monthly on a Tuesday, saw a three-figure number in the Cost column, and felt the small cold drop you feel when a tool tells you something about your money. Then I remembered I am on a flat subscription and have not been billed a variable amount in months. So the number was not wrong. It was answering a question I had not asked, and I had spent about four seconds reading it as though it were my invoice. This is the field log of what that column actually measures, written on September 5, 2026, after going and reading the primary documents instead of the dashboard.

What the number actually is

Start with the vendor, because on this one the vendor is unusually clear.

Anthropic's Claude Code costs documentation, read on September 5, 2026, says this about the Session block in /usage:

"The Session block in /usage shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so the session cost figure isn't relevant for billing purposes."

And on where the dollar figure comes from:

"Claude Code computes the dollar figure locally from token counts at list price, unless a modelPricing table is in effect."

And then, plainly:

"The figure is an estimate, so for authoritative billing see the Usage page in the Claude Console."

Three things fall out of that. The figure is computed on your laptop, not fetched from a billing system. It is priced at list price, which is the pay-per-use API rate card, not whatever you actually pay. And Anthropic itself scopes it to API users and says so in the sentence that introduces it.

ccusage reads that same world. In its display mode it surfaces the costUSD value Claude Code writes into its own local JSONL. In calculate mode it computes the figure itself from token counts using pricing pulled from LiteLLM, models.dev and built-in historical schedules. In the default auto mode it uses whichever is available per entry. Every one of those three paths lands on a list-price number.

So the column is honest arithmetic on the right tokens against the wrong price list, for a subscriber. That is a useful thing to have. It is just not a bill.

Where the caveat lives, and where it does not

This is the part I found genuinely interesting, and it is not a story about anyone being wrong.

ccusage's introduction page gets it exactly right. Its Problem section lists the questions the tool exists to answer, and one of them is, word for word, "What would I be paying on a pay-per-use plan?" The same page describes the output as estimated costs. That is precise, and it is the correct framing.

Now go one click away, to the README on GitHub, which is the result sitting at organic position 1 for the term. Its tagline is "Analyze coding (agent) CLI token usage and costs from local data." I counted, on the real README (the repo root file is a 24 byte pointer into a monorepo, which cost me a wasted fetch): across roughly 11,000 characters of content, the word subscription occurs zero times, estimated occurs zero times, and pay-per-use occurs zero times. For calibration on the same file, cost occurs 14 times and pricing 10, so the count is a real absence and not a broken grep.

Same on the detail pages. Across the cost-modes guide and the source-support page, subscription, pay-per-use and flat rate all occur zero times.

And then the number itself renders in your terminal as a dollar sign followed by digits, under a header that says Cost, with no caveat attached to it at all.

That is the actual shape of this. Every authoritative source states the caveat somewhere in prose, and not one of them states it at the point where you read the number.

The mode recommended for billing verification

Here is the sharpest version of the same misalignment, and I want to be careful to frame it as a documentation gap rather than a defect.

ccusage's cost-modes page has a Mode Selection Guide. Under when to use display mode, the first bullet is "Billing verification - Comparing with Claude charges" and the second is "Official costs only - Trusting Claude's calculations".

display mode is the one that reads Claude Code's pre-calculated costUSD values. Those are the values Anthropic documents as computed locally at list price and "not relevant for billing purposes" for subscribers.

So the mode the docs point you at for verifying your bill is the mode that reads the one number the vendor has explicitly said is not about your bill. Both pages are individually accurate. Read together, they send a subscriber somewhere unhelpful. Nobody had to make a mistake for this to happen, which is precisely why it survives.

What actually answers the subscription question

The constructive half, and it is better tooling than I expected.

/usage inside Claude Code is now substantially more than a cost line. On a Pro, Max, Team or Enterprise plan it shows plan usage bars, activity stats, and a usage breakdown. The part I had not seen before is attribution: recent usage broken out by skills, subagents, plugins and individual MCP servers, each as a percentage of the total. If you have ever suspected one chatty MCP server of eating your window, that is the screen that tells you. It needs Claude Code v2.1.174 or later, and the VS Code extension surfaces the same shares in its Account and usage dialog.

Two more that were news to me. /insights analyses your usage patterns and runs on any plan and any provider, with the honest note in the docs that its own analysis tokens count against your plan. And /usage-credits shows spend against a monthly limit once usage credits are on, which requires signing in with a claude.ai subscription through /login and is not available with API key authentication.

Also worth knowing: /cost does not appear on that documentation page at all. Zero occurrences. /usage appears 21 times. If you have a muscle memory or a blog bookmark pointing at /cost, it has moved on without you.

On the ccusage side, the command that maps to the subscription reality is ccusage blocks, described in its own README as Claude Code 5-hour billing windows with active block monitoring. That is the unit Pro and Max plans actually ration against. It is the least-linked command in the tool and the most relevant one if you are trying to avoid hitting a wall mid-refactor.

The tool grew eighteen data sources while I was not looking

Worth updating your mental model. ccusage is no longer a Claude Code utility.

Its introduction now lists eighteen coding CLIs it reads: Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI and ZCode. It aggregates all detected sources by default, with no special flag. The docs even note the name has been retrofitted: "The original 'cc' came from Claude Code usage and now also fits Codex CLI usage."

The two most-cited third-party write-ups both describe a Claude-Code-only JSONL parser, which is what it was when they were written. If you run more than one agent CLI, the default output is now a merged view across all of them, and that changes what a total means.

There are two different tools called ccusage

Small, real, and it will bite exactly one kind of person.

npx ccusage gets you the tool above: local JSONL parsing, eighteen sources, estimated costs.

pip install ccusage gets you a different program by a different author. It is wakamex/ccusage, version 0.1.12, and it does close to the opposite thing: it fetches your real rate limit data from Anthropic's API and renders it in the statusline. Its sample output shows a plan name, a session percentage, weekly percentages per model family, reset timers and an extra-usage figure.

I want to be honest about scale rather than dress this up as a rivalry. The PyPI package had 3 stars when I looked and was last pushed on August 15, 2026. It is a small personal project, not a competitor. But it is genuinely closer to what a subscriber wants, because percentages against your plan limits are the thing that determines whether you get rate-limited, and it is sitting in the package namespace people reach for reflexively. If you are a Python person who typed the obvious install command and got something unfamiliar, that is why.

The blind spot they share

Both approaches read local session history on this machine. Anthropic's docs spell out the consequence for the native figure: usage from other devices or claude.ai is not included. The same is structurally true of ccusage, which parses local files by definition.

I work across a laptop and a desktop. Neither tool has ever shown me a complete picture, and until I read that sentence I did not know I was looking at a partial one. That is not a criticism of either. It is a property of local-first accounting, and it is the reason the Console remains the authoritative surface.

The scoreboard

What I actually changed

I stopped reading the Cost column as spend and started reading it as relative burn. As a comparison between two weeks, or between two projects, or before and after I turned a noisy MCP server off, it is excellent, because the pricing error is a constant that cancels out. As an absolute figure it was only ever going to mislead me.

Then I put ccusage blocks in my shell history instead of ccusage monthly, because the five-hour window is the thing that can actually interrupt my afternoon.

And I went and looked at /usage attribution properly, which is the one concrete win in this whole exercise. It turned out one MCP server was responsible for a share of my usage I would not have guessed, and I would never have found that from a cost total. I wrote up which statusline fields survived a similar cull in the statusline I actually read, and the same principle held here: the number that looks most important is rarely the one that changes a decision.

One correction I had to make to myself

I went into this expecting the ecosystem write-ups to be the villain, because the highest-ranking one is titled "ccusage: Finally Know How Much Claude Code Is Actually Costing You", which promises exactly the thing the vendor documentation says the number is not.

Then I read it. The article is right. It opens by naming the subscription situation directly, "You're paying a flat monthly fee", and it correctly identifies rolling five-hour windows as what actually governs whether you get rate-limited, "not your total monthly spend". Its body is more careful than its headline.

I was one step away from using a title as evidence about a body, in a post whose entire argument is about reading primary sources instead of summaries. Catching that changed the conclusion for the better, because the real finding is not that anyone is wrong. It is that the caveat lives in prose, in three separate places, and never in the one place where the dollar sign appears.