Cut Your Claude Token Bill With Headroom

If you run Claude Code for anything serious — multi-file projects, long research sessions, full agent loops — you have probably watched your token counter climb faster than expected. Context gets long. Every message carries the full conversation history. By the time you are three hours deep, you are paying for tokens on context you already processed an hour ago. Headroom fixes this at the layer where it counts: before the tokens reach the model.

Headroom is a free, open-source (Apache 2.0) middleware layer that sits between your AI coding agent and the model. It intercepts prompts before they leave your machine and compresses the context — removing redundancy, collapsing repeated phrasing, summarizing stable background that has not changed. It caches the originals locally so nothing is lost. On typical sessions, this produces 60–92% fewer input tokens with no measurable accuracy drop on coding or reasoning tasks.

Install

# Python
pip install "headroom-ai[all]"

# Node.js
npm install headroom-ai

Three Ways to Use It

• Wrap mode — run `headroom wrap claude` to wrap Claude Code directly. Headroom compresses context on every message. Lowest friction, works immediately, no config file needed.
• Proxy mode — run `headroom proxy --port 8787` to spin up a local proxy. Point any AI client to localhost:8787 and Headroom handles compression upstream before requests leave your network.
• Library mode — call `compress()` from the headroom Python or Node package inside your own scripts. Use this when you want compression in a custom agent build or pipeline.

Check Your Savings

headroom perf

This command prints a breakdown of tokens sent versus tokens that would have been sent without compression. Run it after your first real session. Most people are surprised how much redundant context they have been paying for — especially on projects where the same files appear in context repeatedly.

Learn Mode: Self-Improving Compression

Headroom's learn mode watches your sessions and writes project-specific compression rules into your CLAUDE.md file. It learns what to compress and what to preserve verbatim. On a codebase you return to regularly, compression efficiency improves over time without you adjusting anything.

What Gets Compressed

• Repeated file contents — if the same file appeared three messages ago and has not changed, Headroom replaces it with a compact hash reference instead of re-sending the full content
• Stable system context — role definitions, tool descriptions, and background instructions that repeat unchanged on every message
• Conversation history — long prior exchanges get summarized rather than included verbatim
• Boilerplate code — import blocks, lock files, and structural scaffolding the model already processed earlier in the session

Headroom is reversible. Every compressed message has a local cache of the original. If you need to debug what was actually sent to the model, you can inspect the uncompressed version. Nothing is permanently discarded.

When It Makes the Biggest Difference

• Long Claude Code sessions on a large codebase — context accumulates fast and the same files appear repeatedly
• Agent loops with many iterations — each loop iteration re-sends the full history
• Any project where you return to the same files repeatedly across a session
• Teams where AI usage is billed by token volume and the spend is visible on a dashboard

For a solo developer running a few hours of Claude Code per day, Headroom can drop a $100/month token bill to $20–$40 depending on session patterns. For production agent pipelines running continuously, the math is more significant. The install is two minutes. Run `headroom perf` after your next session and see the number before deciding whether to keep it.