Headroom: compress context before it reaches the LLM

TL;DR: Headroom compresses tool outputs, logs, files and RAG chunks before they reach the model. The project claims 20% fewer tokens for coding agents and 60-95% fewer for JSON payloads, and it ships in three shapes: a library, an HTTP proxy and an MCP server.

What it is

Context window pressure is the problem. Every tool call a coding agent makes returns a wall of JSON or a log dump, and all of it lands in the context window whether or not the model needs it. Headroom sits in front of that traffic and compresses it before the tokens are spent.

The repository is Python under Apache-2.0, owned by an organization, and it was created on 2026-01-07. It has 77,288 stars, 5,996 forks and 528 open issues, with documentation hosted at docs.headroomlabs.ai. The topic list is telling: agent, ai, anthropic, claude-code, compression and context-engineering.

Three ways to install it

The description names three delivery shapes, and the difference between them matters in practice.

Shape	Where it sits	What it compresses
Library	Inside your own process	Whatever you pass through it
Proxy	Between your agent and the model API	Requests and responses in flight
MCP server	As an MCP tool your agent can call	Tool output the agent pulls on demand

The proxy is the drop-in option, since it needs no code change in the agent, only a base URL change. The library is the option when you want to control exactly which payloads get compressed. The MCP server fits setups where your agent already speaks MCP and you would rather compression be a tool than a transparent layer.

The numbers

The repository description makes three specific claims, and the gap between the first two is the interesting part:

Workload	Claimed token reduction
Coding agent tool output	20%
JSON payloads	60% to 95%

Structured data compresses hardest because its redundancy is mechanical. Coding agent output sits in between because it mixes structured results with prose that carries meaning on its own. The third claim in the description is that the answers come back the same, which is the part you need to verify on your own data rather than take on faith.

How to try it

Start by reading the code, since the three delivery shapes share a core:

git clone https://github.com/headroomlabs-ai/headroom.git
cd headroom
ls

If you want the MCP server, register it in your client config. The binary path is whatever you installed it to:

{
  "mcpServers": {
    "headroom": {
      "command": "<path-to-headroom-mcp-server>"
    }
  }
}

When to use it

Headroom pays off when you pay per token on long agent sessions and your tool output is mostly machine-readable. Compression at the boundary means the model sees the same answer with fewer tokens attached, and on JSON-heavy workloads the reduction is large enough to change what a session costs.

When to skip it

Skip it when your payloads are mostly prose that has to survive verbatim, since that is where the claimed reduction shrinks. Also skip it if you cannot tolerate a component sitting in the request path that rewrites content before the model sees it. The project is young, created in January 2026, and carries 528 open issues against 77,288 stars, so expect the edges to be sharp.

Source and Accuracy Notes

• Project page: https://github.com/headroomlabs-ai/headroom
• Source repository: headroomlabs-ai/headroom (verified via GitHub API html_url)
• License: Apache-2.0 (verified via GitHub API license.spdx_id)
• Stars at time of writing: 77288