More than 76,000 GitHub stars and a spot on the daily Trending page on October 20, 2026: Headroom comes with a very specific pitch for anyone paying for agent tokens. It compresses what your agent reads (tool output, logs, RAG chunks, files and history) before it reaches the model, and it does so on your machine. In its showcase example, a 10,144-token log shrinks to 1,260 and the model still finds the same FATAL.
What it is and how it works
Headroom is a local layer that sits between your agent or app and the model provider (Anthropic, OpenAI, Bedrock…). You can use it four ways: as a library (compress(messages) in Python or TypeScript), as a proxy compatible with the OpenAI and Anthropic APIs, by wrapping a coding agent with headroom wrap, or as an MCP server.
Under the hood, a ContentRouter detects the content type and picks a compressor: SmartCrusher for JSON (it keeps errors, outliers and the first and last items of each list), an AST-aware CodeCompressor for Python, Go, Java, Rust and others, and its own model on Hugging Face, Kompress-v2-base, for prose. Two pieces set it apart from plain truncation:
- CCR (reversible compression): originals are stored locally and the model gets a
headroom_retrievetool to fetch the full text when it needs it. - Live-zone-only compression: only new content (the latest tool output, the latest turn) is compressed and the prefix stays byte-identical, so the provider's prompt cache keeps hitting.
On top of that there's cross-agent shared memory, headroom learn (it mines failed sessions and writes corrections to CLAUDE.local.md or other instruction files), and output-token reduction, off by default, which asks for terser answers and lowers reasoning effort on routine turns. The core mixes Python and Rust, there's a TypeScript SDK, and the license is Apache-2.0.
How to use it
The README recommends uv for the CLI; there's also a Docker image:
uv tool install --python 3.13 "headroom-ai[all]"
headroom doctor # checks that routing works
headroom proxy --port 8787 # drop-in proxy, no code changes
headroom wrap claude # or wrap a coding agent
headroom dashboard # live savingsIf you'd rather wire it into your code, the minimal example runs the messages through compress() before calling the client:
from headroom import compress
from openai import OpenAI
messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")Two warnings before you run it. headroom wrap is not side-effect free: it starts a local proxy, installs Serena as an MCP server and, for Claude Code, registers it in ~/.claude.json (headroom unwrap reverts it). And if you use an OpenAI-compatible provider other than OpenAI, such as DeepSeek or OpenRouter, you have to pass --openai-api-url; otherwise, the README warns, your key gets sent to OpenAI's API and comes back with a 401.
What I like and what I don't
I like that it shows how to measure. Its four scenarios built on real MCP server output are reproducible with a fixed seed, and the numbers are modest and believable: 57% savings debugging an SRE incident, 42% exploring a codebase, 30% triaging issues and 21% on code search. Compression costs 0.21 ms at the median on a 10,000-token JSON result. On accuracy, the README itself admits that with 100 samples the TruthfulQA gain is within the confidence interval. And the pace is relentless: 3,316 commits, 203 PyPI releases since January 2026, and 0.41.0 out on October 14, 2026.
What I don't: that pace is also a risk. It's still 0.x, with 259 open issues and a huge surface (proxy, memory, learning, effort routing, Copilot auth). The README admits prose and already-dense output barely compress, native wheels don't cover Intel macOS, and on networks with TLS inspection a source install can end up asking you to curl … | sh rustup. And putting a proxy between your agent and the provider adds one more component to maintain, one that handles your credentials in wrap mode.
Headroom vs. LLMLingua
The reference for prompt compression is Microsoft Research's LLMLingua, which uses a small language model to drop low-information tokens.
| Headroom | LLMLingua | |
|---|---|---|
| Approach | Per-content-type compressors (JSON, code, prose), reversible | Small model that removes expendable tokens |
| Deployment | Library, proxy, agent wrap, MCP, Docker | Python library; LangChain and LlamaIndex integrations |
| Built for | Long agent sessions with heavy tool output | Long prompts, RAG and general context |
| License | Apache-2.0 | MIT |
| Maturity | 0.41.0 (Oct 14, 2026), very active development | 0.2.2 (April 2024), backed by research papers |
When to use which: LLMLingua fits a Python RAG pipeline where you want a well-studied technique that, according to its authors, compresses text up to 20x. Headroom makes more sense when the spend comes from coding agents reading JSON, logs and files, because it understands those formats, keeps the provider cache intact and lets the model get the original back. I'd try it in proxy mode on a test environment first, and run headroom savings against real traffic before wrapping the whole team's agent.
Sources
- headroomlabs-ai/headroom (GitHub)
- headroom-ai on PyPI (PyPI)
- microsoft/LLMLingua (GitHub)