# Headroom

By **headroomlabs-ai** · MCP Servers

Context compression MCP server and proxy for AI agents, cuts token usage 60-95% across tool outputs, logs, RAG, and files while preserving answer accuracy.

- Source: https://headroomlabs-ai.github.io/headroom/
- Repository: https://github.com/headroomlabs-ai/headroom
- Install: `pip install "headroom-ai[all]" npm install headroom-ai headroom proxy --port 8787 headroom wrap claude headroom perf`
- Tags: open-source, mcp, proxy, compression, agent, python, typescript, local-first
- Pricing: free
- Upvotes: 0

## Features

- Three MCP tools: headroom_compress, headroom_retrieve, headroom_stats
- Transparent proxy mode, zero code changes, any language or framework
- Six content-type-aware compressors: JSON, AST/code, prose (ML), logs, search results, git diffs
- CCR reversible compression: originals stored locally, retrievable by hash
- CacheAligner: stabilizes message prefixes for provider KV cache hit optimization
- Cross-agent shared context store with auto-dedup across Claude, Codex, Gemini
- Output token shaper: verbosity steering and effort routing to trim model replies
- Prometheus metrics, cost tracking, budget limits, and live savings dashboard

---

## Why it matters

Token costs compound fast in agentic workflows. Every tool call, DB read, RAG retrieval, and log dump lands in the context window, most of it boilerplate the model does not need to reason well. Headroom intercepts that content before it hits the model, compresses it, and hands the LLM a retrieval tool to fetch full originals on demand, so nothing is thrown away.

## The big picture

Headroom is not a summarizer. It runs a three-stage deterministic pipeline: CacheAligner stabilizes message prefixes so provider KV caches actually hit; ContentRouter auto-detects content type (JSON, code, logs, diffs, HTML, plain text) and routes each chunk to the best compressor; IntelligentContext scores and trims messages that would overflow the context limit. Per the docs, Claude's 90% read discount on cached prefixes only materializes if prefixes are stable, CacheAligner makes that happen.

## How it works

The six compressors each do a different job. SmartCrusher uses statistical field-variance analysis on JSON arrays, keeping errors, anomalies, and boundary values. CodeCompressor is AST-aware via tree-sitter: it preserves function signatures and collapses bodies. Kompress runs ModernBERT token classification on prose to drop redundant tokens without changing meaning. The MCP surface exposes three tools: `headroom_compress` (on-demand), `headroom_retrieve` (full original by hash), and `headroom_stats` (session-level cost and savings tracking).

## By the numbers

On real agent workloads, per the README: code search over 100 results goes from 17,765 to 1,408 tokens (92% reduction); SRE incident debugging from 65,694 to 5,118 (92%); GitHub issue triage from 54,174 to 14,761 (73%). On standard benchmarks at N=100, GSM8K accuracy holds flat (0.870 delta zero), TruthfulQA improves slightly (+0.030), and BFCL tool-calling accuracy sits at 97% with 32% compression. These are reproducible via `python -m headroom.evals suite --tier 1`.

## Zoom in

The MCP server installs in one command: `headroom mcp install`, then `claude`. No proxy required for on-demand use. For automatic compression of all traffic, run the proxy alongside: `ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude`. Compressed originals live locally with a 1-hour TTL; the LLM calls `headroom_retrieve` with a hash to get the full content back.

## Yes, but

Output-token shaping is off by default and explicitly marked as producing estimated savings, not measured ones, unless you opt into a 10% holdout control group via `HEADROOM_OUTPUT_HOLDOUT=0.1`. ML compression (Kompress) requires PyTorch. The `[ml]` extra adds a non-trivial dependency footprint.

## The bottom line

Headroom is the most practical lever for cutting agent token costs without changing agent logic. The proxy mode requires zero code changes, the MCP mode gives the LLM direct control over compression, and CCR means no information loss. Requires Python 3.10+, licensed Apache 2.0, free for commercial use.

## FAQ

### What is Headroom and what problem does it solve?

Headroom is a context compression layer for AI agents and LLM applications that reduces token consumption by 60-95% on tool outputs, logs, RAG results, files, and conversation history before the content reaches the model. Every agent tool call, database read, or retrieval result tends to be 70-95% boilerplate the model does not need; Headroom compresses that noise away using six specialized algorithms. Critically, it is reversible: originals are stored locally in a CCR store and the LLM can retrieve them on demand via a hash key, so no information is permanently discarded.

### How do I install and start using Headroom?

Install with `pip install "headroom-ai[all]"` (Python 3.10+ required) or `npm install headroom-ai` for TypeScript. For the MCP server specifically, run `pip install "headroom-ai[proxy]"` or the lighter `pip install "headroom-ai[mcp]"`, then `headroom mcp install` to register with Claude Code, and finally `claude` to start a session with compression tools available. For zero-code-change proxy mode, run `headroom proxy` and point your app at `http://localhost:8787`. To wrap a coding agent in one step, use `headroom wrap claude` (or `codex`, `aider`, `copilot`, `opencode`).

### Is Headroom free? What is the license?

Headroom is open source under the Apache 2.0 license, which permits free commercial use. There are no usage fees from Headroom itself; you continue to pay your LLM provider for the tokens consumed, which Headroom reduces significantly. The library, proxy, and MCP server are all included in the open-source distribution.

### What kinds of workloads benefit most from Headroom?

Headroom delivers the largest savings on tool-heavy agentic workflows where individual tool calls return large JSON blobs, log dumps, grep results, or RAG retrievals. Per the README benchmarks, code search over 100 results compresses 92%, SRE incident debugging compresses 92%, and GitHub issue triage compresses 73%. It also helps multi-agent systems by providing a shared, deduplicated context store across Claude, Codex, and Gemini instances. Workloads with short, focused prompts that already fit comfortably in context will see less benefit.

### How does Headroom compare to just summarizing or truncating context manually?

Unlike manual summarization or naive truncation, Headroom uses content-type-aware compressors that preserve semantically important content: SmartCrusher keeps statistical anomalies and boundary values in JSON, CodeCompressor (via tree-sitter AST analysis) preserves function signatures while collapsing bodies, and LogCompressor retains errors and warnings while dropping passing noise. Crucially, it is reversible via CCR: a hash-addressed local store lets the LLM retrieve full originals when it needs them, which no truncation approach supports. Accuracy benchmarks at N=100 show GSM8K math scores hold flat and BFCL tool-calling accuracy stays at 97% with 32% compression.

### What are the main limitations or risks to know about?

ML-based text compression (Kompress) requires PyTorch, adding substantial install weight, use `pip install "headroom-ai[ml]"` only when prose compression is needed. Output token shaping is off by default, and savings estimates are counterfactual: Headroom reports a 95% confidence interval rather than an exact number, unless you opt into a holdout control group via `HEADROOM_OUTPUT_HOLDOUT=0.1`. Compressed originals in the local CCR store have a 1-hour TTL, so long-running sessions that pause and resume may lose retrieval access to early content. Cursor integration is manual; users must paste proxy base URLs into Cursor's settings rather than using an automated wrap command.

---
[View on Analog](https://analoghq.ai/pt-br/headroomlabs-ai/mcp-servers/headroom)