Python 3.10+ gets a library, proxy, and MCP server
Headroom has three credible entry points. Python and TypeScript applications can call compression directly, any compatible client can send requests through the local proxy, and MCP clients can expose compression, retrieval, and statistics as tools. The proxy also wraps coding agents and keeps original content in a local cache so the model can request detail later. That breadth is useful when logs and tool results consume more context than the work itself.
The breadth also explains our 2,333-file checkout and roughly 614,461 lines of source. Wrapping an agent does more than change a base URL: it starts the proxy, installs Serena for code navigation, and changes agent configuration. Serena is registered at user scope and remains available across projects until headroom unwrap reverses the setup. A developer should inspect those changes before using the one-command path on a shared workstation.
What happened when we ran it
Our sandbox installed Headroom in 409 seconds, adding 218 packages and occupying 6,039 MB. The build completed in 14 seconds. The checked-out commit was 954a5ff, run without secrets in an unprivileged Debian container with 3 CPUs and 8 GB of RAM. Pip-audit reported 0 known vulnerabilities in the installed Python environment. Those are respectable build and audit outcomes paired with an unusually large local footprint.
The test command did not finish within 900 seconds. Pytest was at 30% when the cap stopped it, after passing through custom telemetry, dashboard, dataset, diagnostics, Compose persistence, error-detection, and HTML extraction files. The final visible target was tests/test_evals/test_html_oss_benchmarks.py; the log did not print an assertion failure or identify a stuck test. We therefore have a timeout finding, not a passed suite and not evidence of a particular defect.
A 6,039 MB install changes the quickstart calculation
The README calls the first setup a 60-second process, but our all-extras install took 409 seconds before any model request. Headroom's dependency choices cover proxying, MCP, embeddings, file parsing, image work, evaluation, and multiple provider adapters. The repository includes a Dockerfile, a Compose file, a tests directory, and 23 CI workflow files, so the project has visible automation. None of that makes the 6,039 MB environment cheap on a laptop or CI runner.
The documented extras help narrow the load, although [all] is the main quickstart. Vector search is excluded even there and needs a C++ toolchain. ML use may fetch a compression model from Hugging Face and ONNX Runtime from another CDN. Python 3.14 tracks token savings but cannot display dollar savings because LiteLLM is unavailable on that interpreter. On x86 systems without AVX2, Headroom falls back to BM25 relevance and heuristic detection instead of the ONNX paths.
v0.37.0 leaves budget and cache boundaries open
Headroom v0.37.0 was released on August 27, 2026, with fixes across proxy authentication, file-read protection, session state, and output-savings recording. A newer open report, issue 3374 on budget bypass, reproduces OpenAI and Gemini requests reaching their upstreams after a zero-dollar budget is exhausted. The Anthropic control is rejected correctly. Treat the proxy's budget as reporting, not enforcement across every provider, until that behavior changes.
Issue 3346 on semantic-cache isolation is more serious for a shared gateway. With 2 upstream base URLs and identical Anthropic requests, the report receives gateway A's cached response for the request sent to gateway B, and gateway B is never contacted. The semantic cache is enabled by default according to the report. Operators routing tenants or trust zones to different upstreams should disable that path or reproduce isolation before sharing a proxy.
One v0.37.0 report sees compression stay near zero
The OpenAI chat-completions report tests repeated logs, JSON, and prose on Windows after installing the ML extras and trying documented configuration changes. It reports only 0 to 1% savings and sees tool-schema compaction rather than the content compressors. That single report does not measure every platform or endpoint, but it is directly about the feature buyers come for. Use a representative prompt corpus before assuming the README's savings claims apply.
Our run cannot settle compression quality because its 900-second test cap arrived during the suite and we supplied no provider secrets. A useful acceptance test should retain original prompts, compare answers on the tasks that matter, inspect when retrieval restores omitted content, and record provider cost outside Headroom. Reversible compression reduces the consequence of removing too much only when the retrieval tool is available and the model chooses it at the right time.
August 31 activity comes with 597 open items
GitHub recorded 68,231 stars, 277 open issues, 320 open pull requests, and a last push on August 31, 2026. Same-day reports and pull requests show that maintainers and users are working on the proxy rather than merely starring it. The volume also means behavior can move quickly between commits, and a release tag alone is a weak production pin. Read the issues for the provider and wrapper you plan to use.
Headroom is easiest to justify for one technical user who can observe the proxy, keep the 6,039 MB environment off a constrained machine, and remove it cleanly if compression hurts results. A team deployment needs provider-by-provider budget tests, cache isolation checks, protected local state, and a known rollback for agent configuration. The August 31 push is encouraging, but open v0.37.0 reports make those checks part of adoption rather than optional polish.