# tokensave puts a semantic code graph between an AI agent and your repository

> tokensave is a Rust MCP server that pre-indexes a codebase into a local libSQL knowledge graph so coding agents answer symbol questions with one tool call instead of a trail of greps and file reads. It suits teams running agents over a repository they change often, and it costs you a Rust toolchain, a local database and an index that can drift.

**aovestdipaperino/tokensave** — The most comprehensive code intelligence MCP server for AI coding agents. 40+ tools, 30+ languages, 9 agent integrations. Pre-indexed semantic knowledge graphs for instant code understanding — fewer tokens, fewer tool calls, 100% local.

- Repository: https://github.com/aovestdipaperino/tokensave
- Stars: 676 · Forks: 69
- Language: Rust
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/aovestdipaperino-tokensave

## Why agents keep paying for file exploration

The cost of an AI coding agent is not only the final patch. It is the context assembled before the patch. The project description for tokensave states the problem plainly: every grep, glob and file read costs money, and on complex tasks agents spawn multiple Explore sub-agents that scan hundreds of files just to build context. The bet here is that this exploration work does not need to run inside the model on every turn. tokensave builds a semantic knowledge graph of a codebase ahead of time, so the agent asks a graph question and receives symbols, their relationships and the surrounding source in a single call.

That is a different trade-off from a faster file search. A better grep reduces the price of each probe; a pre-built graph aims to remove most of the probes. The feature table frames the contrast directly: without the server, agents use grep, glob and Read to scan files, which produces many API calls and high token usage, while with it they query the graph over MCP tools and get results back locally. The audience is therefore teams running agents over repositories they intend to modify repeatedly, where the same clusters of symbols come up on task after task and where a locally cached index can amortize the cost of learning the code base.

## The libSQL graph that every tool call hits

The architecture shown in the project diagram has three layers. On top sits the MCP server, which agents reach over the Model Context Protocol. Inside it sit tool families for Search, Callers and Context. At the bottom sits a libSQL graph database, credited in the diagram with instant lookups and FTS5 full text search. The data flow runs from a user request such as 'Implement user authentication', down through one or more sub-agents, into a tool call, and finally into the graph.

Because storage is embedded and local, the server answers with structured symbol data rather than a raw file listing. The feature table claims 80+ MCP tools spanning call graph traversal, dead code detection, atomic edit primitives, code-health metrics, test mapping and complexity analysis. The stated purpose of the context building tool is to return entry points, related symbols and code snippets together, which is the mechanism behind the token savings claim: the agent receives a structured answer rather than a sequence of files it must read and interpret itself. Search is described as semantic rather than textual, so a query for 'authentication' is expected to surface names such as login, validateToken or AuthService. Callers and callee tracing provide the impact analysis, and the table presents that as the way to know what breaks before changing something.

## Installing tokensave and connecting it to an agent

The quick start offers one installer per platform. On macOS the documented route is a Homebrew tap:

```bash
brew install aovestdipaperino/tap/tokensave
```

On Windows the quick start adds a Scoop bucket first and then installs the package:

```powershell
scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket
scoop install tokensave
```

For any platform, the project also documents a Cargo path that installs a prebuilt binary instead of compiling, and a source build with a smaller language tier:

```bash
cargo binstall tokensave
```

Those three steps put a tokensave binary on your path. The README then lists a wide set of agent integrations, including Claude Code, Codex CLI, Gemini CLI, Cursor, OpenCode, Zed, Cline and Roo Code, and the top level of the repository contains a server.json file that describes the server to MCP clients. The README section itself is truncated in the copy available here, so the exact client configuration block is not visible to this review. Expect the install to be followed by a per-project index step, since the whole design depends on a graph that already exists when the agent asks its first question.

## Three language tiers and the binary size decision

The language coverage is the part of the project with the clearest cost attached to it. The feature table lists 50+ languages, with Rust, Go, Java, Python, TypeScript, C, C++, Swift, Svelte and Astro named explicitly, alongside shader and compute languages such as WGSL, HLSL, Metal, CUDA and HIP, plus Markdown. Grammars are grouped into three tiers, lite, medium and full, and the tiers control binary size. A source build with the medium tier is the one install command the quick start spells out with a feature flag.

The package metadata shows the build is pinned to a recent toolchain, which matters if you plan to compile rather than install a binary:

```toml
edition = "2021"
rust-version = "1.95.0"
```

The package description in Cargo.toml lists the languages it considers primary, including Rust, Go, Java, Scala, TypeScript, Python, C, C++, Kotlin and C#, and the crate is published as a command line utility in the development-tools category. The practical implication is that the tier you install should match the languages your tree actually contains. If your repository is mostly TypeScript and Go, the lighter tier is the sensible choice; if shader or CUDA code sits in the same tree, the full tier is the only one that covers it. Nothing in the documentation suggests the graph degrades gracefully around a grammar that is missing, so the tier is worth deciding before the first index rather than after.

## Index freshness, per branch databases and worktrees

A graph that is out of date is worse than no graph, so the project puts effort into staleness handling. The feature table describes an on-demand staleness check on every MCP call with a 30 second cooldown, plus a catch-up sync when the server connects. That combination means a long session can carry an index built minutes after the last edit, and a fresh session repairs the gap at startup. It also means the index is not guaranteed to reflect an edit made a second ago, which is worth keeping in mind when an agent reads a symbol and then rewrites it.

