~/guides/SAVE.md

Guides / Claude Code

Headroom: Claude Code does the same work on fewer tokens, so your usage limit lasts longer

A free, open-source tool that sits between Claude Code and the model and compresses logs and tool output first. Install, headroom wrap claude, savings, limits.

Claude Code's usage limit is often eaten not by your question but by what it reads: a long log, hundreds of search results, a big JSON dump. Headroom is a free, open-source (Apache 2.0) tool that sits between Claude Code and the model, compresses that tool output, keeps what matters and then sends it on. This is the full version of the SAVE reel: the real numbers we got on our own machine, the install commands, how to hook it into Claude Code with headroom wrap claude, how to see what you saved, and when it saves nothing.

01The result first: the same debugging task, 55,957 tokens down to 24,340

Reel frame: Headroom's benchmark in a terminal on a 3D laptop, the SRE row 55,957 to 24,340 (57%) circled
Real run: we re-ran Headroom's own benchmark script on our machine and got exactly the numbers in the README.

When you are done, you get this:

  1. You use Claude Code as usual, but the tool output it reads (logs, search results, JSON) is compressed on your own machine before it goes to the model.
  2. Repeated content is squeezed out; important lines such as errors are kept.
  3. One command shows how many tokens you saved.
  4. Reading less means the same usage limit lasts longer.

02Step 1: install Headroom

Reel frame: the headroomlabs-ai/headroom page on GitHub, Star 78.7k circled, the Apache-2.0 license highlighted
Headroom on GitHub: Apache 2.0 licence, about 79K stars on 3 Nov 2026.

Headroom is an open-source project by headroomlabs-ai and needs Python 3.11 or newer. Open a terminal and pick one way to install it:

Install (pip)
pip install "headroom-ai[all]"
Other way (uv, in its own environment)
uv tool install --python 3.13 "headroom-ai[all]"

Then run a health check once:

Check
headroom doctor

03Step 2: start Claude Code with headroom wrap claude

Reel frame: the How it works diagram in the README, the Headroom box between Claude Code and the model circled green
The README diagram: Headroom runs on your machine, between Claude Code and the model.

From now on, start Claude Code with this line:

Start Claude Code (through Headroom)
headroom wrap claude

That command does three things:

  1. Starts a local proxy on your machine.
  2. Installs Serena (an MCP tool for navigating code) for this project only.
  3. Launches Claude Code through that proxy. Then just type as usual; what gets sent goes through Headroom first.
Reel frame: Get started in the README, the headroom wrap claude line circled, a dark command card below
Get started in the README: install, then start with headroom wrap claude.

To skip Serena, or to wire it up by hand:

Without Serena
headroom wrap claude --code-memory none
By hand: start the proxy, then point Claude Code at it
headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 claude

04Step 3: see what you saved, and use it on the right work

Reel frame: our own run, node --test 0% saved marked red, npm ls --all --json 27% saved marked green
Real run: the same tool saved nothing on plain test output and 27% on npm ls JSON.

While headroom wrap claude is running, open another terminal to watch the savings live:

Live savings
headroom dashboard

Headroom helps most when Claude Code has a lot of output to read:

  1. Long, repetitive logs and build or test output.
  2. JSON from APIs, database query results, hundreds of search results.
  3. Long sessions with many tool calls, where output keeps piling up.

For work like that, just ask Claude Code to read it and let Headroom compress it:

A good fit (swap in your file)
Read [a log file or command, e.g. logs/server.log], find the first error, why it happened and the most likely fix.

05Do the answers get worse?

Reel frame: the README Accuracy table, the GSM8K row circled, 0.870 and 0.870 highlighted green
From the official README: GSM8K maths, 0.870 with and without Headroom.

Headroom's README has an accuracy table: on 100 GSM8K maths questions the score is 0.870 without it and 0.870 with it; TruthfulQA goes from 0.530 to 0.560, which they say is inside the margin of error, so no real difference. The original text that gets compressed away is kept on your machine, and the model can call headroom_retrieve to get the full version when it needs it.

Reel frame: Claw'd on the Headroom press, grey cubes in on the left, a shorter green stack out on the right
Same answers, fewer tokens going in.

06Good to know

  1. It doesn't always save: short output, prose and code mostly pass through; repetitive logs and JSON save the most.
  2. It sends anonymous stats by default (compression ratios, model names, OS; never your prompts or code); set the environment variable HEADROOM_TELEMETRY=off to stop that.
  3. While Claude Code goes through Headroom, Remote Control is not available; start claude directly when you need it.
  4. headroom wrap claude installs Serena for the project; add --code-memory none to skip it. To undo, run headroom unwrap claude.
  5. The README mentions a paid Headroom Enterprise for teams; for personal use the open-source version is enough, and the source is on GitHub.
  6. You found this guide by typing SAVE on the site from the link in bio; nothing is sent by DM.

Sources

Related guides