Headroom (github.com/headroomlabs-ai/headroom) sits between your AI agent and the model and compresses everything the agent reads: tool outputs, logs, files, search results, conversation history. The model gets the same meaning in far fewer tokens. Apache 2.0, runs locally — your data never leaves the machine.
Four ways to plug it in
- Proxy.
headroom proxy --port 8787— zero code changes, any language. - Agent wrap.
headroom wrap claude(also codex, cursor, aider, copilot, opencode and more), undone withheadroom unwrap. - Library.
compress(messages)inline in Python or TypeScript. - MCP server. Three tools —
headroom_compress,headroom_retrieve,headroom_stats— for any MCP client.
The best part: the statistics
Most tools around LLMs promise savings but never let you look at your own spend. Headroom does the opposite: headroom savings, headroom stats and headroom dashboard break it down by day, by model and by client. You can finally see how expensive a given project actually is.
Here is a real slice of my own Claude Code session, unpolished: 118 API requests, 74 of them compressed, 37,249 tokens removed; the session would have cost $3.65 and came out at $3.50. On top of that, nearly 4 million tokens were served from the provider cache. Per-model costs are listed separately — Opus on one line, Haiku on another.
Numbers worth reading carefully
The README claims 60–95% savings on JSON data and 15–20% for coding agents. Both are honest, but they describe different workloads. My session averaged roughly 1–4% compression — and that is expected: most coding-agent requests are prefix-frozen and already sitting in the provider cache. Headroom deliberately leaves them alone, because rewriting that prefix would bust the cache and cost more than it saves.
The big percentages live where fresh noise piles up: code search (17,765 → 1,408 tokens), incident debugging, issue triage. Accuracy holds up on benchmarks — GSM8K unchanged, TruthfulQA even slightly above baseline.
A tool that shows you "this much, and here is why exactly this much" instead of a flattering percentage is rare. It earns more trust.
Compression you can undo
Inside there is a content router: JSON goes to SmartCrusher, code to an AST-aware compressor (Python, JS/TS, Go, Rust, Java, C/C++), prose to their own Kompress-v2-base model. The key property is reversibility — originals stay cached locally, and if the model needs the details it simply calls headroom_retrieve.
What that looks like in practice: a large file in my terminal collapsed into a short marker with a hash, and when I needed the full text one call brought it back. Nothing lost — it just travelled to the model ten times lighter.
Small things that pleasantly surprised me
- Output-side savings.
HEADROOM_OUTPUT_SHAPER=1trims what the model writes back — preambles, restated code, deep thinking on routine steps. The report gives an estimate with a confidence interval instead of a made-up number. headroom learn. Mines failed sessions and writes the lessons intoCLAUDE.local.mdso the agent stops repeating them.- Cross-agent memory. Claude, Codex, Gemini and Grok share one store.
Worth a try if…
If you run coding agents daily or build your own, it is worth measuring at least once. Setup takes a minute:
pip install "headroom-ai[all]"(Python 3.10+; pick 3.13 if you want the dollar figures)headroom wrap claude— then work as usualheadroom savings— see what it added up to
If you stay on a single provider and its native compaction is enough for you, feel free to skip it. But once agents run in CI or a whole team burns tokens every day, the bill becomes visible — and that alone is a reason to look.
Got an idea where AI agents could save your team time and money? Get in touch — let's figure it out together.