Headroom: A Local-First Context Compression Layer for AI Agents

What Headroom Solves and Who It Targets

Headroom addresses a specific cost: LLM context windows fill with verbose tool outputs, logs, and RAG chunks, driving up token usage and latency. The README targets AI agents like Claude Code, Cursor, Codex, and LangChain-based apps. The core claim is that you can compress this material before it reaches the model and still get the same answers. The savings are not uniform: 60-95% fewer tokens for JSON data, 15-20% for coding agents. The project positions itself as a 'context compression layer' that runs locally, which matters for teams with data privacy constraints. It is not a general-purpose prompt optimizer; it is specifically for the high-volume, structured data that agents ingest.

The Compression Pipeline: ContentRouter, SmartCrusher, and CCR

The architecture diagram in the README shows a pipeline: CacheAligner, ContentRouter, and CCR. ContentRouter detects the content type and selects a compressor. There are three named compressors: SmartCrusher for JSON, CodeCompressor for AST, and Kompress-v2-base for text, the latter hosted on Hugging Face. CacheAligner detects volatile content that could break provider KV cache prefixes, but it never rewrites prompts. The reversible CCR stores originals locally; if the LLM needs the full text, it can call `headroom_retrieve`. This design is a trade-off: compression is lossy by default, but the original is not destroyed. The README gives a live example: 10,144 tokens compressed to 1,260, with the same 'FATAL found' result. That example is anecdotal, but it illustrates the mechanism: the compressor strips formatting and redundancy while preserving semantic markers.

Installation and Modes: Library, Proxy, Wrap, and MCP

You can install via `uv tool install --python 3.13 "headroom-ai[all]"` or `pip install "headroom-ai[all]"`, both of which ship the `headroom` CLI. The npm package `headroom-ai` is only a TypeScript SDK, not a CLI, so pick the Python route for the full tool. After install, there are four modes. The library: call `compress(messages)` in Python or TypeScript. The proxy: run `headroom proxy --port 8787` to intercept traffic without code changes. The agent wrap: `headroom wrap claude` or other tools, and undo with `headroom unwrap`. The MCP server: expose `headroom_compress`, `headroom_retrieve`, and `headroom_stats`. The README warns that a wrapped agent session is recommended each time, because wrapping starts a local proxy and installs Serena for semantic code navigation. Serena is registered at user scope, so it persists across projects until you unwrap. You can skip it with `--code-memory none`.

Configuration and Extras: What You Need to Know

The package has granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`, and `[pytorch-mps]`. The `[vector]` extra is optional and requires a C++ toolchain; it is not in `[all]`. Python 3.10+ is required. For Apple GPU users, `[pytorch-mps]` offloads the memory embedder, and you set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`. The README also covers a Codex-specific issue: if an MCP client cannot inherit the shell `PATH`, install Headroom as a persistent uv tool and use the absolute binary path in the MCP config. The example shows a TOML block with `command = "/absolute/path/from/command-v/headroom"` and `args = ["mcp", "serve"]`. This level of detail is useful, but it also signals that setup is not always turnkey, especially across different agent environments.

Output Token Reduction and `headroom learn`

Beyond input compression, Headroom claims to trim what the model writes back. The README says it 'drops ceremony/restated code and skips deep thinking on routine steps.' This is a more aggressive feature, because it alters the model's output, not just the context. The `headroom learn` command mines failed sessions and writes corrections to `CLAUDE.local.md` by default, or to `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or `GROK.md`. This is a feedback loop: the system learns from failures and adjusts future behavior. The README does not detail how the learning is validated, so the risk of over-correction or unintended prompt changes is unclear. This feature is optional, but it is a notable departure from a pure compression tool, because it writes persistent files that affect agent behavior.

Limitations and Failure Modes

The most obvious limitation is that compression is lossy. The README says 'same answers' but also describes a reversible CCR that stores originals, implying that the compressed form may not always suffice. If the LLM needs a detail that was stripped, it must call `headroom_retrieve`, which adds latency and requires the client to support that call. Another failure mode: the `[vector]` extra needs a C++ toolchain, which can break in environments without build tools. The README also notes that the npm package does not include the CLI, so a team expecting a unified install might be confused. The proxy mode intercepts traffic, which could introduce a single point of failure; if the proxy crashes, the agent loses access. The README does not discuss error handling for the proxy or the MCP server, so resilience in production is unverified.

Alternatives and How They Differ

A direct alternative is to use a rule-based token truncation library, such as `tiktoken` for counting and then slicing context to a fixed budget. That approach is simpler and lossless in the sense that you keep the first N tokens, but it discards information arbitrarily. Headroom's content-aware compressors preserve semantic structure, which is better for JSON where field names repeat. Another alternative is a dedicated RAG chunking tool like `LlamaIndex` or `LangChain` text splitters, which break documents into chunks before embedding. Those tools do not compress; they segment. Headroom compresses after retrieval, which is a different stage. The closest comparison is to a semantic compression model like `Kompress-v2-base`, which Headroom itself uses for text. If you want to avoid a dependency on a Hugging Face model, you could use a pure JSON minifier, but that would not handle prose or code. The choice depends on whether your workload is JSON-heavy, code-heavy, or prose-heavy.

Maintenance, Licensing, and Upgrade Cost

The project is under Apache-2.0, which permits commercial use and modification without copyleft obligations. The last push was August 2026, with version 0.37.0 released the same day, so the project is actively maintained. The release cadence (three versions in five days) suggests rapid iteration, which is good for bug fixes but means you should pin versions in production. The README references a CI workflow and Codecov, but it does not provide upgrade notes or a changelog. The cost of maintenance is that the system has multiple moving parts: a proxy, an MCP server, a model (Kompress-v2-base), and optional vector backends. Each component needs updates when the underlying model or protocol changes. The `headroom unwrap` command exists to remove agent wrapping, which helps, but the Serena installation at user scope may persist until you manually unwrap, so cleanup is not fully automatic.

Editorial conclusion

Headroom is for engineering teams running coding agents or RAG pipelines that hit token limits or cost ceilings on JSON-heavy workloads; the 60-95% savings on structured data are the strongest argument. It is not for teams that need lossless context or distrust local caching of conversation history, since the reversible CCR still stores originals on disk. Before adopting, verify that the compression preserves answer quality on your specific workloads by running the `headroom evals` extra and comparing outputs with and without compression. Also check Python 3.10+ compatibility and whether the optional `[vector]` extra's C++ toolchain requirement fits your build environment. If you need simple, lossless context trimming, a rule-based token truncation library may be simpler; if you need semantic compression with retrieval, consider a dedicated RAG chunking tool.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes