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. On a real code-heavy request it logged a 92.4% reduction — 27,187 tokens compressed down to 2,056 — while the provider still accepted the body and returned a correct reply.

What Headroom actually does

Headroom is an external compression proxy that de-duplicates and compresses conversation context — repeated file contents, large tool outputs, long histories — before the request leaves your machine and reaches the provider. It runs as the last stage in kRouter's token-saver pipeline, joining RTK, Caveman Mode, Ponytail, and PXPIPE.

The key design decision is that it fails open. If the proxy is down, times out, or is not installed, kRouter returns the request completely untouched. You never lose a request because a compressor hiccuped — worst case, you simply do not get the savings on that call.

The proof is in the token counts

This is not a marketing number. From the v0.5.115 verification, run through the full kRouter request pipeline:

[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 returned the correct answer — this is lossless-to-the-model compression, not truncation.

The magnitude depends on your content. Repeated-code context compresses ~92%. Plain prose barely moves. That is expected: Headroom finds redundancy, and code-heavy agentic sessions are full of it.

Install and enable

Headroom ships as a Python proxy. 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 the ML / code compression extras — these do the heavy lifting
pip install "headroom-ai[proxy,ml]"

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. Start the Headroom proxy and toggle it on

kRouter manages the proxy lifecycle for you — start, stop, restart, and installing or removing the compression extras — all from that card. Behind the scenes it POSTs your conversation to the proxy's /v1/compress endpoint and swaps in the compressed messages before dispatch.

How it differs from RTK, Caveman, and PXPIPE

kRouter now ships four distinct token savers, and they compress different things:

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. On a long agentic session, running all three is how you take a $200/month Cline habit down to single digits. See why your Cline bill is $200 for the full cost math.

When to use it

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

• Cline / Cursor 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 per-workload toggle rather than an always-on default.

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. kRouter added a per-request token-saver bypass header in v0.5.104, so you can opt a single call out of the entire saver pipeline without disabling anything globally.

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 RTK, Caveman, Headroom, and PXPIPE, or head to the install guide to get kRouter running in 30 seconds.