Headroom Review: Cutting AI Agent Tokens with Context Compression

Headroom is an open-source tool that compresses the tool output, logs, search results, files, and conversation history an AI agent sends to a model, shrinking input tokens before the content ever reaches the model. For coding agents such as Claude Code and Codex, you add it with a single headroom wrap line (for Cursor, you set the proxy address by hand), and in your own apps you can call the compress() function. As of November 13, 2026, it has 79,482 GitHub stars, and the latest version is v0.44.0. This post is an introduction and usage review based on the Headroom repository's README, release notes, official docs, and package registry listings, which I read on November 13, 2026. I did not install or run Headroom myself, and every figure, including the savings rates, comes from the project.

Screenshot: example dashboard image from the headroomlabs-ai/headroom GitHub repository (part of the v0.3.0 screen), Apache License 2.0

Key takeaways

• What is it? A tool that compresses tool output, logs, JSON, and conversation history between an agent and an LLM. According to the project, compression happens on your own machine, and the originals are stored locally so the model can retrieve them when it needs them.
• Four ways to use it: Python and TypeScript libraries, a local proxy, an agent wrapper (headroom wrap), and an MCP server.
• Savings reported by the project: input tokens drop 21-57% across four agent scenarios, and repetitive JSON arrays or log lines drop by more than 90%. Prose barely shrinks.
• Installation: run uv tool install --python 3.13 "headroom-ai[all]", then start with headroom wrap claude. Python 3.11 or later is required.
• Things to watch: anonymous usage statistics are sent by default, and frequent version updates sometimes include breaking changes. The official docs say the effect is small for short conversations and code-only sessions.

What kind of project is Headroom?

Every time an AI coding agent reads a file, runs a command, or searches, it sends the result to the model. Those results tend to be mixed with content the model does not really need to read: repeated JSON fields, thousands of lines of healthy logs, search results with the same structure. The project says savings grow with repetition. Headroom is a compression layer that trims that part before it reaches the model.

Based on the repository description and README, this is how it works.

• ContentRouter detects the type of content and hands it to the right compressor.
• The compressors are split by content type. JSON goes to SmartCrusher, source code goes to the syntax-tree-based CodeCompressor (which works only in a limited way by default; see the limitations item below), and plain text goes to Kompress-v2-base, a model the project trained itself and published on Hugging Face.
• CacheAligner only flags changing content that could break the provider's prompt cache, and the project says it does not rewrite the prompt.
• CCR (reversible compression) keeps the original locally and lets the model request the full text again with the headroom_retrieve tool.
• What gets compressed is the newly arrived part (the latest tool output, the last turn). The earlier conversation is left byte for byte as it was so the provider's prompt cache stays intact, and the project says it does not delete conversation history.
• The README stresses that prompts and file contents are not sent anywhere for compression; the work happens on your own machine. There is, however, a separate usage-statistics transmission, so check the cautions below.

Headroom project status

These are values I checked through the GitHub API and package registries on November 13, 2026.

The repository is only about ten months old, and recent official releases arrive every 5 to 12 days, so this is a fast-moving project. The v0.44.0 release notes list, under BREAKING CHANGES, a change that removed extra PyTorch-family packages from the [all] install, and they also add support for wrapping the Hermes agent. With features growing this quickly, it is safer to check the release notes whenever you upgrade.

Four ways to use it

Installation and usage

1. Attaching it to a coding agent

This is the sequence the README recommends for coding agent users.

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

headroom wrap starts a local proxy and launches the agent configured to go through that proxy. The proxy shuts down when the agent exits. According to the README table, Claude Code has the options --memory, --code-graph, --1m, and --tool-search. To undo it, use headroom unwrap <tool>.

To keep the proxy running after a reboot, the docs point to headroom deploy (local deployment and agent setup in one step) or headroom install apply.

2. Adding it to your own app

pip install headroom-ai

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

This function runs inside your process without an API key or a model download, and with the environment variable HEADROOM_OFFLINE=1 it reportedly makes no network access either. With default settings, only tool and assistant messages are compressed; to compress user messages as well, you need to pass compress_user_messages=True. The example above is the README's code, and because it has only a one-line message, it would barely shrink in practice. The design pays off in conversations with large tool output.

