What is Headroom?
Headroom compresses what an AI agent reads before it reaches the model: tool results, logs, search hits, RAG chunks, files and history. A router detects the content type and hands JSON to a statistical crusher, source code to an AST-aware compressor and prose to Kompress-v2-base, a small model the team trained on agent traces. Originals are cached locally so the model can ask for the full text back.
It ships as a Python and TypeScript library (`headroom-ai`), a proxy on port 8787, a one-command wrapper for Claude Code, Codex, Copilot, Aider and about 15 other agents, and an MCP server. Extras include shared memory across agents, `headroom learn`, which mines failed sessions for corrections to `CLAUDE.md`, and an opt-in output trimmer. Headroom Labs sells an enterprise edition alongside the Apache 2.0 code.
Is Headroom worth it?
The project publishes reproducible numbers instead of a single banner figure. On four seeded scenarios built from real MCP output formats it cut input tokens by 21% for code search, 42% for codebase exploration, 30% for issue triage and 57% for incident debugging, and repeated JSON arrays and log lines clear 90%. Prose barely shrinks. Compression takes 0.21 ms at the median on a 10,000-token JSON result, so it adds nothing noticeable to latency, and on small accuracy suites (100 questions each) scores stayed within the margin of error.
Independent use tells the same story with less flattering emphasis. The russ.cloud blog ran it for a few days of mixed interactive coding and saw 20.7% fewer tokens on 1.9 million, but the dashboard's dollar savings were mostly the provider's own prompt-cache discount ($47.36) rather than compression ($9.23), with 304 ms of proxy overhead per request; its author found `headroom learn` more useful than the compressor. A second review confirmed the token counts match provider records but doubted the bill always falls.
Adoption is real rather than viral: 466,346 PyPI downloads in the last month and 125,494 on npm, against 79,667 stars and 3,730 commits. Releases are frequent, v0.44.0 shipped on 10 November 2026.
The catch: an anonymous telemetry beacon is on by default (compression ratios, provider and model IDs, OS; no prompts or code), and the proxy sits in the path of every API key and request. Two advisories have been published, a high-severity cross-site WebSocket hijack in August and an arbitrary file read in the MCP server's read tool on 9 November 2026, both fixed.
Our take: on an agent that reads big JSON payloads, logs or search results, it pays for itself; for ordinary chat-style coding, RTK's command filters do much of the same job with less machinery.
Where it earns its place
An SRE team using Claude Code to debug incidents
Stop log dumps and metrics JSON from filling the context window
`headroom wrap claude` starts a local proxy for the session; the project's incident scenario fell from 55,957 to 24,340 tokens. The model can still fetch the original lines through the retrieve tool when it needs them.
A backend developer running a RAG API in Python
Cut input cost on long lists of retrieved chunks and database rows
Call `compress(messages, model=...)` before the provider call; it runs in-process with no key or network. Run `headroom evals` on your own traffic first, as reviewers suggest, to confirm answers do not change.
An engineer who keeps correcting the same agent mistakes
Turn repeated failures into standing instructions
`headroom learn` reads past sessions and writes corrections to `CLAUDE.local.md` or `AGENTS.md`; one independent tester rated this the most useful part. It costs nothing beyond the run.
Before you commit
- Setup
- `uv tool install --python 3.13 "headroom-ai[all]"`, then `headroom wrap claude` (or codex, copilot, aider and others); `headroom doctor` checks routing. Libraries: `pip install headroom-ai` or `npm install headroom-ai`.
- Integrations
- Claude Code, Codex, Copilot CLI and VS Code, Cursor (manual), Aider, OpenCode, Cline, Continue, Goose, OpenHands and more; Anthropic, OpenAI and Vercel AI SDK wrappers; LiteLLM, LangChain, Agno and Strands; MCP server.
- Data and privacy
- Compression runs locally and originals are cached on your machine. An anonymous beacon sends ratios, counters, provider and model IDs, OS and architecture by default; `HEADROOM_TELEMETRY=off` or `DO_NOT_TRACK=1` stops it.
- Cost at scale
- No licence cost. Savings scale with repetition: 90% or more on repeated JSON and logs, about 20% on mixed coding sessions in one independent test; prompt caching may already cover much of the dollar saving.
- Limits
- Prose and short prompts barely compress; the CLI needs Python; third-party OpenAI-compatible providers need an explicit upstream URL or the key goes to OpenAI; 302 open issues.
What’s good
- Reproducible benchmarks with honest per-scenario numbers
- Compression is local and reversible on demand
- Library, proxy, agent wrapper and MCP server from one package
- Large real usage: 466,346 PyPI downloads in a month
What’s not
- Little saving on prose and interactive coding
- Telemetry beacon on by default
- Proxy handles every key and request; two advisories since August
- Feature sprawl beyond compression
Best for
Teams whose agents or RAG pipelines push large JSON, logs or search results into the model and pay per input token.
Headroom alternatives
Headroom: common questions
- Is Headroom worth it?
- Headroom is the most rigorous of the token-saving add-ons, and its own numbers show the savings depend almost entirely on how repetitive your tool output is. We rate it 3.9 out of 5.
- How much does Headroom cost?
- Free and open source (Apache 2.0). Headroom Enterprise for teams is sold separately; pricing not published.
- What are the downsides of Headroom?
- Little saving on prose and interactive coding; telemetry beacon on by default; proxy handles every key and request; two advisories since August; feature sprawl beyond compression.
- Who is Headroom best for?
- Teams whose agents or RAG pipelines push large JSON, logs or search results into the model and pay per input token.
- How much does Headroom cost for a team or in production?
- No licence cost. Savings scale with repetition: 90% or more on repeated JSON and logs, about 20% on mixed coding sessions in one independent test; prompt caching may already cover much of the dollar saving.
- Is Headroom safe for company data?
- Compression runs locally and originals are cached on your machine. An anonymous beacon sends ratios, counters, provider and model IDs, OS and architecture by default; `HEADROOM_TELEMETRY=off` or `DO_NOT_TRACK=1` stops it.
- What are the best Headroom alternatives?
- The closest alternatives we have reviewed are rtk (Rust Token Killer), Caveman and OmniRoute.
Answers checked Nov 14, 2026.