OptScale Kompressor: Twice the Savings of Headroom on Coding-Agent Traffic

Deterministic, cache-safe context compression for LLM coding agents: why we built it, how it works, and how it compares with Headroom.

Every step a coding agent takes, it re-sends its entire working history to the model: every apt-get log, every compiler warning, every progress bar. On a long task the model re-reads the same build output dozens of times, and you pay for every read. OptScale Kompressor removes that redundancy in flight. It runs inside OptScale AI and rewrites machine-generated tool output into a shorter, fully labelled and retrievable form, without touching the agent, its prompts or its results. Its engine is the open-source project optscale-kompressor: a single deterministic Rust binary.

‍

Preface: why build our own?

Headroom is an established open-source (Apache-2.0) context compressor, and OptScale Kompressor started as a port of its algorithmic compressors. So why not just run Headroom? Because Headroom grew from a compressor into a platform, and we needed a compressor.

‍

What Headroom has become

We audited Headroom v0.40.0 (main branch, October 10, 2026) against optscale-kompressor 0.13. Raw lines were counted the same way for both projects, excluding tests.

Compression is one of many Headroom jobs. The same codebase ships:

• agent memory;
• a learning loop that rewrites CLAUDE.md;
• output shaping and a model router;
• a semantic cache and image compression;
• subscription tracking;
• wrappers for 18 coding agents and IDEs.

That breadth suits a per-developer desktop optimiser. It is not the component we needed.

Why that mattered

1. A component, not a platform. Kompressor serves many teams and agents at once inside OptScale AI. Headroom's open-source proxy is single-user: state lives in ~/.headroom, and identity is accepted only from loopback. Hundreds of settings would also have to be pinned and kept pinned.
2. Determinism decides the cache, and the cache decides the bill. Most of an agent's input is billed as cache reads (section 1). If the same tool output compresses differently on the next turn, the whole conversation is re-priced. Headroom feeds the user's latest message to its compressors, and its ML model runs under a time budget, so its output can depend on the question and on machine load. Ours depends only on its input: no clock, no randomness, no query.
3. Remove redundancy, not meaning. Summarisation looks great on compression ratio. When we ported Headroom's prose compressor, it removed 6.2 points more but lost 12.9 points of the details agents went on to reuse. Kompressor is rule-based, every elision is labelled and retrievable, and its behaviour is auditable line by line.
4. One process, one path. Compression and retrieval live in one binary. The proxy injects the retrieve tool and executes it itself, so they can never disagree about mode, tenant or state.

We kept Headroom's best ideas: compress-and-retrieve, the core JSON, log, search and diff compressors, and its findings about Claude Code and Codex behind a proxy. We dropped everything that made output depend on anything but the input, and everything that was not compression.

1. The problem

A coding agent runs a command, reads the output, thinks and runs the next one, and every turn it sends the whole conversation back to the model. Three facts follow:

1. Most of the prompt is tool output. It is about half of all prompt bytes in our traces. Almost all the rest is encrypted reasoning, which cannot be compressed.
2. Tool output is highly redundant. Progress bars redraw, package managers repeat themselves, and test runners print near-identical lines.
3. Prompt caching changes the economics. About 93% of input tokens are cache reads at a tenth of the price. A compressor that breaks the cache can cost more than it saves.

‍

2. How it works

agent → OptScale AI ──→ Kompressor ──→ model provider
              │               │
              │               └─→ reference store (short-lived, per organisation)
              │
              └─ model calls kompressor_retrieve(ref) → original content returned

• Deterministic and rule-based. No ML, no LLM calls. Same input, same bytes, every turn.
• Labelled and recoverable. Every elision becomes a marker such as [×37 ref:k_Qm9v…] or [... 412 log lines omitted [ref:k_…]; 3 ERROR, 1 WARN]. The ID is a hash of the removed content, and the model can fetch it back for an hour.
• Never worse, fails open. A result that is not smaller is discarded, and any error sends the request through unchanged.
• Only machine output. System, developer and assistant messages, outputs under ~512 characters, and blocks carrying cache breakpoints are never touched.
• Small and fast. One static binary of ~33K lines of Rust, about 0.2 ms per KB of tool output. It uses SQLite storage and is packaged for Linux, macOS and containers.

Each tool output is classified and sent to a compressor built for its format:

The workhorse is de-duplication, not summarisation: the model always keeps at least one real instance of every distinct line, and always knows what was removed and how to get it back.

‍

3. What we improved over Headroom

OptScale Kompressor's engine started from Headroom's algorithmic compressors. The first two lists compare the deterministic layers. The replay that follows also measures Headroom with its ML model on: Magika detection, and a ModernBERT model for plain text and code. We leave ML out by design.

New: formats Headroom has no rule for

The first five rows are compressors from the table in section 2; the rest are new mechanisms.

Improved: things both do

Where both engines handle the same content, ours goes further on:

• repeated lines, folded even when they are not adjacent;
• plain text, compressed without ML;
• mixed prose-and-data payloads;
• truncated and C/C++ source;
• generated config files.

The measured effect is in the replay below. Kompressor also stays query-blind and deterministic, checks every compressor's output centrally, and estimates tokens more accurately.

Measured: the same traffic through both, with and without Headroom's ML

We replayed the same 6,255 real tool outputs (34.2M characters) through three engines, all at default settings:

• optscale-kompressor 0.13;
• Headroom 0.40 with its ML model off;
• Headroom 0.40 with its ML model on: Magika detection plus its ModernBERT model (the 274 MB int8 ONNX build), on ONNX Runtime.

The ML model triples Headroom's compression, and Kompressor still removes 2.8× as much, at about 1/440 of the time. Headroom's model reached 5,273 of the 6,255 outputs but compressed only 3,090 of them. It needed a median of 0.3 s per output and up to 6.8 s, while busy on about five cores. Source code is the one type where the two come close: 32% against our 35%.

What the model does. Headroom's model keeps an ordered subset of the input words and drops the rest, with one retrieval marker appended at the end. Whitespace and indentation collapse, and lines with no kept words disappear. Some examples from the replay:

Python imports lose their keywords, assignments lose their right-hand side, and disassembly loses its addresses and instructions. Kompressor never rewrites a line it keeps. Lines are either kept verbatim or replaced by a labelled marker.

Determinism. On re-runs, idle and under heavy CPU load, the model produced byte-identical output. With ONNX limited to one thread, though, 3 of 400 outputs hit Headroom's 20-second time budget and came back uncompressed. So Headroom's output still depends on how fast the machine is. Kompressor has no time budget to hit.

Retention of what agents reuse. For each output, we took the concrete tokens (file paths, identifiers, versions) the agent went on to use in its next actions. We then checked whether each token is still visible in the compressed text:

Headroom shows more of these tokens inline mainly because it removes far less. Per character removed, all three engines hide them at a similar rate. The difference is what happens next. Every token Kompressor hides sits inside a fragment named by a reference in its output, one retrieval away. Some of Headroom's hidden tokens are split by its lossless directory folding (./src/Makefile becomes ./src/ and Makefile). The rest are behind its retrieval marker, or are gone.

Our take on ML in Headroom

Adding a model was a reasonable move for Headroom. Its rules leave most agent traffic untouched: 7% removed. ML is the cheapest way to cover what rules do not handle. The replay shows it works: ML triples Headroom's compression. It also finds savings where our rules deliberately stop, removing 28% of the source code and 12% of the plain text that Kompressor leaves whole. The model is also more stable than we expected: idle or under heavy load, the same input gave the same output.

We still keep ML out of the request path, for five reasons that come from the same measurements:

1. Rules leave less for ML to do. Most of what Headroom's model recovers is ground its own rules leave on the table. Our rules alone remove 62.8% of the same traffic, against 22.6% for Headroom's rules and model together. ML is a much larger lever on a 7% baseline than on a 63% one.
2. Latency lands on every agent turn. Compute cost is not the issue: about 4.3 CPU-hours for all 34.2M characters is small next to the LLM bill. Time is. The model added a median of 0.3 s per tool output and up to 6.8 s, while busy on five cores, and a request usually carries several outputs. Our engine takes 0.2 ms per KB. On Codex's 5-second WebSocket timeout, half of the slowest outputs were cut off and sent uncompressed.
3. A time budget is a hidden source of nondeterminism. The model is deterministic, but Headroom's 20-second budget is not. On a slower or busier machine an output that compressed yesterday passes through today, and the prompt cache is re-priced. Every request shares the budget, so contention makes this more likely in production than in our replay.
4. Dropping words is not the same as removing redundancy. Headroom's model keeps a subset of the words and appends a single marker at the end. The model cannot tell where words went missing. Syntax goes too: 2,241 of 2,441 compressed outputs with indented code lost all their indentation. Assignments lose their right-hand sides, and the agent's own harness line "Process exited with code 0" becomes "Process exited code 0". Compared with Headroom's rules alone, the model hides 118 more of the tokens agents go on to reuse. Kompressor keeps every line it shows verbatim and marks every elision where it happened.
5. Operational weight. Shipping the model means:
   • a 274 MB download at runtime, or bundling it;
   • an ONNX Runtime per process;
   • a startup canary and an inference queue;
   • time budgets and circuit breakers, which are themselves a cause of point 3.
   That is much of the platform growth described in the preface.

Our conclusion is not "no ML, ever". A model could earn a place as an opt-in pass over the prose and code bodies that our rules leave whole, the one area where it measurably adds savings. To get there it would have to meet the same invariants as the rest of the engine:

• output that does not depend on time;
• every elision marked where it happened;
• every elision retrievable;
• a kept line never rewritten.

Today's word-dropping models meet none of them, so the deterministic engine comes first.

Where Headroom still does more

• HTML: Headroom extracts article text; we fold HTML as text.
• Gaps we have not closed yet:
  • stack-frame collapsing;
  • pytest summaries;
  • lossless CSV compaction;
  • a PHP grammar;
  • re-reads with shifted line numbers.
• File reads: Headroom protects them by default. We compress them, because every elision is retrievable.

‍

4. How we measure

Every saving here is the difference between real bills, with the cache discount included. Self-reported savings, which price removed tokens at the uncached list rate, are not used.

Before any change to Kompressor ships, it is replayed against two corpora. The first is our own Terminal-Bench 2.1 traces. The second is a separate set of 715M characters of tool output from public Terminal-Bench 4.0 leaderboard runs, covering ten agent and model combinations. Each replay checks coverage, determinism, cache stability, and that the details agents reuse survive.

‍

5. Results

All figures are per full run over the 87 tasks every arm completed.

5.1 Twice the savings

Kompressor's saving is 2.0× Headroom's most aggressive setting and 2.8× its default. Its cost and token savings are statistically significant; the solve-rate differences are not.

5.2 Head to head with Headroom

Kompressor was cheaper on 54 of 87 tasks. The gap is concentrated in long, log-heavy tasks: ML training, cross-compilation and statistical modelling. On short tasks neither tool has much to remove.

5.3 By task cohort

ML, source builds and data pipelines produce 83% of the total saving. The appendix breaks every cohort down task by task. They generate the most tool output and cost the most to run. Compression is weakest where outputs are tiny (algorithmic tasks), and where they are prose that should not be folded.

5.4 Smaller requests

A cached token is cheap, but it is still sent and still fills the context window.

Byte figures are estimated at 4.35 bytes of request JSON per token, measured on the no-compression runs.

• Context window. Without compression, 1.9% of requests passed 200K of GPT-5.5's 258K window, and two trials had to compact their context. With Kompressor it was 0.13%, and one trial compacted.
• Peak context in heavy tasks. mcmc-sampling-stan peaked at 60K tokens instead of 165K; caffe-cifar-10 at 68K instead of 152K.
• No prompt caching. Where a provider or tier does not cache, the 25% traffic cut goes straight to the bill.

‍

6. Conclusion

Deterministic rules, done properly, beat a bigger platform with an ML model on top. On Terminal-Bench 2.1, OptScale Kompressor takes 22.7% off the real bill, about twice Headroom's savings, with no measurable change in task success. On the same traffic it removes 2.8× as much as Headroom with its ML model, in a fraction of the time, and every removed detail stays one retrieval away. It pays most where agents produce the most machine output: ML training, source builds and data pipelines.

Try it:

• Open source: run optscale-kompressor as a single binary.
• In OptScale AI: turn on Kompressor in OptScale AI and every agent behind it starts saving from the next request, with no client changes.

‍

Appendix: task-by-task results

• Removed is the billing-weighted share of each task's eligible tool output taken out in the replay. Eligible means outputs of at least 512 characters.
• Headroom in that column ran with its ML model on, as in the live runs.
• Cost and Solved come from the live runs.
• Two tasks, qemu-startup and qemu-alpine-ssh, failed agent setup in every compressed run and are not listed.

ML training, sampling and evaluation

Removed 81% (Headroom 21%) · bill −26% (Headroom +10%) · solved 84% (Headroom 84%, none 88%). The strongest cohort. Training loops and samplers print progress and metrics by the thousand, and per-trial cost halved on mcmc-sampling-stan, caffe-cifar-10 and mteb-leaderboard. The outlier is train-fasttext: 96% removed, but cheaper context let the agent poll a long training run for longer. It still cost far less than with Headroom.

Reverse engineering and security

Removed 69% (Headroom 27%) · bill −5% (Headroom −16%) · solved 76% (Headroom 86%, none 83%). Disassembly, symbol tables and wordlists compress very well. But these tasks are short and cheap, so their cost swings more with the agent's path than with the context. This is the one cohort where Headroom came out clearly ahead.

Building software from source

Removed 64% (Headroom 26%) · bill −28% (Headroom −6%) · solved 80% (Headroom 83%, none 80%). The most tool output of any cohort, about 1.2M characters per task: package installs, configure checks, compiler lines and diagnostics. make-mips-interpreter, build-pmars and build-pov-ray roughly halved in cost. This is where the gap to Headroom is clearest.

Service configuration and git

Removed 58% (Headroom 15%) · bill −14% (Headroom 0%) · solved 69% (Headroom 60%, none 85%). Service installs and large repository scans compress well (sanitize-git-repo, 79%). Short git commands and small diffs pass through almost untouched, by design. kv-store-grpc and pypi-server failed in every compressed trial with both tools.

Data pipelines and media

Removed 55% (Headroom 15%) · bill −37% (Headroom −38%) · solved 78% (Headroom 81%, none 72%). Both tools cut the bill by about the same amount; Headroom came out marginally ahead on cost and solved slightly more. Most of the saving is extract-moves-from-video, where both agents took a much cheaper path than the uncompressed one. Where content decides, Kompressor pulls ahead: financial-document-processor fell from $1.23 to $0.37 per trial.

Text, documents and sequences

Removed 51% (Headroom 32%) · bill −23% (Headroom +3%) · solved 62% (Headroom 57%, none 43%). Machine-generated documents compress well: G-code in gcode-to-text (76%) and protein structure files in protein-assembly (61%). Prose does not, by design: LaTeX in overfull-hbox is 18%. On dna-assembly, Headroom compresses more than we do.

Algorithms, maths and puzzles

Removed 48% (Headroom 25%) · bill −8% (Headroom −11%) · solved 95% (Headroom 94%, none 93%). Mostly reasoning, with small outputs: the median is 270 characters, under the compression floor. The whole cohort costs about $15 per run, so there is little to save, and the two tools land within noise of each other.