Headroom: Compress the Input, Not the Output

Your agent reads 65,694 tokens to debug one SRE incident. headroom turns that into 5,118. Same answer.

The right side of the bill

LLM cost scales with what your agent reads, not just what it generates. The token bill of a coding agent is dominated by tool outputs: logs, grep results, file dumps, RAG chunks, GitHub issue bodies. Most of that text is noise. Repeated headers, redundant metadata, unused fields. The model still pays for all of it.

headroom compresses that input before it reaches the LLM. Apache 2.0, 7,600 stars in days, available as a Python library, a TypeScript library, a proxy, an MCP server, or a one-line wrapper around your existing agent.

How it actually works

A ContentRouter classifies each input chunk by type (JSON, code, prose, image) and dispatches it to a specialist compressor. Three today: SmartCrusher for JSON, CodeCompressor for AST-aware code in Python, JS, Go, Rust, Java, and C++, and Kompress-base, a HuggingFace model trained on agentic traces.

The originals are not lost. headroom stores them locally via CCR (Conversation Context Reversibility). The LLM gets the compressed version. If it needs a specific original back, it calls headroom_retrieve as a tool. A CacheAligner step also stabilizes prefixes so provider KV caches actually hit, which compounds the savings.

The proof (N=100 per workload)

Code search results: 17,765 → 1,408 tokens (92% off). SRE incident debugging: 65,694 → 5,118 (92%). GitHub issue triage: 54,174 → 14,761 (73%). Codebase exploration: 78,502 → 41,254 (47%).

The spread is honest: tool-noise compresses easily, while source code itself is denser and shrinks less. Accuracy on standard benchmarks holds: GSM8K stays at 0.870, TruthfulQA nudges up by 0.030, and BFCL (Berkeley Function Calling Leaderboard) clears 97% at 32% compression. BFCL is the agentic relevance number, since it measures whether the model still picks the right tool after compression.

Where it sits in the stack

This is not a replacement for Anthropic prompt caching or OpenAI cached input. Those are provider-side. headroom sits before the call, multi-algo, multi-provider, with reversibility built in. The categorical layer it occupies (input-side, reversible, cross-agent) does not have a vendor product yet. That is exactly why someone shipped a 7.6k-star library in days.

Skip it if

You only use a single provider's native compaction and you do not need cross-agent memory. If you do not run agents on logs, RAG chunks, or large tool outputs, you will not feel the gain.

Try it

pip install "headroom-ai[all]" && headroom wrap claude

Then run headroom stats on your own workload. The 92% number is from their bench, not yours. Reproduce before you ship it.