22nd of 48 in Gateways and observability
headroom
Compresses tool outputs, logs and history before they reach the LLM
- Stars
- 79.4k
- License
- Apache-2.0
- Last commit
- Nov 2026
- Last release
- Nov 2026
- Language
- Python
1,478 on 20 Apr 202679,353 on 9 Nov 2026
From GitHub's daily star counts.
Checked on GitHub.
Overview
Headroom is a Python library, local proxy and CLI that shrinks agent context before it is sent to an LLM provider. It routes JSON, source code and text to separate compressors and keeps originals locally so the model can retrieve them. `headroom wrap` configures coding agents such as Claude Code, Codex, Aider and Cline to go through the proxy.
Who it is for: Developers cutting LLM input token costs in apps or coding agents
Ranked among open-source alternatives to OpenRouter (#2 of 10).
Strengths
- Seeded, offline benchmark: 21–57% fewer input tokens across four agent scenarios
- One-command `headroom wrap` for many coding agents, reversible with `headroom unwrap`
- Compression runs locally; reported 0.21 ms p50 on a 10K-token JSON result
- Originals cached locally and retrievable by the model via `headroom_retrieve`
Weaknesses
- Little savings on prose or already-dense output; gains depend on repetitive payloads
- Cursor and ZCode need manual base-URL setup; Cortex Code is library-only
- Third-party OpenAI-compatible providers need an extra flag or the key goes to OpenAI
- Output token reduction is off by default and reported as an estimate
What it needs
- no GPU
- Docker + Compose
- Needs Python 3.13 (for uv tool install), Serena (installed by headroom wrap), Kompress-v2-base model from Hugging Face
- Models: OpenAI, Anthropic, Bedrock, Gemini, OpenAI-compatible providers
- port 8787
What changed
“packaging: keep PyTorch extras out of all (#4067)”
GHSA-MC2F-VG4V-2FH4. “asgi: stop buffering when the client disconnects (GHSA-mc2f-vg4v-2fh4) (#4701) (c6d7081)”
“mcp: port MCP servers to SDK 2.x (#4603)”
GHSA-8G49-PG6G-XGRF. “mcp: confine headroomread to the workspace (GHSA-8g49-pg6g-xgrf) (#4525) (8ab2e91)”
From the release notes. No flag means the note does not say so, not that the upgrade is safe.
Quick answers
Is headroom open source?
Yes. Its code is on GitHub under the Apache-2.0 license.
Can you run headroom with Docker?
Yes. Its repository has a Docker setup: a Dockerfile, a Compose file or a published image.
Does headroom need a GPU?
No, it runs without one.
Head to head
Also in Gateways and observability
See all 48| Rank | Project | Score |
|---|---|---|
| 1 | OmniRouteLLM gateway routing one OpenAI-compatible endpoint across 372 providers | 96 out of 100 |
| 3 | new-apiGateway that unifies LLM providers behind OpenAI, Anthropic and Gemini APIs | 91 out of 100 |
| #4 | MLflowTracing, evaluation and prompt registry for LLM apps, plus ML tracking | 90 out of 100 |
| #5 | LiteLLMOpenAI-format gateway and Python SDK for calling 100+ LLM providers | 87 out of 100 |
| #6 | freellmapiOpenAI-compatible gateway pooling free-tier LLM providers with automatic failover | 86 out of 100 |