headroom vs token-optimizer: two multi-layer bets

Part of the reduce Claude Code token usage pillar. This page is the head-to-head between the two most feature-dense tools in the category.

Is headroom or token-optimizer the better choice?

token-optimizer, for most people — and if you are a company, read its licence before you read anything else. Both stack several techniques rather than betting on one. The split that matters is where they intervene: headroom rewrites the message array before every API call; token-optimizer works mostly upstream of that, replacing large files with AST structure maps and watching context quality as the session runs. On my open long-session benchmark, headroom finished 53% more expensive than running no tool at all, last of twelve. token-optimizer has not been through it. I run that benchmark and sell a competing tool, so what follows is mechanism rather than ranking.

What does token-optimizer actually do?

Four layers, and they are genuinely different from each other:

AST structure maps. A 180K-token file becomes roughly 250 tokens of structure — signatures, symbols, shape. That is 95–99% compression on exactly the payload that hurts most, and it works because the agent usually needs to know what is in a file, not to read it.
Smart compaction with progressive checkpoints. Session state is condensed as it grows, rather than dumped and restarted.
A 7-signal quality score. It watches for context degradation mid-session — the slow drift where an agent's answers get worse because its window filled with noise. Almost nothing else in this category models that at all.
A dashboard. Per-turn costs, model mix, cache analysis, subagent breakdown, skill adoption, drift detection. Full HTML, not a CLI table.

It runs on Claude Code, OpenCode, OpenClaw and Codex. Its licence is PolyForm Noncommercial. Free for personal and small-team use; commercial use requires a paid licence. That is not a footnote — it is the first thing to check if you are installing this at a company, and it is the single biggest practical difference between these two tools. headroom is Apache 2.0 with no such condition. The other costs: setup is more involved on non-Claude Code platforms, it carries a heavy Python dependency on local environments, and it exposes no transparent API for third-party integration.

What does headroom actually do?

It compresses the whole conversation window before each API call. Python SDK plus CLI proxy plus MCP server, Apache 2.0, roughly 18.7k stars. CacheAligner moves timestamps and UUIDs out of the static prefix into a non-cached tail; ContentRouter routes each piece of content to a format-specific compressor via ML detection — JSON, code, text, logs, diffs, HTML; IntelligentContext scores what remains across six relevance dimensions. It is reversible: originals sit in a local LRU cache with an injected headroom_retrieve tool and optional BM25 sub-search. Per-workload compression is strong — 92% on code-search results and SRE incident logs, 73% on issue triage. The footprint is heavy: Python 3.10+, a 150M-parameter ModernBERT model, Magika content detection, 16 to 50 ms per call.

Why does the intervention point matter so much?

Because one of these two spends prompt caching and the other does not. Caching pays only when the prefix is byte-identical between turns, and cached input is billed at a fraction of fresh input on every major provider. A window rewriter changes the prefix whenever its compression decisions change, which is every turn in an agent loop. The cache misses, and you re-pay full price for context you already bought. CacheAligner exists precisely to fight this; on a long interactive loop it is not enough. An AST structure map has no equivalent problem. It replaces a file with a smaller representation before that content enters the window, so what the provider caches is stable. The saving is banked once and it stays banked. This is the same reason headroom has a second failure path that token-optimizer does not: when a compressed payload turns out to be insufficient, the model calls headroom_retrieve and pulls the original back, so you paid for the compressed copy, the original, and the round-trip.

What is the quality score worth?

More than its feature-list position suggests. Every other tool here optimises cost and lets you discover the quality cost yourself. A 7-signal degradation score is an attempt to make the trade-off visible while the session is running rather than after it produced a bad answer. Whether it is accurate is not something I can verify from outside, and neither can you without running it. But it is the only tool in this comparison that treats "did compression make the agent worse" as a measurable question rather than an accepted risk. That framing is right even if the implementation turns out to be imperfect.

What does neither of them do?

Command output at the tool boundary. headroom compresses it inside the window, after it has already been produced and paid for once. token-optimizer's compaction is a session-level operation, not a per-command filter.
MCP manifests. Every connected server ships tool definitions before your first message, used or not. Neither defers them.
Semantic code retrieval. Neither replaces a search with a targeted answer.
Re-reads. Same file, four times, four charges.

Which one should you pick?

Pick token-optimizer if you are an individual or small team, you work in Claude Code, and large files are where your tokens go. The AST structure map is the strongest single mechanism in this comparison, and the dashboard means you can see whether it worked. Check the licence first if you are a company. PolyForm Noncommercial means a paid licence for commercial use. Deciding that after deployment is the expensive order. Pick headroom if your workload is batch rather than interactive: long, stable payloads processed once, where the prefix is not being invalidated every turn and 92% off a large JSON blob is the whole story.

How to apply this today

Check your licence exposure before installing anything. It takes two minutes and it is irreversible if you get it wrong at scale.
Look at your cache-hit rate before installing a window rewriter. If it is high, that is the asset you would be spending.
Find your largest file reads. If a handful of big files dominate, a structure map is the highest-leverage single change available to you.
Measure for a week, not a task. Compression and caching effects diverge at those scales.

What goes wrong (anti-patterns)

Deploying a noncommercial-licensed tool across a company. The most expensive mistake available on this page, and it has nothing to do with tokens. Reading a per-payload compression rate as a session saving. 92% off one blob and 53% more expensive over a session are both true of headroom. Stacking both. The structure map makes the window small; the window rewriter then destabilises the prefix that just got small. Assuming an unmeasured tool is safe. token-optimizer's absence from the benchmark is missing evidence, not a clean bill of health.

See also: