Every AI agent you run is drowning in noise. Stack traces that are 80% whitespace. JSON responses with a thousand fields when you needed three. Logs padded with timestamps for lines you didn't ask about. You're paying for all of it. Headroom stops that before the LLM ever sees it.
What It Is
Headroom is a context compression layer that sits between your code — or your terminal, or your coding agent — and the LLM. It squeezes everything going in before the model ever touches it, then optionally trims what comes back out. It runs locally, your data stays on your machine, and it's reversible.
It ships in three forms: a Python/TypeScript library, a drop-in HTTP proxy (zero code changes), and an MCP server. The numbers on their GitHub: 10,144 tokens → 1,260 tokens on a code search task. 92% reduction. Same result. They publish benchmarks and methodology, and they're reproducible.
Why It's Different
Most "token compression" tools truncate. They throw away the tail of your context window and hope what you needed was near the top. Headroom routes by content type to a purpose-built compressor:
- SmartCrusher handles JSON — collapses repetitive structure, keeps the signal
- CodeCompressor uses AST parsing for Python, JS, Go, Rust, Java, and C++ — it knows what's code and what's scaffold
- Kompress-base is a trained HuggingFace model for prose and unstructured text
- CacheAligner stabilizes your prompt prefixes so Anthropic and OpenAI's KV caches actually hit consistently (this alone saves money)
It's also reversible. The originals are cached locally via something they call CCR (Compressed Context Retrieval). If the LLM needs the full version of something, it can ask for it. You're not throwing data away — you're parking it.
Hands On
Install:
pip install "headroom-ai[all]"
The fastest path — zero code changes required — is proxy mode:
headroom proxy --port 8787
Point your OpenAI-compatible client at http://localhost:8787 instead of the upstream API. Every request gets compressed in transit. Nothing in your application code changes.
Or wrap a coding agent directly:
headroom wrap claude
headroom wrap aider
headroom wrap codex
After a session, check what you saved:
headroom perf
If you want to reduce output tokens too — stop the model from restating context and writing ceremony — enable the output shaper:
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
The Honest Part
The full [all] install pulls in ML dependencies and downloads the Kompress-base model from HuggingFace on first run. That's a wait. If you just want the JSON and code compressors without the ML model, install with fewer extras and skip the download.
The output token reduction numbers are estimates with confidence intervals, not hard measurements — because you can't measure what the model would have written. Headroom is honest about this in the docs, which is worth noting. The input compression is measurable and real; the output side is best-effort.
It also requires Python 3.10+. If you're on an older system, that's a hurdle. And if you're behind SSL inspection, the ONNX runtime and HuggingFace model downloads can hit cert issues — the README covers workarounds, but it's not trivial.
Verdict
The proxy mode is genuinely zero-effort to adopt if you're already using an OpenAI-compatible client. The AST-aware code compression is the part I find most credible — that's not a heuristic, that's the compiler knowing where the boilerplate is. The JSON crusher is similarly solid.
Who it's for: anyone running AI coding agents daily who's watching token costs add up or hitting context limits. If you use Claude Code, Codex, or Aider and you're not compressing your context, you're burning money on noise.
Not worth the setup if you only run an LLM occasionally or you're fine with your current context window. But if you're running agents hard — this is one of the more thought-through tools I've seen tackle this problem.
Go Try It
pip install "headroom-ai[all]"
headroom wrap claude # or aider, codex, cursor
headroom perf