Why your Claude Code cost estimate doesn't match your bill

First: which bill?

Anthropic's own documentation settles the subscription case in one sentence: "Claude Max and Pro subscribers have usage included in their subscription, so the session cost figure isn't relevant for billing purposes." The figure is still useful. It is the API-equivalent value of the work your sessions did, which is how you compare two days, notice an expensive hour, or judge what a plan is worth to you. It just is not money you owe.

How the estimate is built

Claude Code writes one JSONL transcript per session under ~/.claude/projects. Notchmeter reads every one touched in the last 30 days (plus Claude Desktop's Cowork sessions and any folder you add in Settings), and each response contributes five token counts from the API's own usage object. None of them is estimated: the counts are what the API reported, and each model's tokens are priced at that model's rate.

Three more rules come straight from Anthropic's pricing page and the Agent SDK's cost documentation. A response whose usage says inference_geo: "us" is multiplied by 1.1 on every bucket, because US-only inference on Claude 4.6 and later is billed at that premium. A web search adds $10 per 1,000 searches, after the multiplier, which never applies to a per-request fee. And a response marked speed: "fast" on Opus 5 or Opus 4.8 is priced at twice the standard rate, and on Opus 5.5 at the page's own fast rate, $8 input and $40 output, with its 0.05 × cache read applied to the fast input rate ($0.40).

A worked line, so you can check the arithmetic: one Sonnet 5 response with 2,000 input tokens, 800 output, 5,000 written to the 5-minute cache and 30,000 read from it costs $0.004 + $0.008 + $0.0125 + $0.006 = $0.0305. The same response served from US-only inference costs $0.03355.

Why two tools disagree about the same transcripts

Claude Code writes a streamed response as several lines, one per content block, and they share one message id. Anthropic's documentation says to deduplicate by that id, and since 2026-09-24 Notchmeter groups by it alone. Until then it grouped by the message id and Claude Code's request id together, the pair ccusage uses, which counted a Claude Desktop Cowork response two or three times over: Cowork's transcripts write the request id under another name on some lines and leave it off others, so each of those lines stood on its own. Claude Code's own transcripts carry the request id on every line, and their figures did not move. What differs between tools is which line each keeps, and it matters more than it looks: Claude Code builds each line from the usage reported when the response began, so every line but the last carries a placeholder output count, often single digits. Only the final line has the real one.

Notchmeter keeps the line with the largest output count. Measured across the 3,501 transcripts on the development Mac on 2026-09-01, keeping the first line of each response would have counted 17,975,458 output tokens; keeping the last counts 24,339,282, 35% more. A golden test pins it: three lines of one Fable 5.1 response, with output counts of 3, 3 and 1,090, price to $0.1095, not the $0.05515 that keeping the first would give. If another tool shows you a lower figure for the same day, this is the first place to look.

The other common mismatch is scope. Claude Code's /usage Session block covers one session since its last /clear. Notchmeter's Today covers every transcript on the Mac for the calendar day. Both can be right.

The eight known divergences

These are the things a bill can contain that the estimate does not, in the order they are likely to matter. They are listed in the accuracy document for the same reason they are listed here: a number that cannot show its work should not be on screen.

1. Interrupted responses. A response that never finished (you pressed Escape, the network dropped) has only placeholder lines, so its output is under-counted. Its input and cache counts are right. It cannot be told apart from a genuinely short reply, so nothing is guessed.
2. Contracted rates, regional cloud premiums and usage-credit rates, unless you tell the app about them (next section).
3. Price changes. The table compiled into the app is a dated snapshot. Once a day, unless you turn it off, the app also reads a price list this project publishes, so a model that launches between releases is priced at its published rate within a day; it can add a model or change a rate from a stated day, never remove one. A scheduled job fetches Anthropic's pricing page every week and fails when a row no longer matches.
4. Other machines and claude.ai. Only this Mac's transcripts, Cowork's and the folders you add are read. Chat on claude.ai is never priced.
5. Currency. Everything is computed in US dollars. Show costs in converts with a rate you type, so a converted figure is only as current as that rate, unless you turn on Fetch today's rate (off by default), which converts at the European Central Bank's daily reference rate instead.
6. Cursor's percentage fields, which Cursor's own staff describe as a different internal metric from spend (see the limits guide).
7. Copilot's day series. GitHub reports a month-to-date count, so a day's credits land on the day this Mac saw them rise.
8. Plan prices. The plan value line ($412 of API-equivalent value on the $200 Claude Max 20x plan · 2.1x) takes each plan's monthly list price from the vendor's own page as read on 2026-09-24. An annual discount, a regional price, a grandfathered rate or a change on the page since is not modelled, and no scheduled job watches those pages the way one watches Anthropic's pricing page.

Two rules that used to be on this list are now modelled and are not divergences: the web-search fee and fast mode, both since 2026-09-02.

If you pay contracted rates

Anthropic's documentation is plain that Claude Code "computes every cost figure it shows developers at list price, so if your organization pays contracted rates, the figures in /usage, the status line, and OpenTelemetry don't match your bill." Two files change that, and Notchmeter reads both. Claude Code's own modelPricing table in ~/.claude/settings.json is honoured, so the card agrees with Claude Code's figure. Notchmeter's ~/Library/Application Support/Notchmeter/pricing-overrides.json takes the same shape and wins on a clash:

Rates are dollars per million tokens, and a cache rate you leave out is derived from your input rate with the standard multipliers. An override changes the pricing fingerprint the app's cache is keyed on, so every transcript is re-priced on the next scan.

Codex, OpenCode, Cursor, Copilot, Gemini CLI, Antigravity and Kimi Code

• Codex is priced from its session rollouts at OpenAI's published standard-tier rates, with cached input taken out of input_tokens before it is priced so it is not charged twice. On a ChatGPT plan it is, like Claude's, the value of the work and not a bill.
• OpenCode is read from its own database on this Mac, and nothing is asked of any server for it. A turn on OpenCode Go is priced at the Go page's rates, for a model that page lists; any other turn is worth the cost OpenCode recorded for it (on OpenCode Zen even a zero, since Zen's free models are free), and a turn it recorded at zero on Anthropic or OpenAI, as it does on a subscription, is priced at that vendor's list rate, like Claude Code's. A turn priced none of those ways counts its tokens and not its dollars.
• Cursor is not estimated at all. Every dollar on its row is the one Cursor itself put on that event in its own usage export, which is why the row says billing export.
• GitHub Copilot is GitHub's own running count of AI credits, a cent each at GitHub's published rate, on seats GitHub meters that way.
• Gemini CLI and Antigravity have no row. Google's endpoints return quota fractions and no price and no token count, so there is nothing to derive a dollar from, and a $0 would be a claim that they cost nothing.
• Kimi Code has no row either. Its usage endpoint returns counts of an allowance and ratios of it, never a price, and Moonshot publishes no per-request rate for a Kimi Code membership.

Check a number yourself

Without the app running and without a Keychain prompt, the app's own executable prints the totals and one clause per tool:

To check one transcript by hand, list its priced lines, keep the line with the largest output_tokens for each message id, price the five buckets from the table, multiply by 1.1 where inference_geo is "us", and add up:

A model the table does not know is never priced at a guess and hidden: it costs $0 and is listed on the card as Unpriced, so a new model shows up as a gap you can see.