For a few weeks now, a tool has been running in my projects that is invisible in daily use - until you look at the counter. tokensave has saved me over 12 million tokens so far. It's an MCP server that gives Claude Code a local code graph to query, instead of letting the model read whole files and search through the repository as plain text. Here's what it does, how it works under the hood, what a reproducible benchmark says about it - and where its limits are.
A quick detour: why tokens are the currency #
Language models don't read and write in characters or words, but in tokens - word fragments of roughly three to four characters. Everything an AI assistant gets to see counts: your question, the system instructions, and above all every file and every search result it loads into its context. As an order of magnitude, a source file with 1,000 lines costs around 10,000 tokens - per request, because the context window is transmitted anew with every API call.
That has two consequences. First, money: billing is per token, usually priced per million. If your assistant reads half a repository for every code question, you pay for it. Second, quality: a model's context window is finite - between 200,000 and one million tokens on current models - and the fuller it is with irrelevant code, the less room remains for what actually matters.
How a model splits text - and why code is expensive #
The splitting into tokens is done by a tokenizer, usually based on Byte Pair Encoding (BPE): the algorithm learns from large text corpora which character sequences frequently occur together and merges them into single tokens. Common English words become one token; rare ones fall apart into several. Three things follow from this that are worth knowing when you're trying to save:
First, code tokenizes differently from prose. Indentation, brackets, and special characters are tokens of their own, and an identifier like getUserAccountBalance
breaks into several fragments - source code is often more expensive per character than plain text. Second, German is more expensive than English: tokenizers are trained predominantly on English text, so long German compound words split more finely. And third, token counts are not comparable across model generations - a new tokenizer can count the same text roughly a third differently. The rule of thumb "1,000 lines ≈ 10,000 tokens" is therefore exactly that: a rule of thumb.
Less context isn't just cheaper - it makes answers better #
One could object: context windows keep growing, so why save at all? Because large contexts have a documented quality problem. In 2023, Liu et al. showed in "Lost in the Middle: How Language Models Use Long Contexts" that language models use information at the beginning and end of a long context far more reliably than information in the middle - retrieval accuracy measurably drops there.
For code questions, that means: if you dump three complete files into the model's context, 95 percent of which are irrelevant, you don't just pay for the irrelevant tokens - you also risk the relevant passage drowning in the middle of the context. Fewer but better-targeted tokens are therefore not just about thrift; they're a quality lever.
What is tokensave? #
Anyone who has watched an AI assistant work through a codebase knows the pattern: to answer "where is this function called?", it first reads three files end to end, then greps its way through half the repository. That works - but it burns thousands of tokens every time, most of which contribute nothing to the answer.
tokensave (github.com/aovestdipaperino/tokensave, MIT license, around 450 stars on GitHub) tackles exactly that: instead of searching code as text, it answers questions about the structure of the code - from a local graph that is built once and then queried on demand. According to the project, it supports 34 programming languages, from Rust to Python, TypeScript, and Swift.
How the code graph works #
During indexing, tokensave breaks the codebase down into its building blocks: functions, methods, types, and modules become nodes; their relationships - who calls whom, who imports what - become edges. The result is stored as a libSQL database (a SQLite fork) in the project folder. If you look inside, you'll find more than just the core tables nodes
, edges
, and files
: an FTS5 full-text index for symbol search, a vectors
table with embeddings for semantic similarity, and fingerprint tables that let the incremental sync detect which files have changed - a sync after small changes takes a measured 21 milliseconds on my machine.
This architecture explains why queries are so cheap: the expensive part - parsing, indexing, embedding - happens once at init. After that, every question is just a database lookup. Asked the classic way, "where is parse_config
called?", the assistant has to read files or load grep hits with their surroundings into context. With tokensave, it asks the graph the same question and gets back a list of call sites, plus, on request, exactly the affected code sections: a few hundred tokens instead of thousands.
On top of that sits a whole toolbox: symbol search, call chains across multiple levels, impact analysis ("what breaks if I change this?"), dead-code detection. For more complex structural questions, you can even query the database directly with SQL.
What the graph doesn't see #
Honesty requires saying this too: a statically built graph only knows what can be resolved statically. Dynamic dispatch, reflection, duck typing in Python, macros - anything decided at runtime never becomes an edge. My own website project illustrates it: the graph contains 1,115 nodes but only 252 edges, all of them function calls. In a small Python and JavaScript codebase with a lot of dynamic glue, the relationship network stays sparse; in a large, statically typed Rust or Java codebase, the ratio would look very different.
In practice that means: for "where is symbol X defined and who calls it directly?", the graph is excellent. For "which handler gets registered at runtime via this config file?", it doesn't help - that's still a job for classic reading. tokensave doesn't replace code understanding; it makes the most common navigation questions cheap.
Setup in five minutes #
The setup itself is unremarkable:
Install via crates.io, Homebrew, or as a prebuilt binary; ends up at e.g.~/.local/bin/tokensave
.inside the project folder createstokensave init
.tokensave/tokensave.db
and indexes the code.registers the tool as an MCP server in the agent configuration - after that, thetokensave install
tokensave_*
tools are available in Claude Code.- After external changes, especially after a
git pull
:. Otherwise the graph works off a stale state.tokensave sync
fetches new versions from GitHub.tokensave upgrade
Step 4 is the only one you really need to remember - more on why below.
Measured: the benchmark #
Claimed savings are one thing; reproducible measurements are another. tokensave ships its own command for this: tokensave bench
asks ten standard questions about the current project ("How is configuration loaded?", "How are errors defined and propagated?", …) and compares the token cost of the graph answer against the baseline, i.e. reading the relevant files.
The result in my website project: 94 percent mean savings - 53,900 tokens for the baseline versus 3,000 tokens across all ten questions, so roughly 5,000 to 6,000 tokens per question the classic way against about 300 via the graph. If you want it even more concrete: tokensave discover
analyzes your own Claude Code history and shows which past navigation steps a graph query would have handled more cheaply.
What it delivers day to day #
The savings aren't an estimate; they're right there in the built-in counter: over 12 million tokens across all my projects, growing daily. A pleasant side effect: answers to code questions arrive noticeably faster, because less context has to pass through the model - and they tend to be more precise, for exactly the "Lost in the Middle" reason above.
The prompt-caching nuance #
An obvious objection: the API providers cache anyway. True - with prompt caching, an unchanged context prefix is stored, and cache reads cost only about a tenth of the normal input price. That softens the "paid anew on every request" from the token detour, but it doesn't replace tokensave, because the two levers work in different places: caching makes re-reading the same bloated context cheaper - and even a small change at the beginning invalidates the cache. tokensave keeps the context from getting bloated in the first place. One is a discount on a large bill; the other makes the bill small. In practice, you benefit from both at once.
Where it stumbles #
The biggest pitfall is staleness. When the code changes outside your own session - the classic case being a git pull
- the graph keeps working off the old state. To be fair: current versions detect commits since the last sync and warn explicitly in the status check ("1 commit since last sync"). But if you miss the warning, you still get quietly wrong answers until
tokensave sync
runs - and until then, you'll be hunting the bug in the wrong place.
Two smaller limitations on top of that: queries are capped per task, so complex questions have to be bundled instead of tried one at a time. And tokensave only answers questions about code structure - for web search, documentation, or anything beyond the repository, it naturally does nothing.
Local, but not network-free: the worldwide counter #
The code graph, the search, the embeddings - all of that runs locally; no source code leaves the machine. Still, tokensave isn't entirely network-free, and that belongs in any honest review: by default, it reports the number of saved tokens to a public "worldwide counter". What gets transmitted is a single HTTP POST with one number (something like {"amount": 4823}
); the country of origin is derived server-side from the IP - no code, no file names, no user ID. Add to that version checks against the GitHub releases API for upgrade
.
Both are documented and can be turned off (tokensave disable-upload-counter
). I've deliberately left the upload on - partly because the global counter is a nice argument for the tool itself: it currently stands at around 17.6 billion tokens saved across all users worldwide.
My experience #
A tool that writes itself into the agent configuration and reads along with every code question doesn't get the benefit of the doubt from me. So before putting it into production use, I looked at the repo metadata, the commit history, and its runtime behavior - the result was an actively maintained open-source project whose network behavior matches exactly what the documentation states: the counter upload, the version checks, nothing else.
Since then, exactly what you'd hope for from a tool like this has happened: nothing. No incident, no surprise - just a counter that keeps growing and code questions that get answered faster. By now, tokensave is the first tool I reach for when researching code in any of my projects.
Verdict #
tokensave is no miracle cure, but a well-thought-out specialist tool: it does one thing - answering code questions without full-text reads - and it does that measurably well, in my case with 94 percent savings in the reproducible benchmark and over 12 million tokens saved in daily use. The limits are known and manageable: the graph only sees static structure, it wants a sync after external changes, and anyone who insists on complete network abstinence turns off the counter upload. If you regularly work with AI assistants in larger codebases, it's worth a look. Just that tokensave sync
after a git pull
- that one you really need to remember.
Sources #
- tokensave on GitHub:
[github.com/aovestdipaperino/tokensave](https://github.com/aovestdipaperino/tokensave)- source code, license, worldwide-counter documentation, and commit history - Liu et al. (2023):
[Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)- study on retrieval accuracy in long contexts - Anthropic:
[Prompt caching documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)- how prefix caching works and how it's priced