Branch handling is opt-in, with optional per-branch databases and cross-branch diff and search without switching your checkout. The documentation is unusually direct about how parallel agents are meant to work: multi-agent work is expected to use git worktrees, each agent gets its own checkout, and the resulting index divergences are merged by git rather than by a file watcher. That is a notable design position. Rather than building concurrent merge logic for the graph, tokensave delegates divergence to the version control system and keeps one index per worktree. Teams that already run agents in worktrees get a model that matches their process, and teams that do not will need to change how they hand out checkouts before the branch databases earn their keep.

## Atomic edits and a parser crash that stays contained

Two features point at the way this tool is meant to sit inside an editing loop rather than sit beside it. The first is a set of atomic edit primitives: a unique-anchor str_replace, an atomic multi-replace, an AST rewrite and an anchored insert. The stated reason is to avoid regex and shell quoting hazards, which are familiar sources of malformed edits in automated workflows. The index is also re-indexed after writes, so the graph does not immediately disagree with the file on disk. That combination matters more for agents than for humans, since an agent will often apply a mechanical replacement to a file it has not fully read.

The second feature is subprocess-isolated extraction. The project states that a native crash in any tree-sitter grammar, whether an abort, a segfault or anything else, kills only the worker, the pool respawns it, and the sync continues. The claim is that sync never dies on a malformed file. Tree-sitter grammars are third-party native code, and one bad grammar crashing the whole indexer would be a routine operational failure. Isolating each parse in a worker process converts that failure from an outage into a retry. The trade-off is that a crash costs time and must be logged, and the documentation here does not say how such failures are surfaced to the agent or the operator.

## Where tokensave is the wrong tool

The design is heavy for small problems. A local database, a background index and an MCP server are meaningful overhead when you only want to ask one question about a single script, and the token savings appear on repeated work over the same code base rather than on a one-off lookup. The same applies to a repository that is read once and never modified, where the index cost has no second round to amortize against.

The code health analytics also deserve a note. The feature table describes a composite health score on a 0 to 10000 scale, Gini inequality across files, file DAG depth, a design structure matrix, risk weighted test gaps and session deltas. These are numbers with units that are not defined anywhere in the visible documentation, so a team cannot reproduce them or argue with them from first principles. Treat them as relative signals within one project rather than targets to hit, and check how they move after an upgrade before trusting a trend.

The genuinely different alternative is to keep the model doing exploration with plain grep, glob and read tools, which is the baseline the project itself names. That approach costs more tokens per task but requires no build step, no index to keep fresh and no second service running beside your editor. A middle path is a plain language server integration for symbol and reference lookup, which many editors already have, though that gives you definitions and references rather than a caller graph, dead code detection, risk weighted test gaps or code health metrics. Choose tokensave when the repeated exploration cost across many agent sessions is the thing you want to remove, and stay with the built in tooling when it is not.

## Conclusion

tokensave fits teams that run Claude Code, Codex, Cursor or a similar agent against a repository they intend to modify, provided you accept a Rust build step and a local index that has to be kept in step with your branch. It does not fit a one-off question about a small script, a polyglot monorepo you only read once, or a workflow that requires a hosted, shared index across machines. Before adopting it, verify that your agent can reach the MCP server, that the language tier you install actually covers the languages in your tree, and that the staleness check and branch databases behave the way the feature table describes for the way your team branches.

## FAQ

### What does tokensave do for AI coding agents?

It builds a pre-indexed semantic knowledge graph of your codebase in a local libSQL database and exposes it over MCP, so an agent can ask for symbols, their callers and related code in one call instead of scanning files with grep, glob and read tools.

### How do I install tokensave?

The quick start lists `brew install aovestdipaperino/tap/tokensave` on macOS, a Scoop bucket plus `scoop install tokensave` on Windows, and `cargo binstall tokensave` or a source build with the medium feature tier on any platform.

### Does tokensave send my code anywhere?

The feature table states that no data leaves your machine, that no API keys are needed and that no external services are used, with everything running on a local libSQL database.

### How does tokensave keep the index in sync with my branch?

The documentation describes an on-demand staleness check on every MCP call with a 30 second cooldown, a catch-up sync when the server connects, and opt-in per-branch databases. For parallel agents it recommends git worktrees, where index divergences are merged by git rather than by a file watcher.

### What licence does tokensave use and is it still being worked on?

The crate is published under the MIT licence. The repository is not archived and the last push was on 2026-10-20, with releases v7.15.0 on 2026-10-07, v7.14.1 on 2026-10-02 and v7.14.0 on 2026-10-01.

## Sources

- [aovestdipaperino/tokensave on GitHub](https://github.com/aovestdipaperino/tokensave)
- [Issues](https://github.com/aovestdipaperino/tokensave/issues)
- [License: MIT](https://github.com/aovestdipaperino/tokensave/blob/master/LICENSE)
- [README](https://github.com/aovestdipaperino/tokensave/blob/master/README.md)
- [Releases](https://github.com/aovestdipaperino/tokensave/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aovestdipaperino-tokensave