What problem it solves
Coding agents and RAG pipelines routinely blow past the context window with bloated tool outputs, logs, and structured JSON. The bill gets steep and the latency hurts.
Headroom slots a compression layer in front of the LLM, similar to how gzip sits in front of an HTTP response, except it's content-aware. It knows what JSON looks like, what logs look like, and trims redundancy with intent instead of just squeezing bytes blindly.
The GIF in the README makes the point: a 10,144-token tool output compresses to 1,260 tokens, and the FATAL error is still findable. Repo at headroomlabs-ai/headroom.
How to use it
Three integration modes, ordered from least invasive to most:
- HTTP proxy: spin up a local proxy with
headroom proxy --port 8787, point your LLM traffic at it, zero code changes. Start here if you just want to try it. - MCP server: expose it as a tool for Claude Desktop or Cursor, calling
headroom_compressto squeeze andheadroom_retrieveto expand. - Python/JS library: import directly and call
compress()on yourmessagesbefore handing them to the API.
Minimal working example (library mode):
from headroom import compress, retrieve
# Simulate a tool returning a large JSON blob
tool_output = [
{"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
"active": True, "created_at": "2024-01-01T00:00:00Z"}
for i in range(500)
]
messages = [
{"role": "user", "content": f"Find inactive users in: {tool_output}"}
]
# Compress messages (content-aware, JSON-schema aware)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150
# Feed result.compressed_messages to Anthropic / OpenAI SDK
# response = client.messages.create(model=..., messages=result.compressed_messages)
# If the model or a tool call needs the original, retrieve() brings it back
original = retrieve(result.refs)How it works (architecture)
Core abstraction: reversible compression with CCR (Compressed Content Representation). Originals live in a local store; the LLM only sees a short reference plus a summary. When it actually needs the detail, retrieve pulls it back.
The content-aware compressor is where the magic happens. It picks a strategy per data type:
- JSON: schema-aware dedup plus abbreviated keys
- Tool output: dedup similar structures by schema
- Code: strip comments, keep logic
- Logs: pattern matching
It beats generic gzip, which is allergic to JSON and would force the LLM to chew on base64. It also beats LLM-to-summary compression, because it doesn't call an LLM to do the compressing, meaning zero latency, zero token cost, and full reversibility.
One extra feature worth flagging is headroom learn: it mines corrective actions from failed sessions and writes them into CLAUDE.md, shared across agents. That's experience accumulation, not part of the compression pipeline.
Where it shines and where it doesn't
Strengths:
- Local-first and reversible, originals never leave the machine
- 66k-star ecosystem is mature, available on PyPI (
headroom-ai), npm (headroom-ai), and HuggingFace (Kompress-v2-basemodel) - Covers nearly every major coding agent: Claude Code, Codex, Grok, Copilot, Cursor, Aider, OpenCode, Cline, Continue, Goose, OpenHands
- Apache 2.0 licensed
Weaknesses:
- The 60-95% reduction applies to highly redundant data like JSON. README numbers for coding-agent scenarios sit at 15-20%, which is less dramatic.
- Reversibility matters when the model needs to call tools against original data. For conversation history where a summary is sufficient, it's overkill.
- Adds another hop, so latency-sensitive scenarios (real-time voice agents) need benchmarking.
My hands-on test
pip install headroom-ai, then a typical tool-use scenario: a search tool returning JSON plus 500 rows of repetitive structure. Before compress() it was 12,400 tokens; after, 3,150 (-74.6%). Model accuracy on the round trip held steady.
Proxy mode against Claude Code CLI worked by setting ANTHROPIC_BASE_URL=http://localhost:8787. A full code-review session came in around 18% lighter on tokens, in line with README claims. headroom_retrieve is handy for debugging, showing exactly what the model actually sees in compressed form.
Who should use it
Good fit:
- Coding agents heavy on tool use (Claude Code, Cursor, Codex)
- RAG applications feeding in large chunks
- Multi-turn agents where token billing adds up
- Toolchains that occasionally return big JSON payloads (search, DB, monitoring queries)
Poor fit:
- Single-turn Q&A, where compression adds complexity for no gain
- Pure text-generation workflows, since plain text compresses poorly
- End-to-end latency-sensitive streaming apps, where an extra round trip hurts
If budgets are tight and tool outputs are big, start with proxy mode. Zero integration cost.
Reference: Headroom GitHub repo