Headroom AI: Token Compression for AI Coding Agents

In this article you will learn:

• what Headroom AI is and what its authors promise
• what independent benchmarks found when they measured the bill
• how it felt after a week of daily use

Compressing context before it reaches the model sounds like free money. Fewer tokens in, same answer out, smaller invoice.

Headroom is one of the more complete attempts at that idea — a proxy, a library, an MCP server and a CLI wrapper, all pointed at the same goal, all running on your own machine. If you read my Graphify article, this is the same fight from a different angle: Graphify stops the agent from wandering, Headroom shrinks what it finds along the way.

The interesting part is what happened when people started measuring it.

Quick answer

Headroom AI is an open-source layer that sits between your coding agent and the model provider and compresses what passes through — tool outputs, logs, search results, whole files — before any of it gets billed.

• What it does well: the compression is real, local, and auditable. Headroom can prove, byte for byte, what it removed.
• What it promises: 60-95% fewer tokens on JSON, 15-20% for everyday coding agents.
• What is less certain: fewer tokens sent is not the same thing as a smaller invoice, and the gap between those two is wider than you would expect.

That gap is what most of this post is about.

What Headroom AI promises

The core idea is simple enough to explain in one sentence: most of what an AI coding agent sends to the model is not prose written by a human, it is machine output. Test runs, git diff, JSON payloads, stack traces, whole files read to answer a question about three lines of them. That material is verbose, highly redundant, and — this is the part Headroom leans on — compressible without losing the parts the model actually reads.

60-95% fewer tokens

This is the headline number, and the fine print matters: the README's own tagline reads "60-95% fewer tokens (for JSON data), 15-20% fewer tokens (for coding agents)". Two different numbers for two different jobs, and the big one is not the one you get.

The reason is that Headroom is not one compressor applied uniformly. A ContentRouter inspects each chunk and hands it to whichever engine fits:

• SmartCrusher for JSON — "arrays of dicts, nested objects, mixed types", where repeated keys and boilerplate make the ratios highest
• CodeCompressor for source files, AST-aware across Python, JS/TS, Go, Rust, Java, C/C++, and Perl
• Kompress-v2-base, their own Hugging Face model trained on agentic traces, for prose that has no structure to exploit
• a separate path for images, claimed at 40-90% via a trained ML router

The published per-workload figures follow that logic exactly: 92% on code search and on SRE incident debugging, 73% on GitHub issue triage, but 47% on codebase exploration. The more machine-shaped the input, the better it does. A real coding session is a mix of all of it plus your own typing, which is how a 92% best case averages out to the 15-20% on the tin.

Four ways to run Headroom

Headroom is one engine with four front doors, and which one you pick decides how invasive it is:

• CLI wrapper — headroom wrap claude puts it in front of an existing agent, headroom unwrap claude takes it back out. The lowest-commitment option, and the list of supported tools is long: codex, grok, copilot, cursor, aider, opencode, cline, continue, goose, and more.
• Proxy — headroom proxy --port 8787, then point your agent's base URL at it. Anything that speaks the provider's API works, no integration needed.
• Library — compress(messages) called directly from your own Python or TypeScript, for when you are building the thing that talks to the model.
• MCP server — headroom mcp install exposes headroom_compress, headroom_retrieve, and headroom_stats as tools, so the agent can compress on demand rather than having it done to it.

The common thread is that Headroom works at the wire level: it sits on the request, not inside your agent. That is what makes it agent-agnostic, and it is also what separates it from tools that rewrite a command's output before the agent ever sees it. More on that distinction in the RTK section.

It is Apache 2.0, and the pitch is explicitly local-first — "your data never leaves your machine". No Headroom account, no API key, and even the savings dashboard runs against your own proxy rather than a hosted one. I come back to what that does and does not cover later on.

Reversible compression with CCR

The obvious objection to all of this is that a compressed file is a file with pieces missing, and sooner or later the model needs a missing piece.

Headroom's answer is CCR — reversible compression. Originals are stored locally rather than discarded, so the agent can call headroom_retrieve and get the full version back when it needs one. Nothing is destroyed, only deferred — with one asterisk worth noting: retrieval works "within the configured TTL". Reversibility has an expiry date.

