Headroom is an Apache 2.0-licensed context compression layer that sits between an AI agent and the model it calls, shrinking everything the agent reads — tool outputs, logs, files, RAG chunks, and conversation history — before those tokens reach the LLM. Since its first commit in January 2026 it has grown past 61,000 GitHub stars, a pace that reflects how sharply the economics of agentic coding have shifted. Long-running agents burn most of their budget not on the prompts a human writes but on the machine-generated text they consume, and Headroom attacks that specific line item. ## What It Does The project reports 60–95% token reduction on JSON data and roughly 15–20% on coding agents, with the same answers coming back. The gap between those two figures is the honest story of the tool: highly structured, redundant payloads compress dramatically, while prose and code — already information-dense — compress modestly. A demo in the repository shows a 10,144-token input reduced to 1,260 tokens with the same FATAL log line still found, which illustrates the JSON and log case well. Crucially, compression is reversible. Originals are cached locally through a mechanism the project calls CCR, and the model can call a `headroom_retrieve` tool to pull back the full content when the compressed version is not enough. That design choice matters: lossy context trimming becomes far less risky when the model retains an escape hatch to the original. ## Architecture Internally, a ContentRouter detects what kind of content it is looking at and dispatches to a matching compressor. SmartCrusher handles JSON, CodeCompressor works on code via AST parsing rather than naive text truncation, and Kompress-v2-base — a model published on Hugging Face — handles prose. A CacheAligner stabilizes prompt prefixes so that provider-side KV caches actually hit, which is a subtle but meaningful addition, since aggressive rewriting of a prompt can otherwise destroy the cache discounts that providers offer. Everything runs locally. For teams evaluating whether to route agent traffic through another service, the fact that Headroom is a local process rather than a hosted middleman removes a substantial category of data-governance objections. ## Four Ways to Deploy The project deliberately offers multiple integration points rather than forcing one. As a library, you import `compress` in Python or TypeScript and call it inline. As a proxy, `headroom proxy --port 8787` intercepts traffic with no code changes in any language. As an agent wrapper, a single `headroom wrap claude` command sets up a local proxy, installs Serena for semantic code navigation, and launches a configured agent session — with `headroom unwrap` to reverse it. And as an MCP server it exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client. The wrap command supports a long list of agents including Claude Code, Codex, Cursor, Copilot, Aider, Cline, Continue, Goose, and OpenHands. Two additional features go beyond compression. Cross-agent memory maintains a shared store across different agents with automatic deduplication, and `headroom learn` mines failed sessions to write corrections into `CLAUDE.local.md`, `CLAUDE.md`, `AGENTS.md`, or equivalent instruction files. There is also output token reduction, which trims what the model writes back by cutting ceremony and restated code rather than only shrinking what is sent. ## Usability Installation goes through PyPI as `headroom-ai` or via uv as a self-contained tool, and it requires Python 3.10 or newer. One packaging detail deserves attention: the CLI ships only through the PyPI package, while the npm `headroom-ai` package is a TypeScript SDK you import — installing it does not give you a `headroom` command. The project documents this explicitly, which suggests it has been a common source of confusion. A `headroom doctor` health check and a live savings dashboard help confirm the setup is actually working, which is important for a tool whose benefit is otherwise invisible. ## Pros and Cons The strengths are a genuinely broad integration surface, local-first operation, reversibility through retrieval, and content-aware compressors that treat JSON, code, and prose differently instead of applying one blunt strategy. The KV-cache alignment shows real attention to how token savings can be undone elsewhere in the stack. The caveats are worth stating plainly. Coding-agent savings of 15–20% are useful but far from the headline 60–95% figure, and readers who see only the larger number will be disappointed. The project carries over 500 open issues, which for a repository this young signals both heavy usage and a substantial backlog. Compression adds a processing step and, with the ML compressors enabled, real local resource cost. Any lossy compression carries some risk of dropping context that mattered, mitigated but not eliminated by retrieval. And a proxy in the request path is one more component that can fail. ## Outlook Context engineering has become its own discipline as agents run longer and consume more machine-generated text, and Headroom is one of the more complete attempts to treat it as infrastructure rather than a prompt-writing habit. The direction to watch is whether content-aware compression becomes a standard layer in agent stacks or gets absorbed into the agents and providers themselves. ## Conclusion Headroom is a well-engineered answer to a cost problem that grows with every hour an agent runs. It is most valuable for teams whose agents chew through large JSON payloads, logs, or RAG results, where the savings are dramatic. Teams running mostly code-focused sessions should calibrate expectations toward the lower end and trial it with the built-in dashboard before assuming the headline numbers apply to them.