Every time you send a message in Claude Code, the tool doesn't just ship your new line — it re-uploads the entire conversation so far. On a long session, that quietly becomes the bulk of your token bill.
Why Claude Code Resends the Entire Conversation on Every Turn
Claude Code is stateless between API calls, so it appends the full message history, all tool outputs, and MCP server metadata to every outbound request. Anthropic's own cost documentation confirms token spend scales with accumulated context: the longer the session, the more you pay to resend material the model has already seen . Prompt caching softens this — Anthropic gives roughly a 90% read discount on a stable prefix — but tool results, file reads, and variable JSON payloads keep changing the prefix, breaking the cache and forcing stale output to be re-billed at full input rates on later turns .
Headroom is a local middleware layer that intercepts that outbound payload before it reaches the provider. Requests pass through a staged lifecycle — Input Received → ContentRouter → Compressed → Pre-Send — where redundant blocks like logs, search dumps, and repeated file reads are stripped or compressed en route . The current headroom-ai package is version 0.33.0, published July 29, 2026 .
The payoff varies by content. Headroom's README cites 15–20% overall reduction for coding agents, while structured payloads — JSON arrays and build logs — reach 70–95% . Independent expectations should be tempered: one practitioner reported about 26% real-world savings after a month of use .
What Headroom Needs to Attach to Claude Code
Headroom attaches to Claude Code with two runtime prerequisites and no API key changes. Pick one install path: Python 3.10+ for pip install "headroom-ai[all]", or Node 18+ for npm install headroom-ai . The current PyPI package is headroom-ai version 0.33.0, released July 29, 2026, so a fresh install already carries the compressor stack described in the arc .
There is no build step. Prebuilt wheels ship for Windows, Linux (x86-64 and aarch64), and macOS (x86-64 and ARM64), so the install resolves without a compiler toolchain on any of those platforms .
Your Anthropic credentials stay untouched. Headroom runs on localhost and you redirect Claude Code at 127.0.0.1 instead of api.anthropic.com; the key still authenticates upstream, only the base URL moves .
Verify before wiring anything: headroom --version should print 0.33.0 . After you attach it in the next step, one live Claude Code invocation confirms the round-trip end to end.
Fitting Headroom Into Claude Code
You have three ways to route Claude Code through Headroom, ordered from least to most manual. Pick one based on how much control you want over what gets compressed.
Path A — agent wrap (zero code changes). Run headroom wrap claude. Headroom launches Claude Code as a subprocess and compresses every payload in-process before it leaves your machine; nothing else in your setup changes . This is the fastest path if you just want savings without thinking about which blocks matter.
Path B — transparent local proxy. Start headroom proxy --port 8787, then set ANTHROPIC_BASE_URL=http://localhost:8787 before invoking claude. All traffic routes through Headroom without touching source or config files, and the request continues upstream to Anthropic authenticated by your existing key .
Path C — MCP server. Run headroom mcp install to expose headroom_compress, headroom_retrieve, and headroom_stats as callable tools. Instead of compressing all traffic, Claude compresses specific blocks on demand and can pull the original back within a one-hour TTL . This gives you per-block control at the cost of Claude choosing when to invoke it.
What makes the compression safe is CCR — Compress-Cache-Retrieve. Headroom stores the original content locally under a content hash and hands the model a shorter representation plus a retrieval affordance. The documented example crushes 5,000 lines of grep output from 12,000 to 3,200 tokens — a 73.3% cut — with the full original on standby via headroom_retrieve for one hour .
Under any path, ContentRouter auto-detects each block's type — JSON, logs, diffs, HTML, plain text — and hands it to the right compressor: SmartCrusher for JSON, an AST-aware CodeCompressor for source (Python, JS/TS, Go, Rust, Java, C/C++), and Kompress-v2-base, a 149M-parameter extractive prose model, for narrative text . You do not tag content yourself; routing is automatic.
When Headroom Skips Compression Entirely
Headroom does not compress everything, and knowing what it leaves alone sets a realistic expectation. Messages under roughly 300 tokens pass through untouched, because compressor overhead exceeds any saving at that scale . Source-code compression is opt-in and off by default, and short conversational exchanges compress a median of just 4.8% . Images, grep/search results, and system prompts may also bypass the pipeline.
The gains concentrate in long, tool-heavy sessions. Agentic conversations of 25–50 turns compress 56–81%, while a single-turn or early-session call can see near-zero reduction . The headline 60–95% figures apply exclusively to structured payloads — JSON arrays and build/test logs — not prose-heavy turns; the README's own coding-agent figure is 15–20% .
| Workload | Typical reduction |
|---|---|
| Short conversational exchange | ~4.8% (median) |
| 25–50 turn agentic session | 56–81% |
| JSON arrays | 70–90% |
| Build/test logs | 80–95% |
| Source code (opt-in) | 40–70% |
Independent signal is thin. One practitioner reported roughly 26% real-world savings after a month — well below the marketed range. Every published number originates from Headroom's own suite, including the v0.5.18 reproducible benchmarks that measured 66.1% total-corpus compression ; as of August 2026 no independent, peer-reviewed benchmark exists. Treat vendor figures as an upper bound and measure your own workload with headroom_stats before assuming plan-doubling savings.
What to Explore After Initial Attachment
Once compression is running cleanly, four features extend what Headroom does for a Claude Code workflow. The most useful is headroom learn: an offline failure-mining pass that reads your past Claude Code transcripts, mines recurring errors and patterns, and writes the distilled findings directly to CLAUDE.md Headroom README. It runs on stored sessions, not live traffic, so it costs no extra tokens during a conversation.
If you run Claude and Codex in parallel, Headroom keeps a shared compressed corpus across both agents and deduplicates overlapping context, so the same file reads and tool outputs are not stored or re-sent twice Headroom README. That matters most when two agents are exploring the same repository at once.
To measure any of this without leaving a conversation, call the headroom_stats MCP tool for per-turn compression ratio and cumulative token delta Claude plugin manifest. Finally, tune CacheAligner — the component that flags volatile content breaking KV-cache prefixes. Configuring it to hold more prefix stable earns Anthropic's roughly 90% cache-read discount on top of compression, stacking both savings.
Concrete next step: attach via the proxy, turn on headroom_stats, run one real session, then decide whether headroom learn and CacheAligner tuning justify the setup for your codebase.
Frequently asked questions
Does Headroom change Claude's answers or discard information?
No — Headroom is designed to be reversible rather than lossy. Its CCR (Compress-Cache-Retrieve) design stores the original content locally under a hash and hands the model a compact representation plus a retrieval affordance, so Claude can call headroom_retrieve to fetch the full original within a one-hour TTL when detail is needed . The prose compressor, Kompress-v2-base, is extractive and scores eval F1 0.918 with must-keep recall 0.974 on 7,037 held-out examples, meaning very few forced-retain spans are dropped .
How much will Headroom actually save in a real Claude Code session?
It depends heavily on workload. The README claims a modest 15–20% reduction for coding agents broadly, but structured payloads see far more: JSON arrays 70–90% and build/test logs 80–95% in Headroom's own benchmarks . Short conversational exchanges compress a median 4.8%, while agentic sessions of 25–50 turns compress 56–81% . One practitioner reported roughly 26% real-world savings after a month . Meaningful gains appear once a session accumulates significant tool-output history.
Is running Headroom's local proxy safe with my Anthropic API key?
Yes, for on-machine use. The proxy binds to 127.0.0.1 only, so traffic from Claude Code to Headroom never leaves your machine; Headroom then forwards requests to Anthropic's API . The repository is Apache 2.0 licensed and fully inspectable on GitHub, and Headroom itself stores no credentials .
What is the difference between proxy mode, wrap mode, and MCP mode?
Proxy mode (headroom proxy plus an ANTHROPIC_BASE_URL override) intercepts all traffic transparently — no code changes and it works with any tool. Wrap mode (headroom wrap claude) shells Claude Code as a subprocess with Headroom in front, the simplest path for CLI use. MCP mode (headroom mcp install) gives Claude selective, on-demand compression through a tool call instead of intercepting every request; the docs cite a representative 12,000 → 3,200 token result on grep output, with the original retained locally for one hour .
Does Headroom work with editors other than Claude Code?
Yes. Documented integrations include Cursor, Aider, Cline, Continue, and Goose via proxy or wrap mode, and any HTTP client that respects ANTHROPIC_BASE_URL works with proxy mode . On the library side, Headroom documents Vercel AI SDK middleware and LangChain, Agno, and Strands integrations through its compress(messages) API .
Top comments (0)