Headroom

1. What is Headroom? (Headroom GitHub explained)

Headroom cuts the number of "tokens" your AI coding assistant has to read. A token is the unit AI services use for billing and limits, roughly a fraction of a word. While it works, a coding assistant (Claude Code, Codex, Cursor and the like) keeps reading command output, log files, JSON data and conversation history. Headroom sits between the assistant and the AI provider and compresses that material before it is sent, so you use fewer tokens for the same answers.

To be plain about it: this is a tool for developers and people who run AI coding assistants from the command line. There is no app to click through, and it does nothing for you if you only chat with ChatGPT or Claude in a browser.

Headroom is free and open source (Apache-2.0) for individual use. Compression happens on your own machine. The original content is kept locally, so the AI can fetch the full version when it needs it. The team also offers deployments for companies; contact them directly for that.

A good fit if:

• You use an AI coding assistant every day and keep hitting limits, or you pay per token.
• Your sessions are long and full of logs, search results and JSON.
• You want savings without changing your own code.

Not a fit if:

• Your exchanges are short. According to the docs, short conversations, prose and already-dense content see little or no reduction.
• You do not use an AI coding assistant yet, or are not comfortable with a terminal.

2. What you need

• A computer running Windows (64-bit), macOS or Linux. Version 0.39.1 ships prebuilt packages for Windows x86_64, macOS (Apple Silicon and Intel) and Linux (x86_64, aarch64).
• Python 3.10 or newer: the language Headroom runs on. Prebuilt packages target Python 3.10 through 3.13, and the docs recommend 3.13. Download from https://www.python.org/downloads/ . Python includes pip, its package installer.
• uv (optional, preferred by the docs): a tool that installs Python applications into their own isolated environment. Get it at https://docs.astral.sh/uv/
• An AI coding assistant, installed and signed in, such as Claude Code, Codex, Aider, Copilot CLI, OpenCode or Cline. You keep paying its provider as usual.
• Docker (optional): if you would rather not install Python, the project offers a Docker-based setup. See https://docs.headroomlabs.ai/docs/docker-install

Headroom itself needs no account and no API key.

The latest version at the time of writing is v0.39.1, released on 26 September 2026.

Note: The headroom command ships only in the Python package (PyPI). The headroom-ai package on npm is a library for TypeScript developers; installing it does not give you a headroom command.

3. How to install Headroom, step by step

Headroom has no .exe or .dmg installer. The command line is the only route; the steps below are the shortest path.

Step 1: Check Python

python --version

What success looks like: a version between 3.10 and 3.13. On macOS/Linux, if python does not work, try python3 --version.

Step 2: Install Headroom

With pip (included with Python; works on Windows, macOS and Linux):

pip install "headroom-ai[all]"

Or, if you have uv (the docs prefer this on Apple Silicon Macs and Linux):

uv tool install --python 3.13 "headroom-ai[all]"

The [all] part installs the full set of main components. The download can take a few minutes.

What success looks like: the command finishes without errors, and this prints a version number:

headroom --version

Step 3: Wrap your AI assistant

The easiest way in is the wrap command. It starts a local "proxy" (a relay running on your machine) and then launches your assistant already configured to go through it. For Claude Code:

headroom wrap claude

For another assistant, replace claude with its name: codex, aider, copilot, opencode, cline, continue, goose, openhands and so on. The full list is in the project README.

What success looks like: your assistant opens as usual and you work normally. Each time you want Headroom in the loop, start the assistant through headroom wrap rather than directly.

Note: The first wrap also installs Serena, an open-source tool that helps the AI navigate code by meaning, and registers it at user level. To skip that, add --code-memory none to the command.

Cursor needs a manual step: wrap starts the proxy and prints addresses for you to paste into Cursor's settings.

Step 4: Confirm it is working

Open a second terminal window and run:

headroom doctor

What success looks like: the health check reports that routing works.

4. First use

Once the assistant is wrapped there is nothing else to do. Give it a real task with plenty of data, such as reading a long log file to find the error line, or exploring a large code folder.

While the proxy is running, watch the savings on the dashboard:

