token-optimizer

Compression that optimises your bill, not your byte count — and ships the benchmark so you can check it.

How it compares to Alternative A

Providers cache the prompt prefix: cached tokens re-read at 0.1x, rewritten ones bill at 1.25x. Most compressors optimise bytes removed and ignore that multiplier. This one optimises the bill.

Measured against their real implementation, on their own fixtures. Not a reimplementation and not our fixtures: their harness compresses the payload, dumps it, their resolver redeems their own markers, and ours is handed the identical bytes. Their column is the best of the nine configurations that capture holds, row by row.

Two of our arms are in the table, and they answer different questions. ours is the block engine with nowhere to move a block, which is how the MCP tools and the hooks run: everything it removes, it removes by compressing, and nothing leaves the request. ours, proxy is the proxy a Claude Code session runs through, which also moves a block it could not compress out to a file and leaves a marker naming the path -- the same kind of trade their content-cache reference makes. ours, preset is the block engine with that move switched on at spillWholeBlockBelow: 0.9.

Recorded 2026-10-17 at b1231a8c, by the command in the record's regenerate field, over Alternative A's own fixtures and harness. That arm runs Alternative A itself, so CI does not re-derive it -- it checks these figures and this provenance against the record instead.

Over the corpus the proxy removes 82.5% of the characters and 91.5% of the tokens; their best configuration removes 51.5% and 61.4%. It is cheaper than their best arm on 18 of 18 rows when nothing is ever fetched back, which is the end of the range their markers are built for, and on 17 of 18 when every moved block is fetched back. The block engine alone removes 72.0% and 55.9%: more of the characters than theirs, fewer of the tokens.

Where they still win, and why. On codebase-exploration, grep-output, raw-build-log, sre-debugging and the four raw-data rows their best arm takes 83.2-99.8% off the tokens and the block engine 12.7-62.4%. Their number there is a content-cache reference: the block is not made smaller, it is taken out of the request, put in a store, and replaced by a <<ccr:hash,kind,size>> marker. An engine with nowhere to put a block cannot match that, so on those rows the ours column loses on reduction, and on cost when nothing is fetched back. The proxy makes the same move: it is ahead of them on five of those eight rows, level on grep-output and raw-build-log, and a tenth of a point behind on codebase-exploration. The one row where the proxy costs more than they do is agentic-conversation, and only when every block it moved is fetched back: they move none of that conversation out, so they cost the same at either end, while the proxy moves part of it and pays a retrieval for each part it wants back.

The other column is a turn. A marker is not the content: to read what it stands for, the agent spends a request. Of the 13,792 retention units planted in the corpus, the block engine keeps 5,223 in the text and 8,569 more rebuildable from the text alone, so every one of them is there with no extra turn; theirs keeps 6,711 in the text and 7,075 behind its store, one retrieval call away. 0 are unrecoverable on our side and 6 on theirs. Their best arms force 17 round trips across the corpus to get their content back; the block engine forces 0. The proxy, like theirs, trades a turn for every block it moves, and that turn is what the fetch-rate end of the cost model prices.

What their marker costs is priced, not just its size. Their marker is only redeemable because their proxy also sends a alternative_a_retrieve tool with the request -- on by default (ccr_inject_tool), and on every later request once a session has used it -- so every row where their best arm leaves a marker is charged for that tool's definition as well, recorded from their own package by bench/compression/alt-a/ccr-tool.py. The turn that first adds the tool also rewrites the whole cached prefix behind it; that is not charged, which errs in their favour. Ours needs no tool: our marker names a path the agent opens with the Read it already has, and the path is priced at the length the proxy really writes (<home>/.tok/<pid>/<15 digits>, src/compress/spill-path.ts) rather than a shorter invented one.

browser-session is mostly the fixture. This payload holds four images, two of them distinct, and the base64 in them is generated rather than photographic: one distinct image alone folds from 160,032 characters to 5,572, which no real PNG would do. What carries over to a real session is the duplication -- half the image bytes are a second copy of an image already in the request, which is 44.3% of the whole payload. The run the marker names is still in the output above it, so the reader rebuilds it without asking for anything, which is why the characters fall much further than the tokens: the image tokens are counted from pixels on both arms either way.

Reproduce the whole table:

python bench/compression/alt-a/run-theirs.py <alt-a-clone> <out-dir>

python bench/compression/alt-a/resolve-theirs.py <alt-a-clone> <out-dir>
node bench/compression/head-to-head.mjs <out-dir>

Against their published design

A second arm reimplements their published design from their own benchmark generator's definitions — opaque hash markers, history compressed, a retrieval tool and system message injected — so the four workloads with a published comparator can be checked without their clone. node bench/compression/proof.mjs:

Four workloads, because those are the four this arm has a published comparator for. The head-to-head harness scores eighteen; the other fourteen are not in this arm, and are scored against their real implementation in the table above.