RepoPicks Radar

Updated every day around 23:30 UTC

Guides

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

78,80079,00079,20079,400 Nov 4Nov 6Nov 8Nov 10 78,80079,00079,20079,400 Nov 4Nov 7Nov 10

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)
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

Similar projects

The RepoPicks app

Coming soon: install in 1 click with the RepoPicks app.

Before you download

See the release page on GitHub