Headroom cuts a 55,957-token SRE log to 24,340 and claims the same answers

Headroom, a project from headroomlabs-ai, ships a compression layer that sits between an AI agent and the model it calls. It runs locally, intercepts tool outputs, logs, RAG chunks, files and conversation history, and shrinks them before the prompt goes out. The headline number: a 55,957-token SRE incident debugging payload compresses to 24,340 tokens, a 57% cut, and the project’s own demo shows 10,144 tokens reduced to 1,260 with “the same FATAL found.”

That last part is the whole argument. Token compression is not new. What Headroom is claiming is that the compression is lossless enough that the agent’s answer does not change, and that the overhead is small enough that no one notices it running. The README reports 0.21 ms p50 on a 10K-token JSON search result and 1.4 ms at 100K tokens. If those numbers hold on real traffic, the compression cost is noise next to a model call.

The benchmark table is the pitch, and it is honest about its limits

Headroom’s four proof scenarios are built from real MCP server output formats and measured with the provider tokenizer. Code search over 100 results goes from 17,199 to 13,597 tokens, a 21% cut. Codebase exploration drops 42%, from 58,801 to 33,895. GitHub issue triage saves 30%. The project is upfront that savings scale with repetition: “Repeated JSON arrays and log lines clear 90%,” while “prose and already-dense output compress very little.”

That candor matters. A compression tool that promised 90% everywhere would be lying. Headroom’s own accuracy evals are similarly restrained. On GSM8K math, baseline 0.870 and Headroom 0.870, delta zero. On TruthfulQA, 0.530 to 0.560, and the README explicitly says “at N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement.” SQuAD v2 hits 97% at 19% compression, BFCL 97% at 32%. Those are the numbers a skeptical engineer should actually read, because they are the ones where the project declines to overclaim.

The architecture is a pipeline: a ContentRouter detects content type, then routes to SmartCrusher for JSON, CodeCompressor for source code via AST, and Kompress-v2-base for prose. A CacheAligner flags volatile content that would bust a provider’s KV-cache prefix, and it “never rewrites prompts.” Originals are cached locally under a scheme called CCR, so the model can call headroom_retrieve when it needs the full text. That reversibility is the design decision that makes the whole thing defensible. Compression that cannot be undone is a gamble; compression with a retrieval escape hatch is a cache.

The output shaper is the part that will start arguments

Everything above shrinks the prompt. Headroom also trims what the model writes back, and this is where the project gets more interesting and more contestable. The README notes that “on Opus-class models output costs 5× input,” and that much of that output is ceremony: “Great, let me…” preambles, code re-printed straight back, reasoning spent on routine steps.

Two mechanisms do the work. Verbosity steering appends a short “be terse, don’t restate context” note to the end of the system prompt, positioned so the prompt cache still hits. Effort routing dials thinking effort down when a turn is only the model resuming after a tool result, like a file read or a passing test, while new questions and errors keep full effort. Both apply to Anthropic’s /v1/messages and OpenAI-compatible /v1/chat/completions and /v1/responses, using reasoning_effort on OpenAI and thinking.budget_tokens / output_config.effort on Anthropic.

The honest problem: output savings are counterfactual. You never see what the model would have written. Headroom says so directly and reports an estimate with a confidence band: “Reduction: 31.7% (95% CI 27.7% … 35.7%) [estimated].” For a measured number, you hold out 10% of conversations with HEADROOM_OUTPUT_HOLDOUT=0.1 and the dashboard switches from estimated to measured. That is the right way to ship a number you cannot directly observe, and it is more rigor than most agent tooling bothers with.

Compression that cannot be undone is a gamble. Compression with a retrieval escape hatch is a cache.

What it means for builders

The practical surface is wide. headroom wrap supports Claude Code, Codex, Grok CLI, Aider, Copilot CLI, VS Code Copilot, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe and more, with Cursor on manual setup and Cortex Code library-only. There is a proxy mode (headroom proxy --port 8787) for zero code changes in any language, a Python/TypeScript library, and an MCP server exposing headroom_compress, headroom_retrieve and headroom_stats. Cross-agent memory is a shared store across Claude, Codex, Gemini and Grok with automatic dedup.

The Copilot subscription routing is the most aggressive feature and the one to watch for policy friction. Headroom exchanges a reusable GitHub OAuth token for Copilot’s short-lived API token and routes subscription traffic through the local proxy. That is legitimate for a user who already pays for Copilot, but it sits close to the line of what providers want. Anthropic’s cache mode already forces a tradeoff: --mode cache skips automatic memory context injection so the provider prefix stays stable, and you need --mode token to get memory on the Anthropic path. Providers are not going to make this easier.

The broader read is that the agent economy has a token-bloat problem nobody priced in. Agents read enormous amounts of repetitive JSON, logs and file dumps, and every one of those tokens is billed. Headroom is a bet that the fix is a local, reversible, content-aware layer rather than smarter prompting or cheaper models. The 0.21 ms overhead and the retrieval cache suggest the bet is technically sound. Whether the output shaper survives contact with providers tightening their terms is the open question.