Headroom: How to Cut Up to 95% of Your Tokens Without Changing Responses
Every tool call your agent makes, every log it reads, every RAG chunk and every file you feed into context: you pay for it all, and most of it is boilerplate. Headroom is an open-source layer that sits between your agent and the model, and compresses everything before it reaches the LLM. The promise is straightforward: the same responses, a fraction of the tokens.
The project is by Tejas Chopra, an engineer from Netflix, and it’s moving fast: it’s already one of the most starred developer tools in this space. It’s Apache 2.0, runs locally (your data never leaves your machine), and is model-agnostic: Claude, Codex, Cursor, Aider, Copilot on the agent side, and Anthropic, OpenAI, Bedrock, Vertex, Azure or 100+ providers via LiteLLM on the backend.
First time with token economics? In What are tokens in AI and why do they charge you for them you’ll find the basics: exactly what a token is, why you pay for the entire conversation on each turn, and how to count them for free before you pay.
What it does, concretely
Headroom intercepts the bulky stuff — tool outputs, logs, database reads, RAG results, file reads, conversation history — and runs it through a pipeline of specialized compressors before it reaches the model:
- SmartCrusher for JSON: preserves first and last items, errors, anomalies and relevance matches, and crushes the repetitive middle.
- CodeCompressor, AST-aware for Python, JS, Go, Rust, Java and C++.
- Kompress-base, the project’s own model on HuggingFace, trained on agentic traces, for plain text.
- An ML router for image compression.
The key design decision is that compression is reversible. Headroom caches the originals locally (the CCR system — Compress-Cache-Retrieve) and injects a headroom_retrieve tool so the model can recover full data if it decides it needs it. That’s the mechanism behind the “same responses” promise: nothing is permanently discarded, it’s simply kept out of the prompt until it’s needed.
Four ways to put it in your stack
This is the part that makes Headroom easy to test. You don’t have to commit to an architecture: choose the integration that matches how you already work.
Proxy (zero code changes). You start it and point your agent’s base URL to it:
pip install "headroom-ai[all]"
headroom proxy --port 8787
# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# Any OpenAI client
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
Agent wrap, a single command: headroom wrap claude|codex|cursor|aider|copilot.
Library, inline in Python or TypeScript:
from headroom import compress
result = compress(messages, model="claude-sonnet-4-5-20250929")
# result.messages: same structure, way fewer tokens
MCP server, for any MCP client: headroom mcp install exposes headroom_compress, headroom_retrieve and headroom_stats as tools.
The numbers, and where they come from
Headroom’s headline is 60–95% token reduction with response quality preserved. Those are the project’s own benchmarks and, to be fair, they’re reproducible: clone the repo and run the eval suite yourself. The standouts: 94.9% compression with 98.2% recall on an article extraction benchmark, and 76.3% compression on a multi-tool agent test where all target findings were still recovered.
What’s worth noting is how the project handles its output token feature — cutting what the model writes back, not just what you send — Instead of citing a percentage with false certainty, the README is honest that this saving can’t be directly observed: it reports an estimate with a 95% confidence interval (for example ~32%, with a declared range) and offers a way to measure it for real: leave 10% of your conversations uncompressed as a control group with HEADROOM_OUTPUT_HOLDOUT=0.1 and the dashboard labels the number as measured instead of estimated. That kind of restraint in a v0.x project’s README is a good sign.
Where it doesn’t fit
Compression isn’t free magic, and the project says so upfront. Dense, unique text, or novel code, compress much less: Headroom’s own codebase exploration benchmark barely hit 47%, because there’s simply less boilerplate to strip out. And the compress/retrieve round-trip adds a moving part: if the model abuses headroom_retrieve, you recover some of the savings, so you’ll want to measure against your own traffic rather than trust the headline number.
Where it shines is in the opposite profile: agents that fire many tools and ingest large structured outputs (search results, API responses, log dumps), RAG pipelines feeding repetitive chunks, and long-running automated sessions where the same files and history get resent turn after turn.
It’s worth trying
It’s a v0.x project moving fast, so pin a version, read the changelog, and test before production. But the friction to try it is really low — a proxy and a base URL change — and the premise is solid: in a lot of agent workflows the bottleneck isn’t the model, it’s the volume of low-value context you’re paying to send it. Headroom is a clean and honest attempt to fix that, from someone who clearly thinks about cost at scale.
Are you already measuring how many tokens in your pipeline are boilerplate, or are you still paying the full bill without looking?