ERA OF MINDS

What is Headroom? Token compression for Claude Code, tested on real bills

By Era of Minds ·

Short answer

Headroom is a free, Apache-2.0 compression layer (headroomlabs-ai/headroom) that sits between Claude Code and the model and shrinks tool output, logs, JSON and history before they are sent. Setup is one command: headroom wrap claude. The README shows 21% to 57% fewer tokens on its test scenarios. Independent tests are mixed: fewer tokens, yes, but a lower bill only on heavy, tool-rich tasks, because compression can break the prompt cache. When we checked on October 19, 2026 the repo had about 75,930 stars and the latest release was v0.41.0.

Era of Minds cover: ‘Same answer. Fewer tokens.’ Headroom 0.41 context compression for Claude Code, with the README hero (55,957 to 24,340 tokens) and the headroom wrap claude terminal.
Figure: the hero graphic and the headroom wrap claude demo from the headroomlabs-ai/headroom README (Apache-2.0). 55,957 tokens in, 24,340 sent; the demo log dump drops from 10,144 to 1,260 tokens with the FATAL line kept.

What is Headroom for Claude Code?

Your agent opens a 10,000-token log to find one error. You pay for every line of it, and every later turn drags it along in context. That is the problem Headroom goes after.

Headroom compresses what the agent reads before it reaches the LLM: tool outputs, logs, RAG chunks, files and conversation history. It ships as a Python and TypeScript library (compress(messages)), a local proxy, an agent wrapper and an MCP server. The README says compression runs on your machine and no prompt or file content is sent anywhere to be compressed.

Inside, a ContentRouter picks a compressor per content type: SmartCrusher for JSON, an AST-aware CodeCompressor, and Kompress-v2-base, the project's own Hugging Face model, for prose. Originals are cached locally (the project calls this CCR, reversible compression), so if the model needs the full text it calls headroom_retrieve.

How do you set up Headroom with Claude Code?

Install the CLI. It ships only in the PyPI package; the npm headroom-ai package is the TypeScript SDK with no command.

pip install "headroom-ai[all]"

Then launch Claude Code through it:

headroom wrap claude

That starts a proxy on port 8787 and opens Claude Code with its API routed through Headroom. Run headroom doctor to confirm routing and headroom dashboard to watch live savings. headroom unwrap claude takes it back out. Python 3.10 or newer is required.

Other paths from the proxy docs and MCP docs:

  • Manual proxy: headroom proxy in one terminal, then ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude in another.
  • MCP tools only: pip install "headroom-ai[mcp]" and headroom mcp install. Claude Code gets headroom_compress, headroom_retrieve and headroom_stats, and compresses on demand instead of on every request. Originals are kept for 1 hour.
  • VS Code extension: headroom wrap vscode-claude, then reload the window and keep the wrapper running.

One thing to know before you run wrap: it also installs Serena for semantic code navigation, registered for that project only. Pass --code-memory none if you don't want it.

What does Headroom compress, and what does it leave alone?

It does best on repetitive, noisy payloads: JSON arrays from APIs and databases, build and test logs, shell output, and long sessions where tool results pile up. Its limitations page is upfront about the rest. Short messages, prose, already-dense output, and source code (which passes through to keep it correct) see little or no reduction. Blocks under min_input_words come back byte-identical.

There is also an output side. With HEADROOM_OUTPUT_SHAPER=1 (off by default) the proxy adds a short "be terse" note at the end of the system prompt and turns thinking effort down on routine turns, like resuming after a file read. headroom output-savings reports that as an estimate with a confidence range, because nobody can see what the model would have written.

How many tokens does Headroom save?

The README's seeded proof table, built from real MCP server output formats:

  • Code search (100 results): 17,199 to 13,597 tokens, 21%
  • SRE incident debugging: 55,957 to 24,340, 57%
  • Codebase exploration: 58,801 to 33,895, 42%
  • GitHub issue triage: 46,067 to 32,429, 30%

That works out to about 41% across all four. The repo's description sums it up as 20% fewer tokens for coding agents and 60% to 95% fewer for JSON. On accuracy, the README reports GSM8K unchanged at 0.870 and TruthfulQA within noise at N=100.

These are token counts on synthetic payloads. They tell you the compressor works. They don't tell you what your invoice will say.

Does Headroom actually lower your Claude bill?

This is where it gets interesting. Three outside tests, three different answers:

  • Brandon Barker (July 28, 2026), Claude on API billing, 25 SWE tasks picked to favor Headroom: token mode cut prompt tokens by 39% (215M to 132M). The bill barely moved. The average saving was $0.37 per task, smaller than the $0.73 gap he got from running nearly the same setup twice. Solve rates stayed flat (5 of 25 vs 4 of 25 baseline).
  • Ritza's Codex benchmark, 12 runs with gpt-5.5: on a small task, billed tokens went up 0.3%. On a heavy, tool-rich task they fell 24.6% on average (31% median), with about 15% more wall-clock time. All 12 runs shipped a working app.
  • PointFive (its own research, 103 tasks, 2,908 Claude Code runs): Headroom v0.27.0 showed a 48.4% higher pooled billed cost than unmodified Claude Code. PointFive notes it could not measure how much Headroom removed, since it works at the API boundary.

The reason is prompt caching. Barker's write-up puts numbers on it: at Sonnet rates, fresh input costs $3.00 per million tokens and a cache read costs $0.30. About 98% of his baseline prompt tokens were cache reads. Token mode busted the cache 123 times across 25 tasks, against 14 for the lighter cache mode, which pushed about 6 million tokens back to full price. Removing cheap tokens can cost you expensive ones.

Headroom knows about this. Cache mode is the proxy default, a CacheAligner flags content that would bust the provider prefix, and the 0.41.0 release notes are full of cache fixes for Claude Code (forks, re-serialized replies, prefix trackers). Older versions behaved differently, so treat the tests above as dated data points.

Headline numbers that shrink under outside testing are a pattern worth knowing. We found the same gap when we ran the Kronos AI trading model on Bitcoin: a real 93% gain on paper, and a model that lost to "no change" in 27 of 40 forecasts.

Headroom shrinks what an agent reads in one session. If the problem is that agents forget between sessions, or between tools, that is a memory job. Beacon records sessions across Claude Code, Codex and Cursor and turns reviewed lessons into memory any of them can fetch.

Headroom vs RTK: what's the difference?

RTK is a single Rust binary (about 83,900 GitHub stars when we checked) that filters output from common dev commands such as git status, cargo test and pytest before your agent reads it. Headroom sits further down the pipe, at the API boundary, and compresses every content type in the request, with retrieval of originals. They can stack. In the README demo, headroom wrap claude prints "Setting up rtk..." right after the proxy starts.

Should you use Headroom with Claude Code?

Try it if your sessions are dominated by big, repetitive tool output, if you keep hitting the context window, or if you run several agents and want the shared memory. Matching answers on 39% fewer tokens is a real context win even where the dollar win is unclear.

Skip it, or test hard first, if your work is mostly reading and writing code, your prompts are short, or your cache hit rate is already high. Then measure. Run headroom savings on your own traffic, compare it against your provider's billing page rather than the dashboard alone, and keep a few sessions without it as a control. The README even supports a 10% unshaped holdout for output savings (HEADROOM_OUTPUT_HOLDOUT=0.1).

Two defaults worth changing on day one if they matter to you: the anonymous telemetry beacon is on (turn it off with HEADROOM_BEACON=off or DO_NOT_TRACK=1), and wrap installs Serena unless told otherwise.

The README recommends Ponytail as a companion for leaner model output, and that pairing makes sense: Headroom trims what goes in, Ponytail trims the code that comes out. For plan maths, the Claude Code cost calculator shows whether API billing or a Pro/Max plan fits your usage. Other agent add-ons we've covered: earshot, Taste-Skill and book-to-skill, which makes its own token claims for book-sized context.

When we checked on the morning of October 19, 2026 (Asia/Dubai), the repo showed 75,930 stars and 5,904 forks, and the latest GitHub release and PyPI package were both v0.41.0 (published October 14 UTC). @LearnWithBrij's October 17 post on X had about 100,718 views, 1,042 likes, 2,205 bookmarks and 125 reposts.

