
headroom
Compresses tool outputs, logs and chat history before they reach an LLM to cut input
The repository was last updated yesterday and is published under Apache-2.0.
- Pricing
- Open source
- Platforms
- API, CLI, Web
- GitHub stars
- 79.9K
- Last commit
- 1 day ago
- Language
- Python
- License
- Apache-2.0
Similar MCP servers
About headroom
headroom is an open-source MCP server for ai models and llm tooling. It is available on API, CLI, Web, Linux, macOS, Windows, self-hosted and vscode.
The README describes Headroom as a layer that sits between an agent and its model provider, shrinking the content the agent reads before each call. It routes JSON, source code, logs and prose to different compressors, and keeps the removed originals in a local store so the model can fetch them back through a retrieval tool.
The package ships as a Python and TypeScript library, a drop-in proxy, and an MCP server exposing headroom_compress, headroom_retrieve and headroom_stats. The README says compression runs on the user's machine and that the savings it reports come from a seeded benchmark, so real results depend on how repetitive the payloads are.
It is aimed at developers building LLM apps and people running coding agents such as Claude Code or Cursor who want lower token costs without changing their code. The core is Apache 2.0 licensed, and the README points to a separate enterprise offering for larger savings and on-premise deployment.
Tools this server provides (3)
Taken from the project documentation; the running server may differ.
- headroom_compress
- Compresses content before it is sent to the LLM.
- headroom_retrieve
- Retrieves full original content that was compressed.
- headroom_stats
- Reports compression statistics.
What it does
- Reversible compression storage
- Removed content is cached locally so the model can retrieve the full original when it needs more detail.
- Content-aware routing
- Detects JSON, code, logs, text and diffs and applies a matching compressor to each.
- Drop-in proxy mode
- Runs as a local proxy on a port so existing clients can use it without code changes.
- Cache-stable prefixes
- Avoids rewriting earlier messages so provider prompt caches keep hitting.
- Cross-agent memory
- Shares one memory store across several coding agents with automatic deduplication.
- Usage metrics
- Provides a Prometheus endpoint, per-request logs and cost tracking.
Good for
- Reducing token spend for an app that forwards tool results or search hits to an LLM
- Cutting context size for coding agents like Claude Code or Codex without changing their setup
- Compressing build and test logs so an agent keeps the failures and drops passing output
- Sharing compressed context between agents in a multi-agent workflow
Pricing
Open source
Apache 2.0 open source; a separate Headroom Enterprise offering is mentioned but not priced.
Prices change. Check docs.headroomlabs.ai before you buy.
headroom FAQ
Does it require an API key?
The README says the Python library needs no API key and runs in-process, with no model download required for the core path.
What license is it under?
The README states that everything in the repository is Apache 2.0 licensed.
How are the savings measured?
The README reports results from a seeded benchmark script and notes that savings depend heavily on how repetitive the content is.
Which packages does the CLI come from?
The README says the headroom command ships only in the PyPI package; the npm package is a TypeScript SDK without the CLI.
Is headroom free?
Yes. headroom is open source, so you can use and self-host it for free.
What are the best alternatives to headroom?
The closest alternatives to headroom are SuperCompress, distil, LLMSlim memory, Kodelyth ECC and Toolc.
Where this comes from
- Description: written from the project's README and the project's website.