Headroom: the token saver that reclaims your context window

Every agentic coding session has the same silent tax: the same file gets read into context five times, the same 400-line tool output gets re-sent on every turn, and your conversation history balloons until half your token budget is spent re-transmitting things the model already saw.

kRouter's Headroom token saver attacks exactly this. In the July 2026 verification, one code-heavy request went from 27,187 tokens to 2,056 -- a 92.4% reduction -- and the provider still accepted the body and returned a correct reply. That is one request, not an average, and the rest of this post is about when you can expect anything like it.

What Headroom actually does

Headroom is an external compression proxy, the headroom-ai Python package. It de-duplicates and compresses conversation context -- repeated file contents, large tool outputs, long histories -- before the request leaves your machine and reaches the provider. In kRouter's token-saver pipeline it runs after RTK and the Caveman or Ponytail prompt, and before PXPIPE. Compressing your own user messages is off by default.

The key design decision is that it fails open. If the proxy is down, slow (kRouter waits about 3 seconds), or not installed, kRouter sends the request untouched. You never lose a request because a compressor hiccuped -- worst case, you simply do not get the savings on that call.

The numbers, and their limits

From the v0.5.115 verification, run through the full kRouter request pipeline with headroom-ai 0.32 and its ml extra:

[HEADROOM] reported token delta=25131 before=27187 after=2056 (92.4%)

A direct probe of the compressor showed the same magnitude: 99,776 characters collapsed to 7,263 (92.7%). The provider accepted the compressed body and answered that request correctly. That shows it can work; it does not prove every request survives compression unchanged. Headroom rewrites context, so check results on your own workload before you leave it on.

The magnitude depends on your content and on what you installed. Repeated-code context compressed by about 92% in that test. Plain prose barely moves. The base package with only the proxy extra reports 0%: the ml and code extras do the actual compression. Later headroom-ai releases have not been re-measured.

Install and enable

Headroom needs Python 3.10 or newer. The base package gets you the plumbing; the compression extras do the real work:

# Base proxy (plumbing only, reports ~0% on its own)
pip install "headroom-ai[proxy]"
 
# Add a compression extra -- this is what does the work
pip install "headroom-ai[proxy,ml]"

The quotes matter in zsh, which otherwise treats the square brackets as a pattern.

Then enable it inside kRouter. It is off by default, so nothing changes until you turn it on:

1. Open the dashboard at http://localhost:20128/dashboard
2. Go to the Token Saver page
3. In the Headroom card, start the proxy and switch it on

kRouter manages the proxy lifecycle from that card -- start, stop, restart, and installing or removing the ml and code extras. Behind the scenes it posts the conversation to the proxy's /v1/compress endpoint (by default at http://localhost:8787) and swaps in the compressed messages before dispatch.

How it differs from the other savers

kRouter ships several token savers, and they compress different things. Only RTK is on by default.

The percentages are the project's own claims and one measurement, not benchmarks. They stack: RTK shrinks each tool result as it comes in, Caveman trims what the model writes back, and Headroom collapses the accumulated history across turns. How much that saves depends entirely on your traffic -- see why your Cline bill is $200 for where the tokens tend to go, and RTK compression for the saver that is already on.

When to use it

Headroom earns its keep on long, repetitive, agentic workloads:

• Cline, Claude Code or OpenCode sessions that read the same files across dozens of turns
• Codebase-wide refactors where large file contents recur in context
• Any workflow where conversation history grows past ~20k tokens

For short one-shot chats, the overhead is not worth it -- which is exactly why it defaults off and is a toggle rather than an always-on default.

One case where it never runs: when Claude Code talks to a Claude subscription through kRouter, kRouter skips every token saver by default so Anthropic's prompt cache stays intact, since rewriting the context would break the cache.

The bypass escape hatch

Sometimes you want a specific request to skip all compression -- a debugging probe, or a request where byte-exact context matters. Since v0.5.104 a client can send the header X-9Router-Token-Saver: off to opt a single call out of every saver, Headroom included, without disabling anything globally.

Common questions

Is Headroom on by default?

No. It is off until you switch it on in the Token Saver page, and it also needs the Python proxy running. RTK is the only token saver kRouter turns on by default.

Why does Headroom report 0% savings?

Most likely only the base proxy extra is installed. The compression comes from the ml or code extras, which you can install from the Headroom card or with pip install "headroom-ai[proxy,ml]".

What happens if the Headroom proxy crashes?

Nothing breaks. kRouter fails open: if the proxy is down, slow or missing, the request goes out uncompressed.

Get started

Headroom is built into kRouter -- you only need the Python proxy to activate it:

npm install -g @sifxprime/krouter
krouter -t
pip install "headroom-ai[proxy,ml]"

Then open the Token Saver docs for the full comparison of the savers, or head to the install guide to get kRouter running.