Headroom Compresses Agent Context Locally Before It Reaches the LLM
Headroom is an Apache-2.0 library, proxy, and MCP server that compresses tool outputs, logs, and RAG chunks locally, with reversible caching of originals.
Image source: https://github.com/headroomlabs-ai/headroom
What the project does
Headroom compresses what an AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before those payloads reach the model. The repository ships it in several forms: a compress(messages) library call in Python or TypeScript, a headroom proxy --port 8787 drop-in proxy, an MCP server exposing headroom_compress, headroom_retrieve, and headroom_stats, and an agent wrapper for a list of coding agents including Claude, Codex, Cursor, and aider. The project states that compression runs on the local machine and that no prompt or file content is sent anywhere to be compressed. Originals are cached locally under CCR and fetched on demand via headroom_retrieve, so the reduction is reversible.
Reported measurements
The README's stated framing of "same answers, fraction of the tokens" rests on numbers the project publishes itself. Four scenarios built from real MCP server output formats, measured with the provider tokenizer and the shipped compress(), are reported as seeded and offline: code search (100 results) 21%, SRE incident debugging 57%, codebase exploration 42%, and GitHub issue triage 30%. The project's own qualifier is that savings scale with how repetitive a payload is — repeated JSON arrays and log lines reportedly clear 90% in one benchmark script, while prose and already-dense output compress very little — and it directs users to run headroom savings against their own traffic. Compression is reported at 0.21 ms p50 on a 10K-token JSON search result and 1.4 ms at 100K tokens.
Accuracy and scope
On accuracy, the project reports GSM8K unchanged at 0.870 baseline and 0.870 with Headroom, and TruthfulQA at 0.530 baseline versus 0.560 — which the README itself notes falls inside the confidence interval at N=100, so it shows no detectable difference rather than an improvement. SQuAD v2 is listed at 97% at 19% compression and BFCL at 97% at 32% compression. These are the project's self-reported figures under the stated harness, not independent third-party results. Headroom also trims output tokens through verbosity steering and effort routing, which apply to Anthropic /v1/messages and OpenAI-compatible endpoints. Licensed Apache 2.0.