Headroom

Headroom is a compression layer for the traffic an agent sends to a model. It comes in three shapes — a library whose whole API is one compress() call in Python or TypeScript, a FastAPI proxy that any OpenAI-compatible client can point at, and an MCP server exposing headroom_compress, headroom_retrieve and headroom_stats — plus wrapper commands that start the proxy and configure fifteen named coding agents. Inside, a ContentRouter decides what each content block is and hands it to exactly one compressor: SmartCrusher for arrays of JSON records, a search compressor, a log compressor, a diff compressor, an HTML extractor, tabular and config compressors, a text crusher, and an opt-in ModernBERT model called Kompress for prose. The heaviest of them run in a Rust extension loaded through PyO3, and Kompress runs through ONNX Runtime. Only the newest blocks are compressed, earlier turns are forwarded byte for byte so a provider prefix cache survives, and every compression is reversible because the original is written to a local store the model can retrieve from.

Who built itThe repository belongs to headroomlabs-ai, an organisation account rather than a personal one — its commit emails carry the headroomlabs.ai domain, and the README sells a supported or fully managed deployment alongside the open-source core. The largest single committer is chopratejas (Tejas Chopra), with 1,234 of the 3,000 commits in the sample; JerrettDavis follows with 373, abhay-codes07 with 169, gglucass with 139 and rodboev with 102, and dependabot accounts for 76. The contributor list names fifty accounts, and 2,984 of the 3,000 commits carry a linked GitHub account.

1. 01

   A nine-month-old repository with 74,192 stars, and nothing in the material that explains it

   The repository was created on 2026-01-07 and the newest commit in the sample is dated 2026-10-01; in between sit 3,000 commits, and the pull-request numbering has already passed #3896. The GitHub API on 2026-10-01 reports 74,192 stars, 5,734 forks, 219 watchers, 529 open issues, an 85 MB repository and an Apache-2.0 licence. Nothing in the material accounts for the size of that number. What the material does show is the machinery around it: a documentation site, a Discord, a PyPI package, an npm package that ships only the TypeScript SDK, a model published on HuggingFace, a Docker image, a README carrying a Trendshift badge reading “#1 Repository Of The Day”, a changelog of 533 KB, and a description that leads with two savings figures rather than with what the tool does. The one count that sits oddly beside the stars is the watchers: 219 of them against 5,734 forks.

2. 02

   One router, one compressor per content type, and savings figures with no method attached

   Three entry points feed one pipeline: compress() for Python and TypeScript, a FastAPI proxy whose per-provider handlers each run the same pipeline before forwarding, and framework adapters for LangChain, the Vercel AI SDK, Agno, Strands, LiteLLM and MCP adapters. A short ordered pipeline runs on every request — an opt-in tool-result interceptor, then a CacheAligner that only reports prefix drift, then the ContentRouter, which does essentially all of the work. The router detects the type of each block and dispatches it to exactly one compressor, and the project’s own architecture document prints a “typical savings” figure beside each: SmartCrusher for JSON arrays at 70–90%, search results at 80–95%, build and test logs at 85–95%, diffs at 40–80%, HTML at 70–90%, tables at 60–90%, structured config at 40–70%, plain text at 30–60%. Those numbers are the project’s own; they are labelled typical rather than measured, and the document supplies no corpus, run or method behind them. Every transform fails open — on an error the content is returned unchanged and the request still goes out.

3. 03

   The proof table states a method, and the accuracy table carries a caveat the author wrote himself

   The README has a Proof section built from four scenarios, and unlike the table above it says how it was produced: real MCP server output formats, the provider tokenizer, the shipped compress(), seeded and offline, with the command uv run python benchmarks/index_proof_table.py --seed 20260902. Code search 17,199 tokens to 13,597 (21%), an SRE incident 55,957 to 24,340 (57%), codebase exploration 58,801 to 33,895 (42%), GitHub issue triage 46,067 to 32,429 (30%) — every one of those figures is the project’s own. The same section says savings scale with repetition, that repeated JSON arrays and log lines clear 90% in benchmarks/bench_latency.py, that prose and already-dense output compress very little, and that compression costs 0.21 ms at the median on a 10K-token JSON search result. Accuracy comes from python -m headroom.evals suite --tier 1 at N=100 per benchmark, and the section then argues against its own table: “At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement.”

4. 04

   What the issue tracker records about fidelity

   The compression has documented failures, and the clearest is #3880, headed “Severity: silent data loss”: Kompress deleted whole records from single-line JSON tool output and left valid JSON behind, “so no parser, log line or model can tell”. The reporter describes the consequence in his own deployment — an agent repeatedly and confidently told a user that a data collection did not exist, and it did — and names the only mitigation then available, HEADROOM_DISABLE_KOMPRESS=1, which also switches off prose compression. The fix keeps record-bearing JSON away from the prose model on every route that reaches it, and along the way replaces a scanner that walked the same bytes repeatedly with a single linear walk: on a 58.8 KB brace-heavy block, 3.43 s became 0.011 s, checked against the previous walk on 4,000 random strings. Two smaller reports are the same theme: #3881 found one code path comparing a word count against a token count, so an unchanged code block looked like a 55% saving, and #3893 found a passthrough from an external compressor being adopted as a result, which let the block go out uncompressed.

5. 05

   The author’s own audit: the wrong mental model, and about 25,000 lines to delete

   A directory called REALIGNMENT holds fourteen documents and 193 KB of the project’s own diagnosis, and its executive summary opens with an indictment: Headroom “is built on the wrong mental model”, namely that compression means choosing what to drop from conversation history. The IntelligentContextManager tokenised the whole message array, scored each message and removed old ones until the budget was met, and it had been wired into the Rust proxy with frozen_message_count: 0 hardcoded, “so every compression event drops messages from index 0, busting the Anthropic prompt cache for every customer that triggers it”. The audit lists five cache-killer bugs that follow from that model, about 10,000 lines of architectural over-build, a Bedrock and Vertex parity it calls fake, CCR markers computed but never injected into the outgoing body, and X-Headroom-* headers leaking upstream. The plan is nine phases, forty pull requests, roughly thirteen weeks. The same material records the outcome: the context-manager stage was removed, and the scoring classes are gone from the Python package, though the TypeScript SDK still exports the field names “wired to nothing”.

6. 06

   Release cadence, the review machine, and two languages kept in step by recorded fixtures

   The twenty releases in the sample run from v0.26.0 on 2026-06-16 to v0.39.1 on 2026-09-26, and one week in August shows the rhythm: 0.36.0 on the 20th, then 0.36.1, 0.36.2 and 0.36.3 on the 21st, 0.36.4 and 0.36.5 on the 22nd. Commits by month run 135, 68, 165, 676, 334, 433, 581, 324, 276 and 8. Around that sits a review machine: twenty-three workflow files including a 28 KB ci.yml, a 50 KB release.yml, plus eval.yml, rust.yml, security.yml and pr-health.yml, with scripts for changelog generation, version syncing and pull-request governance. A bot comments on pull requests that leave required sections empty; a maintainer reviews at an exact head commit, reports how many focused tests passed locally next to ruff, mypy and the diff check, and states that he has authorised the maintainer-gated hosted workflows. The two languages are kept in step by recorded fixtures — 231 files under tests/parity/, covering the cache aligner, CCR, code-aware compression, content detection, diffs, Kompress, log compression, SmartCrusher, text crushing, the tokenizer and the Codex and OpenAI contract — and the co-author trailers tell their own story: of 1,168, about 466 name a Claude model and 129 say Copilot.