Headroom: Compress an Agent's Tool Output, Logs and Files Locally Before They Reach the LLM, With On-Demand Retrieval of the Original
headroomlabs-ai/headroom is an Apache-2.0 Python project with about 75,000 stars as of this writing. It compresses the tool outputs, logs, retrieval chunks and files an agent reads, on your machine, before they go to the model. Use it as a library, a proxy or a wrap command; originals are cached locally and can be fetched back. The README's benchmarks show 21% to 57% token savings, all from the project's own tests.
headroomlabs-ai/headroom is an open-source Python project under the Apache-2.0 license. It was created on January 7, 2026, last pushed on October 13, and has about 75,257 stars and 5,838 forks at the time of writing. Its pitch is one sentence: compress everything an AI agent reads, meaning tool outputs, logs, RAG chunks, files and conversation history, before it reaches the LLM, so that the answers stay the same and only a fraction of the tokens remain. The README stresses that compression runs on your machine and that no prompt or file content is sent anywhere to be compressed. It targets a common waste in agent use: a search returns a hundred results, or a log repeats the same line a thousand times, and all of it enters the context, takes up the window and is billed by the token.
The architecture has three parts. A ContentRouter detects the content type and picks a compressor: SmartCrusher for JSON, CodeCompressor for source code through the syntax tree, and Kompress-v2-base for plain text. CacheAligner only flags volatile content that would break a provider's KV-cache prefix, and the README says it never rewrites prompts. The key part is CCR, reversible compression: originals are cached locally, and the model can call headroom_retrieve when it needs the full text. That answers the usual worry about compression, which is losing information. Integration is flexible too. You can call compress(messages) in code, run headroom proxy as a drop-in proxy with no application change, wrap a long list of coding agents such as Claude Code, Codex, Cursor and Aider with headroom wrap, or expose three tools as an MCP server.
The project adds several related features. One is shared memory across agents, a single store used by Claude, Codex, Gemini and Grok, with automatic dedup. Another is headroom learn, which mines failed sessions and writes corrections to CLAUDE.local.md (the default, kept out of git), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md. A third is output-token reduction. Beyond shrinking what you send, the proxy trims what the model writes back, with two methods. "Verbosity steering" appends a short "be terse, don't restate context" note to the end of the system prompt, so the prompt cache still hits. "Effort routing" turns thinking effort down when a turn is only the model resuming after a tool result, such as a file read, and keeps full effort for new questions and errors. The README notes that on Opus-class models output costs five times input, so this part matters.
On data, the README's benchmark uses four seeded scenarios built from real MCP server output formats. Code search (100 results) goes from 17,199 to 13,597 tokens, a 21% saving. SRE incident debugging goes from 55,957 to 24,340, 57%. Codebase exploration goes from 58,801 to 33,895, 42%. GitHub issue triage goes from 46,067 to 32,429, 30%. The project says savings scale with how repetitive the payload is: repeated JSON arrays and log lines clear 90% in the latency benchmark, while prose and already dense output compress very little. Compression is fast, with a 0.21 ms median on a 10K-token JSON search result and 1.4 ms at 100K tokens. For accuracy at N=100, GSM8K is 0.870 for baseline and Headroom alike, and TruthfulQA goes from 0.530 to 0.560, which the project says is inside the confidence interval, so read it as no detectable difference. SQuAD v2 reaches 97% at 19% compression and BFCL reaches 97% at 32%.
How to use it safely? First, every figure is a self-reported benchmark on small samples. Run headroom savings on your own real traffic before you roll it out, and do not expect big gains on output that is already compact. Second, headroom wrap is not just a thin layer. It starts a local proxy and installs Serena for semantic code navigation in the wrapped project, which for Claude Code means registering a local-scope MCP server in ~/.claude.json. Use headroom unwrap to undo it, or skip it with a flag. Third, the originals are cached locally, but the compressed text is what the model sees, so keep that in mind when you debug agent behavior. Overall it is a clear, reversible and easy-to-try cost tool, and a good candidate to evaluate in a test environment first.
Sources
FAQ
What does Headroom compress, and how do I plug it in?
It compresses what an agent is about to send to an LLM: tool outputs, logs, RAG chunks, files and conversation history. Compression runs on your machine, and the README says no prompt or file content is sent anywhere to be compressed. There are four ways in: call compress(messages) in Python or TypeScript; run headroom proxy --port 8787 with zero code changes in any language; wrap a coding agent with headroom wrap claude, codex and others; or use it as an MCP server with headroom_compress, headroom_retrieve and headroom_stats.
How much does it claim to save, and can we trust that?
The README's benchmark uses four scenarios built from real MCP server output formats, seeded and reproducible offline. Code search (100 results) goes from 17,199 to 13,597 tokens, 21% saved. SRE incident debugging goes from 55,957 to 24,340, 57%. Codebase exploration goes from 58,801 to 33,895, 42%. GitHub issue triage goes from 46,067 to 32,429, 30%. The project adds that repeated JSON arrays and log lines can clear 90%, while prose and already dense output compress very little. These are the project's own tests. Run headroom savings on your own traffic.
Can compression make answers worse, and what should I watch?
In the project's accuracy table (N=100), GSM8K is 0.870 both with and without Headroom, and TruthfulQA goes from 0.530 to 0.560, but the project itself says that at N=100 a delta of ±0.03 is inside the confidence interval, so there is no detectable difference, not an improvement. SQuAD v2 is 97% at 19% compression and BFCL is 97% at 32%. Also note that headroom wrap starts a local proxy and installs Serena as an MCP server for the wrapped project. For Claude Code it writes a local-scope entry in ~/.claude.json, which headroom unwrap removes, and you can skip it with a flag.