Headroom Labs · 2026-08-27 · major
Headroom v0.37.0 — the context compressor that now wraps 17 coding agents and trims what the model writes back
Headroom v0.37.0 (2026-08-27) adds a session-aware /v1/compress sidecar mode and unifies proxy and sidecar compression on one session engine. Since the June entry the project moved to the headroomlabs-ai org, grew from 7.7K to 70,947 stars, and added `headroom wrap` for 17 agents, output-token shaping (verbosity steering and effort routing), cross-agent memory, and `headroom learn`, which mines failed sessions into CLAUDE.md-style corrections.
Rewrites the conversation on its way to the API: a content router picks a compressor per payload type, keeps the originals locally, and lets the model ask for the full text back.
Key specs
| License | Apache-2.0 |
|---|---|
| GitHub stars | 70.9K |
| Forks | 5,439 |
| Agents wrapped | 17 |
| Compression latency (readme) | 0.21 ms p50 on a 10K-token JSON result |
| Accuracy suite (readme) | GSM8K 0.870 vs 0.870, BFCL 97% at 32% compression |
| Latest release | v0.37.0 (2026-08-27) |
Quick facts
| Maker | Headroom Labs (headroomlabs-ai) |
|---|---|
| Version | v0.37.0 |
| Forms | Python/TypeScript library, proxy, MCP server, `headroom wrap <agent>` |
| Compressors | SmartCrusher (JSON), CodeCompressor (AST), Kompress-v2-base (prose, on Hugging Face) |
| Install | uv tool install headroom-ai[all] / pip / npm (SDK only) |
| License | Apache-2.0 |
What is it?
Headroom sits between an agent and the model API. Everything about to be sent, including tool outputs, files, RAG chunks and history, goes through a ContentRouter that picks SmartCrusher for JSON, an AST-aware CodeCompressor for source, or the Kompress-v2-base model for prose. CCR caches originals so the model can call `headroom_retrieve` when it needs them. It runs as a library (`compress(messages)`), a local proxy, an MCP server, or `headroom wrap claude|codex|cursor|...` which starts the proxy and launches the agent through it.
How does it work?
Compression runs locally; the README states no prompt content leaves the machine to be compressed. v0.37 adds a session-aware sidecar endpoint and a self-limiting session state for the compression cache. Output-token reduction appends a terse-mode note to the end of the system prompt (so the cache prefix survives) and dials reasoning effort down on turns that only resume after a tool result. Output savings are reported as an estimate with a confidence interval, or measured with a 10% holdout.
Why does it matter?
Where RTK shrinks shell commands, Headroom shrinks the payloads RTK cannot see: structured tool results, search hits, API responses, long history. In a standalone bench it took a 100-hit JSON search result from 17,623 to 9,760 tokens while RTK could not touch it. In a small four-setup test on GPT-6 Astra (blog.toolsnetwork.ai/astra-token-burn), its edge on a JSON task was a fraction of a cent because the model scoped its own reads; on shell listings and prose it did nothing, by its own README's admission.