Headroom
headroomlabs-ai/headroomReviewed by AI
Checked by RepoPicks Radar on
What is Headroom?
Headroom sits between your AI coding agent and the model and squeezes what passes through: tool output, logs, files, search results and chat history. You can use it as a Python or TypeScript library, as a local proxy your agent points at, or as an MCP server inside Claude Code, Codex, Cursor and others. The compressing happens on your own machine. It is a developer tool: you install it with pip or uv and run commands. The repository's own benchmarks show 21% to 57% fewer tokens, depending on how repetitive the text is.
Headroom is free and open source (Apache-2.0) and can replace Compresr and The Token Company.
How easy is it to install Headroom?
C · install 1 or 2 tools · Windows
- Windows C
- macOS C
- Linux C
On all three systems you need Python 3.11 or newer and the terminal: `pip install "headroom-ai[all]"` (or `uv tool install`), then commands like `headroom wrap claude` or `headroom proxy --port 8787`. Ready wheels exist for Windows, Linux and Apple Silicon, so nothing has to be compiled; on Intel Macs the README sends you to the Docker install instead, which is harder.
Headroom on GitHub
- Stars
- 79,308on Nov 10, 2026
- Downloads
- 17,1931,439 this week
- Growth
- +557stars in 7 days
Stars over time
Facts
- Runs on
- Windows, macOS, Linux
- You need to install
- Python
- To build from source
- Python, Docker, Graphics card, Rust
- Disk space
- 15 MB–45 MB · from the installer
- Accounts or keys
- Your own model provider (Anthropic, OpenAI, Bedrock and others) — the key you already use passes through the proxy, Other (HEADROOM_PROXY_TOKEN) — a password you make up, needed only if you open the proxy to your network, GitHub (only for the Copilot subscription mode)
- Cost
- Free · Apache-2.0 and free to use. The same company sells a closed "Headroom Enterprise" with more savings; you still pay your own model provider for whatever tokens are left.
- License
- Apache-2.0 (Permissive)
- Can replace
- Compresr, The Token Company
- Last change on GitHub
- Nov 10, 2026
Headroom risk signals (9)
- AttentionInstall command runs a script from the internet
Install command pipes a remote script into a shell: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
automatic check
- Attentiontelemetry on by default
README.md "Telemetry": "An anonymous beacon is on by default. It reports how compression behaved: ratios, counters, provider and model IDs, OS and architecture." It says prompts and code are never sent, and you can switch it off with HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1 or HEADROOM_OFFLINE=1.
AI review
- Attentionsees all prompts and provider tokens
By design every request to the model goes through this local proxy, and for Copilot it also handles credentials: README.md, "headroom copilot-auth login stores a Headroom-specific Copilot OAuth token" and "The short-lived upstream Copilot token is held only in the proxy process." Anything that can read that process can read your prompts and tokens.
AI review
- Attentionopen data plane if exposed
docker-compose.yml header: "None of these three services authenticates inbound callers by default: the proxy's /v1/* data plane is open unless HEADROOM_PROXY_TOKEN is set, Qdrant has no API key... Publishing them on 0.0.0.0 therefore hands any peer on your network a relay through the proxy plus direct read/write on the embeddings and graph derived from your prompts." The shipped file binds everything to 127.0.0.1 to avoid that.
AI review
- Attentionedits other tools configuration
README.md: `headroom wrap` "installs Serena for semantic code navigation" as an MCP server in `~/.claude.json`, "injects config" for OpenCode, Cline and Continue, writes Claude Code's model selector with `--1m`, and `headroom learn` writes corrections into CLAUDE.local.md, CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md. There is an `unwrap` command to undo it.
AI review
- Infosavings depend heavily on content
The repository description claims "60-95% fewer tokens for JSON", while README.md's own four benchmark scenarios show 21%, 57%, 42% and 30%, and the text adds: "prose and already-dense output compress very little". The 31.7% output-token figure is marked "[estimated]" by the tool itself.
AI review
- Infofree version deliberately weaker
README.md "Headroom for teams": "Headroom OSS is a framework. It was built to show what's possible on one developer's laptop, so it saves less than it could. We are building bigger savings for teams and enterprises in Headroom Enterprise."
AI review
- Infobeta with very fast releases
pyproject.toml marks it "Development Status :: 4 - Beta" at version 0.42.0, and GitHub shows 175 releases for a repository created on 2026-01-07, with 471 open issues. Things change week to week.
AI review
- Infodownloads models and binaries at install or run
README.md "Corporate networks" section lists two download hosts it reaches on its own: cdn.pyke.io for the ONNX Runtime used by the Rust core and huggingface.co for the kompress-base model. It also notes the ONNX features need an AVX2 processor on x86 and fall back to simpler methods without it.
AI review
Evidence is shown in its original language.
What Radar could not check about Headroom
- Whether the answers really stay the same on your own prompts and tools
- What the anonymous beacon sends in practice
- Real disk use after the models, the local original-text cache (CCR) and the memory databases fill up
- How much money it actually saves on your bill, which depends on your workload
- Whether every listed agent still works with the current version, given the release pace