headroom vs ccusage: measure first, then compress

Part of the reduce Claude Code token usage pillar. This page is the head-to-head, and the comparison is less lopsided than the categories suggest.

Is headroom or ccusage what I need?

ccusage first, then decide about headroom — because ccusage is how you find out whether headroom is helping you or costing you. They are not competitors. ccusage measures and changes nothing; headroom compresses your message array and changes a great deal. The reason to put them on the same page is that headroom is the tool in this category most likely to produce a result you would never notice without a meter. On my open long-session benchmark, headroom finished 53% more expensive than running no tool at all — last of the twelve tools tested. That is not a claim you should take from me on trust. It is a claim you should be able to check on your own machine, and ccusage is what lets you. I run that benchmark and sell a competing tool. Read this as a case for measuring, not as a scoreboard.

What does ccusage actually do?

It reads your agent's local JSONL transcripts and reports what you spent. Roughly 15k stars, 15 supported agent sources, zero install — bunx ccusage or npx ccusage@latest. Daily, weekly, monthly and per-session reports, per-model breakdowns, cache token tracking, and JSON output that composes with other dashboards. The feature that matters most for Claude Pro and Max subscribers is the 5-hour billing block view. Anthropic's limits reset on a rolling five-hour window, and ccusage is the tool that shows you where you are inside it rather than after it. Its limits are honest and stated: it is read-only and reduces nothing. It also cannot tell you what you would have spent without a given tool — it reports observed spend, not a counterfactual. And the JSONL schema it reads is implicit rather than specified, so it tracks whatever the agents happen to write.

What does headroom actually do?

It compresses the entire message array before every API call. Python SDK plus CLI proxy plus MCP server, Apache 2.0, roughly 18.7k stars. CacheAligner stabilises the static prompt prefix by moving timestamps and UUIDs into a non-cached tail; ContentRouter sends each piece of content to a format-specific compressor via ML detection — JSON, code, text, logs, diffs, HTML; IntelligentContext scores what remains across six relevance dimensions. It is reversible: originals sit in a local LRU cache and the model can call an injected headroom_retrieve tool, with optional BM25 sub-search. The per-workload numbers are strong — 92% on code-search results and SRE incident logs, 73% on issue triage. The footprint is real: Python 3.10+, a 150M-parameter ModernBERT model, Magika for content detection, and 16 to 50 ms of overhead per call.

Why can a compressor make a session more expensive?

Because prompt caching pays only when the prefix is stable, and a window rewriter destabilises it. Cached input is billed at a fraction of fresh input on every major provider. When compression decisions change between turns — and they do, because the content changes — the prefix changes, the cache misses, and you re-pay full price for context you had already bought. CacheAligner exists precisely to fight this, which tells you the project understands the risk. On a long agent loop it is not enough. There is a second path to the same result. When the compressed version turns out to be insufficient, the model calls headroom_retrieve and pulls the original back in. You have then paid for the compressed copy, the original, and the round-trip between them. Rare on a short task; compounding across a session. This is exactly the failure mode a meter catches and intuition does not. Every individual compression looks like a win. The invoice is where the loss shows up, and the invoice is what ccusage reads.

What does the meter tell you that the compressor cannot?

Four things, and each maps to a decision:

Your input/output split. If inbound dominates outbound by ten to one — it usually does — output-side tools are the wrong first move.
Your cache-hit rate. This is the number to look at before installing anything that rewrites the window. A high hit rate is an asset a compressor will spend.
Your per-model distribution. If one model is draining far faster than the others, that is a routing question before it is an optimisation question.
Where you sit in the five-hour block. Useful on its own, independent of any optimizer.

None of that reduces a single token. All of it decides which reduction is worth attempting.

Where does the meter stop?

It reports what happened, not what caused it. ccusage will tell you a session cost more than usual. It will not tell you that eleven of your last twenty tool calls re-read the same four files, or that a compressed payload was fetched back in full. It also has no baseline. There is no "what would I have spent without tool X" view, so an A/B has to be run by you: a week with, a week without, comparable work. That is more discipline than most people apply, and it is the only way a tool's effect on your codebase becomes a fact rather than a vendor claim.

Which one should you pick?

Install ccusage regardless. It is free, zero-install, read-only, and it is the instrument every other decision on this page depends on. There is no scenario where you are worse off for having the number. Install headroom if your workload is batch rather than interactive — long, stable payloads processed once, where the prefix is not being invalidated every turn and 92% off a large JSON blob is the whole story. That is a genuine use case and it is not an agent coding loop. Do not install headroom on an interactive agent loop without measuring before and after. The benchmark says it can cost you; your own numbers are what settle it for your repository.

How to apply this today

Run npx ccusage@latest now. It takes seconds, installs nothing, and reads transcripts you already have.
Write down three numbers: input/output ratio, cache-hit rate, per-model split. These are your baseline and they are worth more than any tool comparison.
Change one thing at a time. Two tools installed in the same week produce one uninterpretable result.
Re-read the meter after a week, not after a task. Compression effects and cache effects diverge at those two scales, and the week is the one you pay for.

What goes wrong (anti-patterns)

Installing an optimizer before a meter. You will never know whether it worked, and one of the tools on this page is measurably capable of making things worse. Trusting per-payload compression rates. 92% off one blob and 53% more expensive over a session are both true of headroom, and they do not contradict each other. Treating ccusage as an optimizer. It saves nothing. Its value is entirely in what you do with the number. Changing two things at once. The most common way a week of measurement produces no usable conclusion.

See also: