Headroom: Cut Your AI Coding Bill By Up To 92%

Every time your coding agent reads a file, runs a command, or pulls a search result, that whole wall of text gets stuffed back into the model, and you pay for it again on every single message after that. Headroom is a free, open source layer that sits between your coding agent and the model, compressing everything it reads before it costs you a token. Same answers, a fraction of the price.

What You'll Learn

• Free, open source (Apache 2.0): one pip install
• Proxy mode = zero code changes, works with Claude Code, Cursor, Codex, Copilot
• Up to 92% fewer tokens on real coding sessions, zero accuracy regression on benchmarks
• A learn mode that writes fixes straight into your CLAUDE.md so your agent stops repeating mistakes

The Real Problem

On a long Claude Code or Cursor session, bloated, repeated context is the quiet reason your limits drain and your bill climbs. Headroom kills that tax without you changing how you work.

Who built it: Headroom is a free open source project (Apache 2.0) by Tejas Chopra, an engineer at Netflix. As of writing it is past 43,000 stars on GitHub. It is not a Netflix product, it is his open source tool, and you run it locally so your data stays on your machine.

Repo: https://github.com/chopratejas/headroom

Install It (One Line)

One install gets you the library, the proxy, the agent wrappers, and the MCP server. Requires Python 3.10+.

pip install "headroom-ai[all]"

Or for Node / TypeScript:

npm install headroom-ai

Pick Your Mode

Three ways in, depending on how hands off you want to be. For most vibecoders, wrap or proxy is the move, no code changes at all.

1. Wrap your agent. Run headroom wrap claude (or codex, cursor, aider, copilot). It starts the proxy and launches your agent through it in one command.
2. Or run the proxy. Run headroom proxy (set a port with the port flag if you need a specific one, the guide setup uses 8787) and point any OpenAI compatible client at it. Zero code changes, any language.
3. Or use the library. In your own app, call compress(messages) in Python or TypeScript and inline it wherever you build prompts.
4. See the savings. Run headroom perf to see exactly how many tokens you just saved on a real session.

The Receipts

This is not summarization that loses your context. Headroom caches the originals locally and the model can pull them back on demand, so it is reversible. Across their published benchmarks, the answers held.

• SRE incident debugging: 65,694 tokens down to 5,118 (92% fewer)
• Code search, 100 results: 17,765 down to 1,408 (92% fewer)
• GitHub issue triage: 54,174 down to 14,761 (73% fewer)
• Accuracy on GSM8K math: identical, plus or minus 0.000 regression
• Headline range is 60 to 95% depending on the workload, so treat 92% as a ceiling, not a guarantee

The Part Most People Miss

Two extras turn this from a cost trick into a real workflow upgrade.

First, the output shaper. It can trim what the model writes BACK, not just what you send, by steering it to be terse on routine steps. Turn it on with the env var:

export HEADROOM_OUTPUT_SHAPER=1

Second, learn mode. It mines your failed sessions, finds where your agent keeps going wrong, and writes the corrections straight into your CLAUDE.md or AGENTS.md, so the same mistake stops happening twice. Run headroom learn with the verbosity and apply flags enabled to learn the right terseness for you and apply it.

When To Skip It

Headroom shines if you run AI coding agents daily and want savings with no code changes, or work across multiple agents and want shared memory. Skip it if you only use one provider's native compaction and do not need cross agent memory, or you are in a sandbox where local processes cannot run.

Go Deeper

Prefer a printable version? Grab the PDF: https://drive.google.com/file/d/1BeK_D7cCLBc0rJ9c04_A6KT6KBsYWwtg/view?usp=drivesdk

Want the whole system installed live, with Cooper on the call? Build Your Own AI, the two week sprint runs the first two weeks of August.

Or get a new working tool every Monday inside The AI Operator community on Whop.