Part of the reduce Claude Code token usage pillar. This page is the head-to-head: two tools that sit at opposite ends of the effort scale and land in a surprising order.

Is headroom or caveman the better token optimizer?

Neither one saves you money — but caveman placed fourth of twelve on the benchmark and headroom placed last, and the reason is worth more than the ranking. On the open token optimizer benchmark I run, caveman came out statistically indistinguishable from running no tool at all. headroom came out 53% more expensive than running nothing: the only tool in the campaign that measurement could show is worse than doing nothing. So the honest summary is that a joke tied with the null hypothesis while a serious engineering effort lost to it. I should be upfront: I maintain that benchmark and I sell a competing tool. Which is exactly why the interesting part here isn't the scoreboard. It's the mechanism — once you see why each one lands where it does, you can check the reasoning against your own sessions instead of taking my word for it.

What does caveman actually do?

caveman is a JavaScript skill that makes the model answer in telegraphic "caveman talk", plus middleware that compresses tool descriptions. It drops articles, filler and connective tissue from the model's output register, and trims the schemas and descriptions the agent ships with its tool definitions. It supports 30-plus coding agents, installs as a drop-in, and costs nothing to run — no runtime, no model, no proxy. It is, transparently, a bit. The name says so. And it still finished fourth. Its limits are the mirror of its footprint:

It optimises output, and output is not where agentic spend lives. In a coding-agent session, inbound context dominates outbound generation by roughly an order of magnitude. Shortening the model's replies compresses the small side of the ledger.
The tool-description middleware is real but bounded. Tool schemas are paid once per cached prefix, not once per turn. Trimming them helps a little and then stops helping.
It degrades the output register. Some people find the telegraphic style unusable in practice, especially when the agent is writing commit messages, comments or docs that a human reads later.

Fourth place still meant no measurable saving. Coming fourth of twelve tells you something about the field, not about caveman.

What does headroom actually do?

headroom compresses the entire message array before every API call. It's a Python SDK plus CLI proxy plus MCP server, Apache 2.0, with a substantial following. The pipeline aligns cache boundaries, routes each piece of content to a format-specific compressor (JSON, code, text, logs, diffs, HTML) selected by an ML content detector, scores context for relevance, and exposes a retrieve tool so the model can pull an original back when the compressed version turns out to be insufficient. On paper it is by far the more complete idea, and by any normal reading of the two READMEs it should win this comparison outright. What happens in a loop is the problem:

Rewriting the message array on every call fights prompt caching. Providers cache on an exact prefix match. When compression decisions shift between turns — and they shift, because the content shifts — the prefix changes and the cache misses. You then re-pay full input price for context you had already bought at a steep discount. That one effect can swamp everything the compressor saved.
Heavy footprint. Python 3.10+, a 150M-parameter ModernBERT model, Magika for content detection, 16–50 ms added per call.
retrieve costs a round-trip. When compression drops something the model needed, fetching it back is an extra turn, and an extra turn carries the whole conversation again.

None of that means the compression doesn't work. Measured on a single payload it works well. It means aggressive per-call rewriting inside a cached, stateful agent loop can cost more than it returns.

Why did the cheap trick beat the expensive one?

Because effort spent in the wrong place is worse than no effort at all, and caveman's footprint is small enough that it can't do damage. That's the whole result in one sentence. caveman touches the small side of the bill with a mechanism that cannot backfire, so it lands on zero. headroom touches the large side of the bill with a mechanism that perturbs the cached prefix, so it can land below zero. In a category where most tools cluster around "no measurable difference", the ability to be actively negative is the differentiator — and it belongs to the more ambitious design. The general lesson is uncomfortable and useful: a compression ratio measured on one payload tells you almost nothing about session cost. The only number that matters is what a full session costs end to end, with caching behaviour in the loop. That is why the benchmark measures sessions rather than ratios, and why popularity and measured effect turn out to be uncorrelated here — stars measure enthusiasm, not outcomes.

How much measurement is behind this?

170 runs per tool across 17 deterministic coding tasks, with results computed from successful runs only. The volume exists because agent sessions are noisy. The same task run twice can differ substantially in cost depending on which files the agent decides to read. A single before/after comparison — how most tool benchmarks in this space are run — cannot separate a real effect from that noise. Most of the "no measurable saving" verdicts in the campaign, including caveman's, would have looked like clean wins or clean losses in a one-run test. That cuts both ways, and it should make you sceptical of my numbers too. It's the reason the method and the full twelve-tool table are public.

Which one should you install?

Install caveman if you want a free five-minute experiment, and skip headroom unless you're compressing payloads outside an agent loop.

Choose caveman to prove a point, or if you genuinely like the terse output register. It won't move your invoice, but it won't hurt it either, and it costs nothing to try or to remove.
Choose headroom if you're compressing payloads in your own application code — a batch pipeline, a one-shot summarisation service — where there's no long cached conversation for the rewriting to disrupt. That's the setting its design actually suits, and it's a good tool there.
Choose neither if your token problem is whole-file reads and unfiltered agent tool output, because neither one addresses that.

What actually moves the number?

The levers that show up on an invoice are the ones that stop unnecessary context from entering the conversation at all, rather than compressing it once it has arrived: targeted retrieval instead of whole-file reads, filtering noisy output across every tool rather than one channel, reading structure before full implementations, and loading MCP manifests lazily instead of at session start. That's the design Tokenade is built on. It sits between the agent and its tools and applies those levers automatically, including folding third-party MCP results at the boundary, without rewriting conversation history behind the provider's cache. On the same open benchmark it cuts session cost by 39% on long sessions against running no tool at all. Verify that on the benchmark page, where the method and the full results are public, rather than taking it from a comparison page I wrote.

See also: