Markdown version of https://extraheadroom.com/blog/claude-code-tokens-without-quality-loss

Blog · How it works

# How Extra Headroom cuts Claude Code tokens without cutting quality

**Garm Lucassen** · November 1, 2026

A Claude Code session sends the model far more than your prompts: test logs, build output, JSON from MCP servers, search results, file contents. The model reads all of it, and every token it reads is billed and counts against your usage limits. Most of that content has a structure that ordinary code can parse. Extra Headroom moves that parsing from the model server to your machine: a local proxy reads each tool result first, forwards the parts the task needs, and keeps the rest on disk, where the model can fetch it with one tool call. This post covers what gets kept, what is never touched, and how we check that answers stay the same.

## The model is an expensive parser

Run a test suite in Claude Code and the full output goes into the next request: hundreds of passing tests, the two that failed, and a summary line. To find the two failures, the model reads every line, on a GPU cluster, at input-token rates, against the same 5-hour and weekly windows your own prompts use. Because Claude Code re-sends the conversation with each request, those lines come back on every later turn too, as cache reads billed at 10% of the base input rate.

Finding the failures in a test log does not take a language model. A log has levels, stack traces and a summary; a JSON array of 500 records has a schema and a few records that differ from the rest. A program that knows those formats does this work in milliseconds on your CPU, and spends no tokens doing it.

## What runs on your machine

Extra Headroom runs a proxy on localhost between Claude Code and the Anthropic API. For each new tool result, a content router detects the format and hands it to a compressor built for that format. The structured compressors are Rust code; prose goes through Kompress, a small ModernBERT-based model that runs locally.

| Content | Kept | Removed |
| --- | --- | --- |
| Build and test output | Errors, warnings, stack traces (including chained exceptions), summary lines | Repeated progress and passing lines |
| JSON arrays from APIs and MCP servers | Every error item, the first and last items, statistical outliers, items that match the task | Look-alike records, replaced by a count |
| Documentation and other prose | The tokens Kompress scores as carrying meaning | Low-information tokens |
| Text already shown earlier in the session | The first copy | Later verbatim repeats, replaced by a pointer to the first |
| A file read that has gone out of date | The newest read of the file | The old copy, after the file was edited or read again |

On the engine's own benchmark, 500 structured log entries come out 54% smaller, 500 JSON search results 49%, and 20K tokens of documentation 92%; Python source passes through unchanged. A full session mixes those with turns that have little to compress. Across 183 Claude Code users in one week of production traffic, input fell 34% ([results and method](/blog/claude-code-savings-real-usage)).

Because the parsing runs locally, the originals stay on your machine. The app syncs token and request counts, never prompt content.

## What is never compressed

Some content has to reach the model byte for byte, so the proxy leaves it as sent:

| Left verbatim | Why |
| --- | --- |
| Your messages | They are the task. |
| Current file reads, Grep and Glob results | Claude Code's Edit tool matches the model's `old_string` against the exact file text, so a compressed read would break edits. |
| Edit and Write results | They record what changed; altering them leads to duplicate or conflicting edits. |
| WebSearch and WebFetch results | They are reference material the model may quote. |
| Context already in the prompt cache | Only new content is compressed, and earlier turns stay byte-identical from request to request, so cache hits are unaffected. |

Shell output is the main target: build logs, test runs and command output are where most of the repetition is.

## Nothing is thrown away

Each compressed block ends in a marker such as `[N items compressed... hash=abc123]`, and the original goes into a local store. The proxy adds one tool to the request, `headroom_retrieve`, which tells the model to use it "when you need more data than what's shown in compressed tool results." When the model calls it with the hash, the original comes back from your machine.

A compression the model disagrees with therefore costs one extra tool call, not a missing fact. The model works from a shorter view by default and the full text on demand, and that is what keeps quality intact. It also means retrieval has to keep pace with Claude Code, which changes how it runs tools between releases. Older Extra Headroom versions could fail a retrieval on newer Claude Code builds, and the agent would then report data it could not read. The app updates itself in the background, and Settings \> Check for updates installs the latest version right away ([updating](/docs/update)).

## Why less input does not mean worse answers

Removing noise can help rather than hurt. Model accuracy degrades as context grows: Lost in the Middle (Liu et al., 2023) found that models use information in the middle of a long input less reliably than information at its start or end, and Chroma's Context Rot report (2025) measured accuracy falling with input length across 18 models, even on simple tasks. Smaller tool results also delay Claude Code's auto-compact, which replaces the conversation with a summary when the context window fills; unlike a compressed block, a summary cannot be retrieved back.

On the engine's accuracy evals, compressed and uncompressed runs agree: GSM8K math accuracy is 0.870 with and without compression (100 problems); TruthfulQA is 0.560 compressed against a 0.530 baseline (100 questions, inside the margin of error); a 100-entry JSON log with one injected error keeps the error at 38% compression; and HTML extraction scores an F1 of 0.919 on 181 real web pages.

## Output: shorter replies, same work

On the output side, Extra Headroom adds a short instruction to each request: skip preamble and recaps, do not restate code, file contents, diffs or tool output already in the conversation (point to the path and line instead), and do not narrate a tool call that succeeded. It targets the prose around the work; code, edits and tool calls are written as before, and shorter replies finish sooner. Output savings are estimated against a learned baseline of reply lengths, and a small control group of conversations runs without the instruction.

Related: [what Extra Headroom is](/what-is-headroom) and [how the savings are measured](/docs/how-savings-are-measured).