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.
What it does
Headroom is a context compression layer for AI agents and LLM apps that shrinks tool outputs, logs, RAG results, and conversation history by 60-95% before they reach the model. It runs as a transparent proxy, Python/TypeScript library, or MCP server, with no code changes required in proxy mode. Accu
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.
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.
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).
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.
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.
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.
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.
Features
Field notes
Reviewed Jun 26, 2026
Best for
Builder outcomes
Watch out
Tested with
Cost
="Licensed Apache 2.0 and free for commercial use. Savings are on downstream LLM token costs, not Headroom licensing fees."
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.
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`).
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.
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.
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.
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.
MCP gateway that gives AI agents like Claude Code, Cursor, and Codex one endpoint and one tool shape for every integration, with sandboxed execution and credential isolation by design.
Best for Teams running multiple MCP-compatible agents against a shared company tool stack