For a TypeScript app, install the SDK with npm install headroom-ai, but the compression itself is done by the local proxy. You need to start the proxy first with pip install "headroom-ai[proxy]" and then headroom proxy --port 8787. The npm package is only a library and does not include the headroom command.

3. Using only the proxy

This is the example from the official quickstart.

headroom proxy --port 8787

# Make Claude Code go through the proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# OpenAI-compatible client
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

4. Checking your savings

headroom doctor      # Health check: confirm routing works
headroom perf
headroom dashboard   # Live savings view (the proxy must be running)
headroom savings     # Savings based on your own traffic
curl http://localhost:8787/stats

There is no guarantee that the savings rates the project published will show up in your own work. The README also tells you to check the numbers for your own traffic with headroom savings.

5. Updating

headroom update figures out whether you installed with pip, pipx, or uv tool and upgrades the same way. To only check, use headroom update --check.

6. Installing on Windows

• The v0.44.0 release assets include wheels (prebuilt installers) for Windows (win_amd64), Linux, and macOS. The corporate-network section also says a Windows wheel exists, so you do not need to build Rust locally.
• There is separate guidance for environments where corporate security equipment inspects SSL. At runtime it reads the operating system's certificate store, you can verify with headroom doctor --network, and if no certificate is found, you set HEADROOM_CA_BUNDLE.
• To use it with a GitHub Copilot CLI subscription on Windows, the docs say to run headroom copilot-auth login first.
• In PowerShell, environment variables are usually set in the form $env:NAME = "value". The docs only show bash export examples, so I could not confirm how it behaves in PowerShell.
• Another README section says native wheels currently cover Apple silicon Macs and Linux, so the installation guidance is inconsistent within the docs. If installation gets stuck on Windows, check the wheel file list of the v0.44.0 release and the issue list first.

What you see on the Headroom dashboard

Screenshot: example dashboard image from the headroomlabs-ai/headroom GitHub repository (part of the v0.3.0 screen), Apache License 2.0

The lead image above and this one are example screens posted in the repository. They are not values I measured, and they come from v0.3.0, well behind the current version (v0.44.0), so the interface may look different now. The screen shows 128 requests, 388.0k tokens before compression becoming 245.0k after (143.0k saved, 36.9%), the removed content split into 95.0k of JSON boilerplate and 48.0k of repetition, and an overhead of 14ms. That 14ms appears to be the value for the whole request passing through the proxy (my interpretation), and because it measures something different from the README's compression-step figure (0.21ms) introduced below, the two cannot be compared directly. The screen is designed to show, in one place, how many tokens were cut, what was cut, and whether the provider's prompt cache stayed intact.

Performance evidence presented by the project

Input token savings

According to the README, four scenarios that mimic the output formats of real MCP servers were measured with the providers' tokenizers, and the random seed is fixed so anyone can reproduce the same numbers. The reproduction command is uv run python benchmarks/index_proof_table.py --seed 20260902.

The README adds that repetitive JSON arrays and log lines shrink by more than 90%, while prose and already dense output barely shrink. The time compression takes is reported as a median of 0.21ms for 10,000 tokens of JSON search results and 1.4ms for 100,000 tokens.

Accuracy

This table comes from the same baseline (python -m headroom.evals suite --tier 1).

The README itself explains that with only 100 questions, a difference of ±0.03 is within the margin of error, and it says TruthfulQA should be read as a difference that could not be confirmed rather than as an improvement. In my judgment, that reading is right. With 100 questions, the results only show a direction, that accuracy is maintained, and are not strong evidence. All figures are the project's own measurements, and I could not find third-party verification.

Can it reduce output tokens too?

Output tokens cost more than input tokens (the README puts it at 5 times as much on Opus-class models), so Headroom also has a separate feature that shortens answers at the proxy. It works by appending an instruction along the lines of "be concise" to the very end of the system prompt, so the prompt cache is reportedly preserved. It is off by default, and you turn it on like this.

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

Because there is no way to know how much the model would have written without the feature, the savings appear only as estimates. headroom output-savings labels them [estimated] with a confidence interval, and if you set aside 10% of conversations as a control group with HEADROOM_OUTPUT_HOLDOUT=0.1, they can be turned into measured values.

Supported agents and integrations

