Cut Claude Code token spend with Headroom: a 5 step setup

Claude Code gets expensive for a boring reason: most of what it reads is noise. Test logs, JSON tool output, long diffs and old conversation turns all go back to the model on every step, and you pay for each token again.

Headroom is an open source tool that sits between your agent and the model and compresses that material before it is sent. According to its README, a log that costs 10,144 tokens can shrink to 1,260 while the same fatal error is still found. Compression runs on your machine, and the originals are cached locally so the model can ask for the full text when it needs it.

This is a practical walkthrough for Claude Code. Our longer write-up of the same setup is on the Deduped use-case page.

What it actually does

Headroom routes each piece of content to a compressor that fits it: one for JSON, one that understands code structure, and a text model for prose. It also flags content that would break your provider's prompt cache, but it never rewrites your prompts. The part that makes it safe is retrieval: compressed output is reversible, and the model gets a headroom_retrieve tool to pull back the original.

You can use it three ways: as a Python or TypeScript library, as a local proxy with zero code changes, or by wrapping an agent with one command. For Claude Code, wrapping is the easy path.

Step 1: install

The README gives these options:

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

The npm package (npm install headroom-ai) is the TypeScript SDK only and does not include the CLI, so use uv or pip if you want the command line.

Step 2: wrap Claude Code

headroom wrap claude

This starts a local proxy, installs the Serena MCP server for semantic code navigation (registered for the wrapped project only), and launches Claude Code configured to route through Headroom. Launch your agent this way each session so the setup runs. If you decide you do not like it:

headroom unwrap claude

The same wrap command works for Codex, Cursor, Aider, Cline, Goose, OpenHands and several others, so you can try it on whatever you already use.

Step 3: check that it works

headroom doctor      # health check, confirms routing works
headroom perf        # compression stats
headroom dashboard   # live savings (the proxy must be running)

Run headroom doctor first. If routing is not working, you will find out there instead of wondering why your bill did not move.

Step 4: run it as a proxy if you prefer

If you would rather not wrap anything, start a proxy and point your tools at it:

headroom proxy --port 8787

Any language that can set a base URL for the API can use it. This is also the route for your own scripts, where you would otherwise call the model directly.

Step 5: let it learn from failed sessions

One of the more interesting commands is headroom learn. It mines sessions that went wrong and writes corrections to CLAUDE.local.md by default (gitignored), or to CLAUDE.md or AGENTS.md if you choose. Check what it proposes before committing any of it to a shared file.

Caveats

• Savings depend on your workload. Tool-output-heavy sessions (test runs, build logs, large JSON) compress well. A session of short prompts will not move much.
• The README's 10,144 to 1,260 figure is its own example, not a benchmark of your repo. Measure with headroom perf on your real sessions.
• It adds a local proxy to your setup. That is one more moving part when something breaks, so keep headroom unwrap in mind.

Who this is for

If you run long Claude Code sessions on a large repo, hit usage limits, or pay per token, a 15 minute trial is cheap. If you mostly ask short questions, skip it.

For more tools in this vein, see the Deduped page for Headroom and the full repo at github.com/headroomlabs-ai/headroom.

---

Get one email every Monday with the week's hottest AI repos and exactly how to use them: subscribe free at dedupedai.com