headroom vs tokensave: compress or index the code?

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

Is headroom or tokensave the better choice?

tokensave carries less risk; headroom carries more upside on the narrow workloads it fits. They do not overlap at all. headroom rewrites the message array before every API call. tokensave gives the agent an index so it stops needing to read as much in the first place. One intervenes on what the provider sees, the other on what the agent asks for, and that difference decides almost everything else. I run an open long-session benchmark and sell a competing tool. On it, headroom finished 53% more expensive than running no tool at all, last of twelve. tokensave has not been through it and publishes no benchmark of its own, so its savings are unquantified. Those are two different statements and neither is a verdict on the engineering.

What does headroom actually do?

It compresses the whole conversation window before each call. Python SDK plus CLI proxy plus MCP server, Apache 2.0, roughly 18.7k stars, in three stages: 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 the remainder on six relevance dimensions. It is reversible. Originals stay in a local LRU cache and the model gets an injected headroom_retrieve tool, with optional BM25 sub-search, to pull one back. The per-workload compression numbers are genuinely strong: 92% on code-search results and SRE incident logs, 73% on issue triage. SmartCrusher samples large JSON arrays at 70–95% while always keeping error lines, which is the kind of detail that shows the project thought about failure modes. The footprint is heavy: Python 3.10+, a 150M-parameter ModernBERT model, Magika content detection, 16 to 50 ms per call.

What does tokensave actually do?

It builds a symbol index and serves it over MCP. A Rust server with a semantic knowledge graph in libSQL with FTS5, built by tree-sitter extraction across 34 languages, exposing 48 MCP tools. Its distinctive features are all about the shape of the tool rather than the compression rate:

Compiled. Fast startup, low memory, no runtime to install. Homebrew on macOS, Scoop on Windows, prebuilt binaries elsewhere.
Multi-branch indexing. Diff and search across branches without switching checkout — nothing else in this category does that, and it removes a class of context-burning git checkout round-trips.
Subprocess isolation. One parser crashing on a malformed file does not take the service down, which matters with 34 grammars in play.
Atomic edit primitives with AST rewriting. The agent renames a symbol through the tree rather than through a regex, avoiding the shell-quoting and partial-match hazards that make agentic edits fail quietly.

Its gaps: no output filtering, so command output still arrives at full size; navigation only, with no semantic vector search and no structural compression; framework detection limited to fourteen hardcoded frameworks; and no published numbers.

Why does the compressor carry more risk?

Because it spends prompt caching to buy token count. 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 tool that rewrites the window changes the prefix whenever its compression decisions change — which is whenever the content changes, meaning every turn of an agent loop. The cache misses and you re-pay full price for context you already bought. CacheAligner exists to fight exactly this, which tells you the project understands the risk. On a long interactive loop it is not enough. There is a second path. When the compressed version is not enough, the model calls headroom_retrieve and pulls the original back — so you paid for the compressed copy, the original, and the round-trip. Rare on a short task, compounding on a session. An index has no equivalent failure. It does not touch the prefix, so caching keeps working. Its worst case is a stale index giving a confident wrong answer, which costs a correction, not a systematic multiplier. That asymmetry is the real content of this comparison.

Where does tokensave's 48-tool surface cost you?

On every turn, before you call anything. MCP tool definitions are sent as input tokens ahead of your first message, used or not. A 48-tool server is a larger standing cost than a 10-tool one, and it is invisible unless you go looking. That is not a reason to avoid it — the tools are the product — but it is a reason to disconnect it on sessions that are pure terminal work, and a reason not to run two indexes at once.

What does neither of them do?

Command output. tokensave never sees it. headroom compresses it inside the window, after it has already been produced and paid for once at the tool boundary.
Whole-file reads for editing. An index says which file; it does not shrink it. A compressor shrinks it and risks the cache.
MCP manifests. Neither defers them. tokensave adds a large one.
Re-reads. Same file, four times, four charges. An index lowers the odds; neither deduplicates.

Which one should you pick?

Pick tokensave if you work across many languages, want a single compiled binary with no runtime, or review branches often enough that multi-branch search maps onto your real workflow. The atomic edit primitives are a genuine safety improvement on any agent that edits through shell commands. Pick headroom if your workload is batch rather than interactive: long, stable payloads processed once, where the prefix is not invalidated every turn and 92% off a large JSON blob is the whole story. That is a real use case and it is not an agent coding loop. Pick neither yet if your spend is mostly command output. Neither is positioned on that channel in a way that survives a session.

How to apply this today

Check your cache-hit rate before installing anything that rewrites the window. If it is high, a compressor is spending your best asset.
Count tool calls for one session if you are evaluating the index. That is the metric it moves and the one you can verify yourself.
Disconnect what you are not querying. A 48-tool manifest on a terminal-only session is pure loss.
Measure for a week, not for a task. These two look completely different at those scales.

What goes wrong (anti-patterns)

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. Treating "not benchmarked" as "does not work". tokensave publishes no figure. That is missing evidence, not evidence of failure. Running a compressor on top of an index. The index makes the window small; the compressor then destabilises the prefix that just got small. You get both downsides. Ignoring the manifest cost of a large MCP surface. It is charged on every turn, including the turns where you never touch a single one of those tools.

See also: