~/guides/SAVE.md
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

When you are done, you get this:
- 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.
- Repeated content is squeezed out; important lines such as errors are kept.
- One command shows how many tokens you saved.
- Reading less means the same usage limit lasts longer.
02Step 1: install Headroom

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:
pip install "headroom-ai[all]"
uv tool install --python 3.13 "headroom-ai[all]"
Then run a health check once:
headroom doctor
03Step 2: start Claude Code with headroom wrap claude

From now on, start Claude Code with this line:
headroom wrap claude
That command does three things:
- Starts a local proxy on your machine.
- Installs Serena (an MCP tool for navigating code) for this project only.
- Launches Claude Code through that proxy. Then just type as usual; what gets sent goes through Headroom first.

To skip Serena, or to wire it up by hand:
headroom wrap claude --code-memory none
headroom proxy --port 8787 ANTHROPIC_BASE_URL=http://localhost:8787 claude
04Step 3: see what you saved, and use it on the right work

While headroom wrap claude is running, open another terminal to watch the savings live:
headroom dashboard
Headroom helps most when Claude Code has a lot of output to read:
- Long, repetitive logs and build or test output.
- JSON from APIs, database query results, hundreds of search results.
- 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:
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?

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.

06Good to know
- It doesn't always save: short output, prose and code mostly pass through; repetitive logs and JSON save the most.
- 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.
- While Claude Code goes through Headroom, Remote Control is not available; start claude directly when you need it.
- headroom wrap claude installs Serena for the project; add --code-memory none to skip it. To undo, run headroom unwrap claude.
- The README mentions a paid Headroom Enterprise for teams; for personal use the open-source version is enough, and the source is on GitHub.
- You found this guide by typing SAVE on the site from the link in bio; nothing is sent by DM.
Sources
- GitHub: headroomlabs-ai/headroom (README, install, Proof, Accuracy, Telemetry; checked 3 Nov 2026)
- Headroom docs: Quickstart (source on GitHub)
- Headroom docs: Limitations (what is and isn't compressed)
- Headroom docs: Troubleshooting (Remote Control)
- Headroom's benchmark script index_proof_table.py (the one we re-ran)
- Claude Help Center: How do usage and length limits work?
What should the next reel cover?
I test Claude and AI tools every day and turn the useful ones into reels. Follow @vivianlin.tech to catch each new guide.