headroom: Compress Context for AI Agents

Overview

Headroom is a local context-compression layer for AI applications and coding agents. It reduces the size of inputs such as tool results, logs, source code, and RAG chunks before they are sent to an LLM, aiming to lower token use without losing information needed for the task.

It can be integrated as a Python or TypeScript library, run as a proxy, or used through an MCP server. It is most relevant to developers with long agent sessions or repetitive, high-volume tool output; short conversations and already concise text may see little benefit.

Key Features

• Routes JSON, source code, and prose to different compression methods.
• Provides Python and TypeScript libraries, a local proxy, and MCP tools.
• Wraps several coding agents so their traffic can pass through the proxy.
• Stores originals locally for retrieval through its reversible compression flow.
• Offers shared context and memory across supported agents.
• Includes optional output-shaping controls and session-learning tools.
• Reports token savings and includes benchmarking and evaluation commands.

Use Cases

• Developers running coding agents can reduce repeated logs, file contents, and tool results in long sessions.
• Teams using multiple agent clients can share context and memory across supported tools.
• Application developers can compress LLM inputs inline through the Python or TypeScript SDKs.
• Operators can route OpenAI-compatible traffic through a local proxy without changing application code.
• MCP users can add compression and retrieval tools to compatible clients.

Getting Started

Install the Python package and its core integrations:

pip install "headroom-ai[all]"
headroom proxy --port 8787

For other install options, agent setup, and configuration, see the README and documentation.

Alternatives

• mcp-gateway: MCP Gateway reduces context overhead by consolidating tools behind one endpoint, while Headroom compresses tool outputs and other context.

Considerations

• Savings depend on the content. Repetitive structured output may compress substantially, while prose and already-dense content may change little.
• Compression is intended to preserve useful information, but the README presents benchmark results rather than a guarantee for every workload. Test against your own inputs.
• The CLI is provided by the Python package; the npm package is a TypeScript SDK and does not include the CLI.
• The project supports optional dependencies and integrations, so some capabilities require installing extra packages. The README lists Python 3.10+ as the requirement.
• Anonymous usage telemetry is enabled by default and can be disabled with HEADROOM_BEACON=off, DO_NOT_TRACK=1, or --offline.
• Compression runs locally, but requests still go to the LLM provider configured by the user.