tokensave vs token-optimizer: find it, or shrink it?

Part of the reduce Claude Code token usage pillar. These two solve consecutive steps of the same problem, which makes the comparison unusually clean.

Is tokensave or token-optimizer the better choice?

They answer different halves: tokensave finds the file, token-optimizer shrinks it — and the licence decides whether you can have both. tokensave is a Rust MCP server over a symbol index across 34 languages. token-optimizer replaces a large file with an AST structure map: 180K tokens become roughly 250. token-optimizer is PolyForm Noncommercial — free for personal and small-team use, paid licence for commercial use. tokensave is free and open. If you are at a company, settle that before comparing anything else. Neither has been measured on my open long-session benchmark, and tokensave publishes no benchmark of its own. I run that benchmark and sell a competing tool, so what follows is mechanism, not ranking.

What does tokensave actually do?

A compiled symbol index served over MCP. A semantic knowledge graph in libSQL with FTS5, built by tree-sitter extraction across 34 languages, with 48 MCP tools.

Compiled: fast startup, low memory, no runtime. Homebrew on macOS, Scoop on Windows, prebuilt binaries elsewhere.
Multi-branch indexing — diff and search across branches without switching checkout, which nothing else here does.
Subprocess isolation, so one parser crash on a malformed file does not take the service down.
Atomic edit primitives with AST rewriting, avoiding the regex and shell-quoting hazards that make agentic edits fail quietly.

Its 48-tool manifest is a standing per-turn input cost, billed whether or not the agent queries the index. Other gaps: no output filtering, no semantic vector search, fourteen hardcoded frameworks, no published savings.

What does token-optimizer actually do?

Four layers, with the structure map doing the heavy lifting:

AST structure maps — 180K tokens to roughly 250, which is 95–99% compression on exactly the payload that hurts most. It works because the agent usually needs to know what is in a file rather than to read it.
Smart compaction with progressive checkpoints, condensing session state as it grows.
A 7-signal quality score, watching for mid-session context degradation. Almost nothing else in this category models that.
A full HTML dashboard: per-turn costs, model mix, cache analysis, subagent breakdown, drift detection.

It runs on Claude Code, OpenCode, OpenClaw and Codex, with heavier setup away from Claude Code, a substantial local Python dependency, and no transparent API for third-party integration.

Two AST users, doing opposite things with it

Both parse your code into a tree. Then they diverge completely, and it is worth being precise about how. tokensave uses the AST to build an index — a persistent, queryable store of symbols and relationships, and a safe path for edits. The tree is infrastructure: it exists between sessions and answers questions about the whole repository. token-optimizer uses the AST to build a view — a compressed representation of one file, produced on demand and handed to the model instead of the raw contents. The tree is a transformation, not a store. That is why the two chain rather than compete. tokensave narrows twelve candidate files to one; token-optimizer makes reading that one cost 250 tokens instead of 180,000. Neither performs the other's step. It is also why running two indexes is wasteful while running an index plus a structure map is not: only one of these is trying to be a store.

What does neither of them do?

Command output at the tool boundary. tokensave never sees it; token-optimizer's compaction is session-level, not a per-command filter.
MCP manifests. Neither defers them, and tokensave adds a large one.
Semantic retrieval. tokensave is FTS5 keyword search; token-optimizer does not search at all.
Re-reads. A structure map makes each read smaller; nothing here notices the repetition.

What the manifest costs you, in the shape it actually arrives

A large MCP surface is the one cost in this comparison that is charged when nothing happens. tokensave's 48 tool definitions are sent as input tokens ahead of your first message, on every turn, whether or not the agent queries the index. On a week of terminal-heavy work — a build loop, an infrastructure task, a dependency upgrade — that is a bill for a capability you did not use. token-optimizer has no equivalent. Its structure map costs something when a file is read and nothing when it is not, which is the better default for anyone whose sessions vary in shape. The fix on the tokensave side is not to avoid it but to disconnect it deliberately on sessions that plainly do not need navigation. That is a habit rather than a configuration, and it is invisible unless you go looking: the charge shows up in your input tokens on days you did no code navigation at all, and nowhere else. A usage meter is how you notice.

Which one should you pick?

Resolve the licence first if this is commercial work. PolyForm Noncommercial means a paid licence for commercial use, and discovering that after a team rollout is the expensive order. It has nothing to do with tokens and it is the only irreversible decision here. Pick tokensave if your stack spans many languages, you review branches often, or you want a compiled binary with no runtime and a safer edit path. Pick token-optimizer if you are an individual or small team on Claude Code and large files dominate your reads. The structure map is the strongest single mechanism in this comparison, and the dashboard shows whether it worked. Pick both if the licence allows and your sessions both hunt and read. That combination chains cleanly.

How to apply this today

Settle the licence question. Two minutes.
Find your largest file reads. If a handful of big files dominate, the structure map is the highest-leverage change available to you.
Count tool calls before and after if you install the index. That is the metric it moves.
Watch input tokens on terminal-only days. A 48-tool manifest shows up there and nowhere else.

What goes wrong (anti-patterns)

Rolling out a noncommercial-licensed tool across a company. The most expensive mistake on this page. Leaving a 48-tool manifest connected on sessions that never query it. Billed every turn regardless. Reading 180K-to-250 as a bill reduction. Honest compression on one payload, at a scope smaller than your invoice. Judging an unbenchmarked tool by its feature list. 34 languages is a capability fact, not a saving.

See also: