Headroom

You adopt Headroom at whichever layer suits the codebase. As a library, you call compress(messages) in Python or TypeScript and hand the result to your existing model client. As a proxy, you run headroom proxy --port 8787 and point your SDK base URL at it, which needs no code change and works from any language. As an agent wrapper, headroom wrap claude (or codex, grok, copilot, cursor, aider, opencode, cline, continue, goose, openhands and others) configures that tool in a single command, and headroom unwrap reverses it. As an MCP server, it exposes headroom_compress, headroom_retrieve and headroom_stats to any MCP client.

Internally the content is routed by type rather than squeezed uniformly. A SmartCrusher handles JSON, an AST-aware compressor handles code, and a fine-tuned text model published on Hugging Face handles prose. A cache aligner runs first so that compression does not invalidate provider-side prefix caching and quietly cost more than it saves, and the reversible layer keeps every original retrievable rather than discarded.

• •Local-only compression - Everything is compressed on your own machine. No prompt, file or tool output leaves the host to be processed, so adopting it does not add a third party to your data path.
• •Four adoption surfaces - A Python and TypeScript library, a drop-in HTTP proxy, a one-command wrapper for roughly fifteen named coding agents, and an MCP server. You pick the one that fits rather than restructuring around the tool.
• •Type-aware routing - JSON, source code and prose go through different compressors, because the structure that can safely be dropped from a JSON payload is not the structure that can be dropped from a stack trace.
• •Reversible retrieval - Originals are cached locally and exposed back to the agent as a retrieval tool, so compression degrades context rather than destroying it and the agent can recover detail it discovers it needs.
• •Cross-agent memory - One shared store across Claude, Codex, Gemini and Grok with automatic deduplication, so context gathered in one agent is not re-fetched by the next.
• •Session learning - headroom learn mines failed sessions and writes corrections into CLAUDE.local.md, CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md, defaulting to the gitignored local file.
• •Output token reduction - Trims what the model writes back, not only what is sent to it, which is the half of the bill most token tooling ignores.

Developers and teams running coding agents at enough volume that token cost is a line item rather than a rounding error, and anyone whose agent sessions die on context-window limits in the middle of long tasks. The proxy and wrapper modes make it worth trying even if you did not write the agent, since neither requires touching its source. Teams under a security review will care that compression is local; teams running several different agents will care about the shared memory store.

It is a poor fit if your agent use is a handful of prompts a day, where the saving will not repay the setup, or if you need the enterprise capabilities (automatic model routing, injection filtering, central configuration), because those are behind a sales conversation with no published price. The compression figures the project quotes, around twenty percent on coding agents and sixty to ninety-five percent on JSON, are its own benchmarks and have not been independently reproduced. The project is also nine months old: the star curve is extraordinary but the track record is short.