headroom dashboard

Your browser opens http://localhost:8787/dashboard (an address that exists only on your machine) with live figures. To see savings in the terminal instead:

headroom savings

Do not expect one fixed number. In the project's published measurements the reduction depends on the type of content:

Scenario	Tokens before	Tokens after	Saved
Code search (100 results)	17,199	13,597	21%
Incident debugging	55,957	24,340	57%
Codebase exploration	58,801	33,895	42%
GitHub issue triage	46,067	32,429	30%

Highly repetitive data such as JSON arrays and log lines shrinks the most; prose and already-dense output barely shrinks.

If your assistant is not on the wrap list, run the proxy on its own and point any OpenAI-compatible client at it:

headroom proxy --port 8787

5. Common Headroom install problems and fixes

Symptom	Cause	Fix
Typing headroom gives "command not found"	Installed with uv but its tools folder is not on your PATH (the list of places the system looks for commands), or you installed the npm package by mistake	Run uv tool update-shell and reopen the terminal. If you used npm, reinstall with pip as in Step 2
On Windows the install stops and Windows Defender flags sg.exe as malware	A known false positive in a dependency (ast-grep-cli), not a Headroom problem	Open Windows Security, go to Virus & threat protection, Protection history, select the sg.exe entry, choose Restore, then rerun the install. The docs list running Headroom in Docker as the safest workaround
On Windows, linker link.exe not found during install	No prebuilt package matches your Python version, so pip tries to compile from source	Use a Python between 3.10 and 3.13 and reinstall, or use the Docker setup
pipx keeps installing an old version	pipx is using a Python version Headroom has no prebuilt package for	Uninstall it and reinstall with pipx install --python python3.13 "headroom-ai[all]"
pip install fails with CERTIFICATE_VERIFY_FAILED	A corporate network is inspecting SSL traffic	Install from a prebuilt package with pip install --only-binary headroom-ai headroom-ai. Details: https://docs.headroomlabs.ai/docs/corporate-networks
headroom proxy will not start, or hangs	Port 8787 is in use by another program, or the proxy components are missing	Try another port with headroom proxy --port 8788. If components are missing, run pip install "headroom-ai[proxy]"
The dashboard shows no savings	The session was short conversation with no tool output, or the data was too small to compress	Try a task with lots of command output, logs or JSON. This is a documented limitation: https://docs.headroomlabs.ai/docs/limitations

Official troubleshooting page: https://docs.headroomlabs.ai/docs/troubleshooting

6. Uninstalling and updating

Updating. Headroom works out how it was installed (pip, pipx or uv) and upgrades the matching way:

headroom update

To only check whether a new release exists:

headroom update --check

Uninstalling. Do it in this order.

First, put your assistant back the way it was. Replace claude with the assistant you wrapped:

headroom unwrap claude

If you registered Headroom as an MCP server for your assistant:

headroom mcp uninstall

Finally, remove the package with the tool you installed it with. For pip:

pip uninstall headroom-ai

For uv:

uv tool uninstall headroom-ai

Those last two are the standard uninstall commands of pip and uv.

7. Frequently asked questions

Does it cost anything? No. The open-source version is free for individuals. You still pay your AI provider as before, and the point of Headroom is to make that bill smaller.

Does it need an internet connection? Yes to install, and your AI assistant needs one anyway to reach its model. The compression itself runs on your machine.

Is my content sent anywhere? According to the docs, no prompt or file content is sent anywhere to be compressed. Headroom does send an anonymous statistics beacon by default: compression ratios, counters, provider and model names, operating system. It does not send prompts, completions, code or file paths. Turn it off by setting the environment variable HEADROOM_BEACON=off or DO_NOT_TRACK=1, or by running with --offline.

Will compression make the AI answer worse? The project publishes accuracy benchmarks showing essentially unchanged results, and the originals stay on your machine for the AI to retrieve when needed. Even so, check it on your own work before relying on it.

Will it run on a weak computer? The docs put compression time at under a millisecond for typical payloads. On older x86 machines without the AVX2 instruction set, Headroom falls back to simpler processing rather than failing.