The README's compatibility table lists Claude Code, Codex, Grok CLI, Aider, GitHub Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Factory Droid, Kimi CLI, and ZCode as supported by headroom wrap, and it separates out Cursor as a manual setup where you start the proxy and enter the address, and Cortex Code as library-only. In v0.44.0, support for the Hermes agent was also added, according to the release notes. See also my earlier post on Hermes Agent, Hermes Agent 설치부터 Oh My Hermes 얹기까지 (in Korean).

On the framework side, the docs cover LangChain, LiteLLM, Agno, Strands, the Vercel AI SDK, wrappers for the Anthropic and OpenAI SDKs, and ASGI middleware. It also includes shared memory used by multiple agents, and headroom learn, which extracts corrections from failed sessions and writes them to files such as CLAUDE.local.md (the default, excluded from git), CLAUDE.md, and AGENTS.md.

Headroom's drawbacks and cautions

• The cases where it helps little are clearly defined. The official limitations doc says the effect is small, or the overhead can outweigh the gain, in short conversations, sessions that only read and write code, and one-off requests with no accumulated context. It does not compress messages under 50 tokens, system prompts, or images (which have a fixed token cost).
• The descriptions of code compression differ from document to document. According to the limitations doc, code in the last 4 messages is protected, and so is all code when the last user message contains words such as analyze, review, explain, fix, or debug. The README promotes a syntax-tree-based code compressor, but the quickstart table says source code compression is off by default (opt-in), and the limitations doc also says it applies to the latest tool output, so they conflict. For images, the README advertises 40-90% compression, while the limitations doc says they are only counted as a fixed token cost and are not compressed. I could not verify this myself, so I cannot say which is right; in my judgment, savings in coding agents are likely to come mainly from tool output such as JSON and logs. The limitations doc also still carries an old version label, "Headroom 0.37.0," so parts of it may be out of date.
• Anonymous usage statistics are on by default. It sends compression ratios, counters, the provider and model ID, and the operating system and architecture, and reportedly does not send prompts, responses, code, or file paths. To turn it off, use one of HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1, or HEADROOM_OFFLINE=1. The limitations doc says that if the value is not recognized, the data is still sent, so it is safer to use the exact values on this list. At startup the proxy also checks PyPI for a new version up to once a day (turn it off with HEADROOM_UPDATE_CHECK=off), and that too is a network request. If you work with company code, check your policy before turning it on.
• A misconfigured proxy can send your key somewhere else. When attached to a coding agent, requests go through the local proxy. The README warns that when you use a third-party OpenAI-compatible service (DeepSeek, OpenRouter, and so on), if you do not set the upstream address with --openai-api-url, the key is sent to the default upstream, OpenAI, and you get a 401 error.
• It changes quickly. Recent official releases come every 5 to 12 days, and v0.44.0 (released November 10) also had breaking changes. There are 299 open issues and PRs (a figure that includes PRs, so it says nothing about quality by itself). For a team setup, pinning the version and reading the release notes before upgrading is a good fit.
• The savings figures are the project's own measurements. The README describes the open-source project as a demonstration framework meant for a single developer's machine, with smaller savings than the team's own paid offering aims for. It says the team is building Headroom Enterprise for bigger savings and invites teams and companies to get in touch. It states that the repository itself will remain Apache 2.0 open source.

Who is it for?

• A good fit: people running agents with many tool calls or long sessions that produce large JSON and log output, people who want to cut API costs but use clients whose code they cannot change, and people who want several agents to share the same memory.
• Fine to skip: people who mostly have short conversations, or whose provider's built-in compression is enough and who need neither restoring originals nor memory shared across agents. The README also says Headroom may not be needed in these cases.
• If you want to try it: going by the docs, a safe order looks like this: run just one session with headroom wrap claude, check with headroom dashboard and headroom savings how much it actually saved in your own work, and move to an always-on setup such as headroom deploy only if it pays off.

Wrap-up

Headroom is a tool with a clear purpose: shrinking the repetitive output that agents read, locally. Going by the docs, its strengths appear to be local execution, restoring originals (CCR), one-line integration per agent, and reproduction commands you can run yourself. On the other hand, its effect depends heavily on how repetitive the input is, the published figures are its own measurements, and default usage-statistics transmission and rapid version changes are things to check before adopting it. This post is a summary based on the docs, so I recommend measuring your actual savings yourself with headroom savings.

Reference links

• headroomlabs-ai/headroom repository
• v0.44.0 release notes
• Official docs: Quickstart, Limitations