Key facts

  • Product: Headroom, a context compression layer for AI agents. Library (Python, TypeScript), local proxy, headroom wrap agent wrapper, MCP server.
  • Repo: headroomlabs-ai/headroom (Headroom Labs). Apache-2.0. Top contributor Tejas Chopra (chopratejas). Docs docs.headroomlabs.ai.
  • Stars / forks (checked Oct 19, 2026 morning Dubai): about 75,930 / 5,904.
  • Version: v0.41.0 (GitHub release and PyPI headroom-ai, October 14 UTC). Python 3.10+.
  • Claude Code: pip install "headroom-ai[all]" then headroom wrap claude; undo with headroom unwrap claude. MCP only: headroom mcp install.
  • README numbers: 21% to 57% fewer tokens across four seeded scenarios (about 41% overall); demo log 10,144 to 1,260 tokens.
  • Independent tests: Barker 39% fewer tokens, no clear cost change (25 tasks); Ritza 24.6% fewer billed tokens on a heavy Codex task, +0.3% on a small one; PointFive +48.4% billed cost for v0.27.0.
  • X buzz: @LearnWithBrij post Oct 17 ~100,718 views / 1,042 likes / 2,205 bookmarks / 125 reposts (checked Oct 19).

FAQ

What is Headroom for Claude Code?

Headroom is a free, Apache-2.0 context compression layer from the headroomlabs-ai/headroom repo. It sits between Claude Code (or Codex, Cursor, Aider and other agents) and the model API, and shrinks tool outputs, logs, JSON, RAG chunks, files and history before they are sent. Compression runs on your machine, and originals are kept locally so the model can fetch them back with headroom_retrieve.

How do I use Headroom with Claude Code?

Install the CLI with pip install "headroom-ai[all]" (or uv tool install --python 3.13 "headroom-ai[all]"), then run headroom wrap claude. That starts a local proxy and launches Claude Code routed through it. You can also run headroom proxy and start Claude Code with ANTHROPIC_BASE_URL=http://127.0.0.1:8787, register only the MCP tools with headroom mcp install, or use headroom wrap vscode-claude for the VS Code extension. headroom unwrap claude undoes it. Python 3.10 or newer is required.

How many tokens does Headroom save?

It depends on how repetitive your context is. The README's seeded proof table shows 21% (code search), 57% (SRE incident debugging), 42% (codebase exploration) and 30% (GitHub issue triage), about 41% across the four. Its demo log dump goes from 10,144 to 1,260 tokens. Source code, grep results, short prompts and prose see little or no reduction.

Does Headroom lower my Claude bill?

Not reliably, based on the independent tests we found. Brandon Barker's 25-task Claude test (API billing) saw 39% fewer prompt tokens but a $0.37 per task saving that sat inside run-to-run noise, because compression broke the prompt cache far more often. Ritza's 12-run Codex test found no change on a small task (+0.3% billed tokens) and 24.6% fewer billed tokens on a heavy one, with about 15% more wall time. PointFive's own research reported a 48.4% higher pooled bill for Headroom v0.27.0. Measure it on your own workload.

What is the difference between Headroom and RTK?

RTK (rtk-ai/rtk) is a single Rust binary that filters the output of common dev commands such as git and test runners before the agent sees it. Headroom works at the API boundary as a proxy, library or MCP server and compresses all content types in the request, including tool results, JSON, logs and history, with reversible retrieval. They are not exclusive: in the Headroom README demo, headroom wrap claude prints 'Setting up rtk...'.

Is Headroom free and safe to run?

The open-source project is free under Apache 2.0; a paid Headroom Enterprise tier exists for teams. The README says no prompt or file content is sent anywhere to be compressed. An anonymous telemetry beacon (ratios, counters, provider and model IDs, OS) is on by default and never sends prompts, code or file paths; turn it off with HEADROOM_BEACON=off or DO_NOT_TRACK=1. headroom wrap also installs Serena for code navigation unless you pass --code-memory none.

Who made Headroom, and why is it trending?

The repo lives under the Headroom Labs GitHub org. Its top contributor is Tejas Chopra (GitHub chopratejas, 1,346 contributions), whose GitHub profile lists Netflix, Inc. An X post by @LearnWithBrij on October 17, 2026 calling it a fix for wasted tokens had about 100,718 views, 1,042 likes and 2,205 bookmarks when we checked on the morning of October 19. The repo had about 75,930 stars and 5,904 forks at that check, and the latest release was v0.41.0.

Sources

Keep reading