Headroom: How to Cut Up to 95% of Your Tokens Without Changing Your Responses
Every tool call your agent makes, every log it reads, every RAG chunk and file you feed into the 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 from Tejas Chopra, a Netflix engineer, and it’s been 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.
What it does, specifically
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 the 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 more. That’s the mechanism behind the promise of “the same responses”: 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 try. You don’t have to commit to an architecture: pick 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, far 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 while preserving response quality. Those are the project’s own benchmarks and, to be fair, they’re reproducible: you 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 in—. Instead of citing a percentage with false confidence, the README is honest that that saving can’t be directly observed: it reports an estimate with a 95% confidence interval (for example ~32%, with a stated range) and offers a real measurement path: 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 own 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. And the compress/retrieve round-trip adds a moving part: if the model abuses headroom_retrieve, you recover some of your savings back, so you’ll want to measure against your own traffic rather than trust the headline number.
Where it shines is the opposite profile: agents firing many tools and ingesting 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.
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?