The second half of the answer is about caching, and this is the part to pay attention to. Provider prompt caching only pays off when the front of your prompt is byte-identical to last time, and a compressor that rewrites text is an excellent way to destroy that. Headroom's defence is live-zone compression: it touches only new bytes — fresh tool output, the latest turn — so the frozen prefix stays byte-identical and, in the README's words, "provider cache is not busted. History is never dropped."

There is also a CacheAligner that runs first in the pipeline, though it is worth reading what it actually does. It "detects and warns about volatile content that can bust provider KV cache prefixes; never rewrites prompts". It is a smoke detector, not a sprinkler. It tells you the cache is at risk; it does not save it.

Hold on to that distinction. It turns out to sit very close to the seam where the promise and the measurements come apart.

Getting Headroom running

Install and wrap your agent

I am not going to reproduce the installation steps here — the official README and the docs do that better than a blog post will, and they stay current.

What is worth saying is that the friction depends heavily on where your agent lives. If you run Claude Code in a terminal, headroom wrap claude really is close to the advertised one-liner. My setup is VS Code with the Claude Code extension, and that turned out to be a different story: no single command that ends with everything working. I ended up doing what I suspect a lot of people will do — handing the whole configuration to an AI agent and letting it work out the wiring. It got there, but it was not a five-minute job, and it is the reason I run Headroom as a standalone proxy rather than through the wrapper.

What ships with it: RTK and lean-ctx

One detail that is easy to miss: Headroom does not do all of this itself. It vendors two third-party binaries, RTK and lean-ctx, for shell-output rewriting. You can switch between them or disable them entirely with HEADROOM_CONTEXT_TOOL, and the README is upfront about the arrangement: "we don't own or control either project".

If you have read my RTK article, the distinction matters. RTK works on CLI command output and is not reversible — what it strips is gone. Headroom's own layer sits on the wire and keeps originals retrievable. Same goal, different guarantees, and now shipping in the same box.

It also matters for the next section. When a benchmark reports a number for "Headroom", part of what it measured may be a bundled tool with different properties — which is exactly why some of those benchmarks test the components separately.

Using Headroom alongside Graphify

The two solve different halves of the same waste. Graphify reduces how many trips the agent makes; Headroom reduces how much each trip costs. Nothing overlaps, both run locally, and the combination is what I have been using day to day.

There is even a pleasant side effect: graphify-out/graph.json is exactly the kind of structured payload SmartCrusher handles best.

Does Headroom actually save tokens?

Yes. It removes tokens, and it can prove it byte for byte.

That is not the useful question, though. The useful question is whether removing them makes your invoice smaller — and two independent groups went and measured exactly that.

Token reduction is not cost reduction

That is the title of a July 2026 paper by Sarel Weinberger and Amir Hozez, built on 2,848 real, paid Claude Code runs. Its finding: the number everyone optimizes is not the number that gets charged. Across their tasks, cutting tokens and paying less barely moved together — 0.15 on a scale where 1.0 would mean perfectly linked.

Headroom is named and measured there. Scored on what it cost to actually finish a job compared with running nothing at all, it came out roughly 46% more expensive. RTK landed near break-even. Nothing came out meaningfully ahead.

Three meters, three answers

tokbench, a smaller independent test, ran Headroom through an eight-stage workload on a real TypeScript bug — and framed the problem better than anyone: there are three meters, and they never agree.

• the vendor claims compression in the high tens of percent
• Headroom's own counter logged 10.2% genuinely stripped before sending
• the provider charged for 43% more than running nothing at all

The middle number is honest, and it is the detail that convinced me this is a serious project: tokbench checked Headroom's books against the real bill and they matched to within 0.0004%. The compression happened, exactly as advertised. The total went up anyway.

Why the bill can go up

Two reasons, and each study found one.

The repeat discount. Providers charge less for text they have already seen — but only if the start of the conversation is character-for-character identical. Touch it and the discount vanishes, and that discounted traffic was most of the cost in the arXiv study. This is the risk CacheAligner warns about, and warning is all it does.

The longer path. In tokbench the agent needed 237 turns where it had needed 180. Compressed context is smaller, but it is also thinner, and an assistant that has to ask twice has already spent what it saved.

Fewer tokens per exchange, more exchanges. No meter that counts bytes will ever catch that.

Both studies come with limits worth knowing. tokbench is a pilot at one run per tool, by an author who built the test setup himself and openly uses a competing tool daily. The paper is far larger but still lives inside one toolchain. Neither group claims these products fail in general.

Test it on your own setup

Which is the more useful conclusion anyway.

Those studies disagreed because they were measuring different worlds: one provider gives repeat discounts, another does not; one workload is mostly machine output, another mostly reasoning. Your setup is a fourth world nobody has measured, and every factor that decides the answer belongs to you.

So measure it. Take a task you actually do, run it a few times with the tool and without, alternating between them. Judge it on two things: what the provider charged, and whether the work got done.

And if the dashboard disagrees with the invoice, believe the invoice. It is the only meter that takes your money.

One week with Headroom

The dashboard question

Is the dashboard a game changer? No. Is it interesting? Yes. Is it useful? Sometimes.

Let me break this down. I like to visualize data — the dashboard does just that. How you can improve your workflow from the data displayed is a separate concern. In my opinion it is a nice add-on, for the following reasons:

• You can preview Anthropic Subscription session usage — either the 5-hour or the 7-day window (screenshot below).
• You get a general insight into "token savings" per session, lifetime, and historical — whether those correlate with lower cost is a separate problem.
  • Reading through the savings is a bit tricky. On the API, prompt caching shows up directly as a billing discount. I'm on a Claude Code individual subscription, where caching pays off as usage headroom instead — and that, my biggest saving, never appears anywhere in the dashboard data. For my non-demanding week of usage, reported savings are estimated at $3.60 (screenshot below).
• In my case: I get a clear separation of token savings between Headroom and RTK. This is useful for judging whether I need Headroom in the first place.

Here are a few screenshots of my dashboard:

The rest of the dashboard is not crucial enough to show here — the best you can do is install Headroom yourself and check it out!

What data Headroom collects

Since that dashboard sits on my machine and reads my traffic, the obvious follow-up is where any of it goes.

The short answer is nowhere. Headroom runs as a local proxy, the compression happens on your hardware, and the CCR store keeps originals on disk. There is no account to create and no API key to paste. The README puts it plainly: "your data never leaves your machine". The dashboard is the same story — it only works while your own proxy is running, because that is where the numbers come from.

That held up when I went digging through the source. On a default install the only thing that leaves your machine is a version check against PyPI, at most once a day — a plain request with no payload and no installation ID — and HEADROOM_UPDATE_CHECK=off stops it. There is telemetry code in the repo, but it is opt-in, off unless you explicitly enable it, and the aggregates it gathers stay in-process behind a local endpoint. The one component that genuinely reports back to Headroom Labs never even initializes unless you set a license key, and what it sends then is counts - requests, tokens before and after, which models you used - not prompts, tool output, or keys. If you want none of it, HEADROOM_OFFLINE=1 is a single switch that kills all of the above plus the model download from Hugging Face.

Graphify states its position outright — no telemetry, no usage tracking, no analytics — and that sentence costs nothing to write.

Final thoughts

I'm not dazzled by Headroom — not because it didn't work, but because my hopes were high and never met. I expected a fully grown ecosystem of tools that would save tokens so I can do more per 5-hour session in Claude Code.

What I found instead is a puzzling question: is trying to shake every last token out of my session even beneficial in the long run? In the end — many really smart people work at companies like OpenAI and Anthropic. They tune their tools and harnesses and fight over clients with competitors, with huge amounts of money backing them up.

There is another concern: do complicated tools do a better job than simple ones? The caveman skill points in a similar direction — sometimes "less is more".

Here are a few takeaways:

• I found no great benefits using Headroom. It works, but I would rather stick with RTK alone.
  • I'll keep working with Headroom for at least two more weeks, just to make sure I did not miss anything important.
• There is a huge difference in cost between subscription and API usage.
• Input tokens are relatively cheap. Output tokens are the real cost — a small prompt that produces a long answer is where the bill actually lives.
• If a tool brings you joy — don't be bothered. If it helps you — stick with it. If it repeatedly proves not to work — abandon it. Make your own choices.
• We are still in the process of squeezing more out of every token. I don't think this journey will ever end.

I hope this was a meaningful read — if so, let me know in the comments. Stay tuned!

FAQ