# headroom

> headroom is an open-source MCP server for ai models and llm tooling. Compresses tool outputs, logs and chat history before they reach an LLM to cut input. It is available on API, CLI, Web, Linux, macOS, Windows, self-hosted and vscode.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, CLI, Web, Linux, macOS, Windows, self-hosted, vscode
- **Website:** https://docs.headroomlabs.ai/docs
- **Repository:** https://github.com/headroomlabs-ai/headroom
- **GitHub stars:** 79,931
- **License:** Apache-2.0
- **Categories:** [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Tools

- `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.

## 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.

## Alternatives

- [SuperCompress](https://ai-powered.com/mcp/supercompress): SuperCompress is a freemium MCP server for ai models and llm tooling.
- [distil](https://ai-powered.com/mcp/distil-2): distil is a free MCP server for ai models and llm tooling.
- [LLMSlim memory](https://ai-powered.com/mcp/llmslim-memory): LLMSlim memory is an open-source MCP server for knowledge and memory.
- [Kodelyth ECC](https://ai-powered.com/mcp/kodelyth-ecc): Kodelyth ECC is an open-source MCP server for developer tools.
- [Toolc](https://ai-powered.com/mcp/toolc): Toolc is an open-source MCP server for ai models and llm tooling.
- [AsterMind MCP](https://ai-powered.com/mcp/astermind-mcp): AsterMind MCP is a free MCP server for ai models and llm tooling.
- [Repomix](https://ai-powered.com/mcp/repomix): Repomix is an open-source MCP server for developer tools.
- [MCP-Bridge](https://ai-powered.com/mcp/mcp-bridge-2): MCP-Bridge is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/headroom-3
