Part of the reduce Claude Code token usage pillar. This page is the head-to-head specifically: two open-source optimizers that get compared a lot, measured on the same benchmark.

Is headroom or rtk the better token optimizer?

On measured session cost, neither one delivers what its README implies — but rtk is the safer of the two. On the open token optimizer benchmark I run, rtk finished at roughly break-even: sessions cost about the same as running no tool at all. headroom finished 53% more expensive than running nothing, last of the twelve tools tested — the only tool the benchmark could show is measurably worse than doing nothing. That is not the result most people expect, and it deserves an explanation rather than a scoreboard. Both projects are competently built and both are solving a real problem. The gap between what they do and what shows up on the invoice comes down to where in the pipeline they intervene — and, in headroom's case, to a genuine trade-off that works against you in an agent loop. I should be upfront about the obvious: I maintain the benchmark and I sell a competing tool. So the useful thing I can offer isn't the ranking, it's the mechanism. Once you understand why each tool lands where it does, you can check the reasoning against your own usage instead of taking my word for it.

What does rtk actually do?

rtk is a Rust CLI proxy that filters shell command output before it reaches the model. You run git status or cargo build or pytest, and rtk intercepts the output, strips the parts a language model gains nothing from, and passes on a compacted version. It ships 100-plus command-specific filters — git, cargo, npm, pytest, docker, aws — and hooks in transparently, so you don't change how you type commands. The engineering is good. Single binary, under 10 ms of startup overhead, no token cost for the integration itself, and rtk gain reports what it saved. If you spend your day in a terminal-heavy loop with verbose build tools, it does visibly shrink those particular blobs. Its limits are structural rather than sloppy:

The hook only covers bash. It doesn't touch the agent's built-in tools — Read, Grep, Glob. In a typical Claude Code session those are where most of the tokens come from, which is the single biggest reason the measured saving lands near zero.
Output filtering only. No semantic retrieval, no structural compression of source files, no lazy loading of MCP manifests.
No native Windows PowerShell support.

So rtk optimises one channel well and leaves the larger channels untouched. Break-even on a whole-session measurement is the honest consequence of that, not a bug.

What does headroom actually do?

headroom is far more ambitious: it compresses the entire message array before every API call. It's a Python SDK plus CLI proxy plus MCP server, Apache 2.0, with a serious following. The pipeline aligns cache boundaries, routes each piece of content to a format-specific compressor (JSON, code, text, logs, diffs, HTML) via an ML content detector, scores context for relevance, and exposes a retrieve tool so the model can pull an original back when the compressed version isn't enough. On paper this is the more complete idea. It operates on the whole conversation window rather than one tool's output, and its per-format compressors report high reduction ratios in isolation. The catch is what happens when you put that in a loop:

Rewriting the message array on every call fights prompt caching. Providers cache on an exact prefix match. If compression decisions shift between turns — and they do, because the content shifts — the prefix changes and the cache misses. You then re-pay full input price for context you had already bought at a discount. That single effect can swamp the savings from compression.
Heavy footprint. Python 3.10+, a 150M-parameter ModernBERT model, Magika for content detection, 16–50 ms per call.
The retrieve round-trip has a cost. When compression drops something the model needed, fetching it back is an extra turn — carrying the whole conversation again.

This is why headroom lands where it does. It isn't that the compression doesn't work; measured on a single payload it works well. It's that aggressive per-call rewriting in a cached, stateful agent loop can cost more than it saves.

Why does compressing more sometimes cost more?

Because in an agent session you are billed on the whole conversation, replayed every turn — and prompt caching is what makes that affordable. The model is stateless. Turn 20 resends everything from turns 1 through 19. Providers price cached input at a steep discount precisely because that replay is so predictable. Anything that perturbs the cached prefix converts a discounted replay into a full-price one. A compressor that rewrites history on each call is, structurally, a cache-invalidation machine — however good its compression ratio looks in isolation. The general lesson generalises past these two tools: a token-reduction number measured on one payload tells you almost nothing about session cost. The only figure that matters is what a full session costs end to end, with caching behaviour included. That is the whole reason I built the benchmark to measure sessions rather than compression ratios.

Which one should you install?

Pick rtk if you want a safe, low-effort win on noisy command output, and skip headroom unless you're using it outside an agent loop.

Choose rtk when your workflow is terminal-heavy, you're on macOS or Linux, and you want something that will not make things worse. Break-even on the benchmark still means the verbose-output problem is genuinely handled; you're just not going to see it on the invoice.
Choose headroom if you're compressing payloads in your own application code — a batch pipeline, a one-shot summarisation service — where there's no long cached conversation for the rewriting to disrupt. That is the setting its design actually suits.
Choose neither if your token problem is whole-file reads and unfiltered agent tool calls, because neither one addresses that.

And check my numbers rather than trusting them. Run a session you actually recognise, with and without the tool, and compare total cost — not tokens saved on one blob.

What actually moves the number?

The levers that show up on an invoice are the ones that stop unnecessary context from entering the conversation in the first place, rather than compressing it after it arrives: targeted retrieval instead of whole-file reads, filtering on noisy tool output across all tools rather than just bash, reading structure before full implementations, and loading MCP manifests lazily instead of at session start. That's the design Tokenade is built on — it sits between the agent and its tools and applies those levers automatically, including folding third-party MCP results at the boundary, without rewriting conversation history behind the provider's cache. On the same open benchmark it cuts session cost by 39% on long sessions against running no tool at all. I'd rather you verified that on the benchmark page, where the method and the full twelve-tool table are public, than took it from a comparison page I wrote.

See also:

headroom alternatives — the fuller field, if headroom isn't working out
Best Claude Code token optimizers — the ranked round-up
Token optimizer benchmark — method, campaign and full results
How to reduce Claude Code token usage — the levers, tool-agnostic

headroom vs rtk: which one actually cuts your bill?