codegraph vs token-optimizer: which file, or how big?

Part of the reduce Claude Code token usage pillar. This is the one pair in the category that chains cleanly instead of overlapping.

Is codegraph or token-optimizer the better choice?

They solve consecutive problems, so the real question is which half your sessions lose tokens on — and whether the licence lets you have both. codegraph answers which file: a symbol index over MCP, so the agent queries instead of opening four files to find where a function is used. token-optimizer answers how big: an AST structure map turns a 180K-token file into roughly 250 tokens of signatures and shape. If your agent wastes tokens hunting, codegraph is your tool. If it wastes them reading files it already found, token-optimizer is. Most sessions do both, which is why this pairing is more interesting than most. token-optimizer is PolyForm Noncommercial: free for personal and small-team use, paid licence for commercial use. codegraph is free and open. Resolve that before the feature comparison if you are at a company. I maintain an open long-session benchmark and sell a competing tool. codegraph lands at roughly break-even there; token-optimizer has not been measured on it.

What does codegraph actually do?

tree-sitter into an FTS5 SQLite knowledge graph, served over MCP, covering 20-plus languages and 14 frameworks: impact analysis, call graphs, symbol lookup. It is the lowest-friction install in the category. A bundled Node.js runtime removes version management, and an interactive installer detects eight agents — Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro — and writes their MCP config. The debounced file watcher shows a staleness banner when files are pending re-index, so the agent knows when its answer may be behind the working tree. Published: −35% cost and −71% tool calls, median over seven repositories. The tool-call half follows mechanically from having an index and you can verify it in one session; the cost half shows visible run-to-run variance, including a four-run spread on Tokio in codegraph's own reporting. Gaps: no output filtering, FTS5 keyword search only with no semantic retrieval, no MCP deferral — and it adds a manifest of its own — and no compression of the files the agent opens.

What does token-optimizer actually do?

Four layers:

AST structure maps — 180K tokens to roughly 250, which is 95–99% compression on exactly the payload that hurts most.
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.

Why do they chain rather than compete?

Because the structure map is what you want after the index has chosen a file. The sequence is concrete. The agent needs to change a function's behaviour. Without an index it opens several files looking for callers; codegraph replaces that with one query. It then opens the file it settled on — and that file might be 2 000 lines when the change is four. A structure map turns that read into signatures and shape, and the agent asks for the specific region it needs. Neither tool does the other's step. codegraph tells you where; it does not shrink what you open. token-optimizer shrinks what you open; it does not help you decide which file that is. That is why running both is coherent in a way that running two indexes, or an index plus a window compressor, is not. The costs are ordinary: two installs, one index to keep fresh, one MCP manifest paid every turn — and the licence question if this is commercial work.

Two published numbers, two scopes

Both vendors measured honestly and neither number is your bill. codegraph's −71% tool calls is scoped to navigation behaviour, measured across seven repositories. Its −35% cost is downstream of that and carries the variance you would expect. token-optimizer's 180K-to-250 is scoped to one file replacement. Rigorous, and silent about how much of your session is large-file reads. The reconciliation is the same as everywhere in this category: per-channel savings are real and per-session savings depend on the mix. Run npx ccusage@latest for a week before attributing a disappointing invoice to either tool.

What does neither of them do?

Command output at the tool boundary. codegraph is not on that path; token-optimizer's compaction is session-level, not a per-command filter.
MCP manifests. Neither defers them, and codegraph adds one.
Semantic retrieval. codegraph 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.

Which one should you pick?

Resolve the licence first if you are at a company. PolyForm Noncommercial means a paid licence for commercial use, and discovering that after a team rollout is the expensive order. Pick codegraph if the agent spends its time finding things, or if you want the easiest install to put in front of a team. 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. This is the pair where chaining actually adds up.

How to apply this today

Settle the licence question first. Two minutes, and the only irreversible decision here.
Count tool calls for a session to size codegraph's half.
Find your largest file reads to size token-optimizer's half. If a handful of big files dominate, the structure map is the highest-leverage change available.
Change one thing at a time and measure for a week, not a task.

What goes wrong (anti-patterns)

Rolling out a noncommercial-licensed tool across a company. The most expensive mistake on this page, and it has nothing to do with tokens. Reading either published number as a bill reduction. Both are honest at a scope smaller than your invoice. Trusting a stale index. codegraph warns you; act on the banner rather than ignoring it. Assuming an unmeasured tool is safe. token-optimizer's absence from the open benchmark is missing evidence, not a clean result.

See also: