aovestdipaperino/tokensave

tokensave – Semantic Code Intelligence for AI Coding Agents

What it is – tokensave is a Rust‑based, local code‑indexing server that builds a semantic knowledge graph of a project’s source code. AI‑powered coding assistants (Claude, Gemini, Cursor, Copilot, etc.) can query this graph instead of grepping or reading files, dramatically cutting the number of tokens they spend on “explore” operations.

Why it matters – Large‑language‑model agents are billed per token. Scanning a repository with grep, find, or similar tools can consume hundreds of tokens before the agent even starts writing code. By pre‑indexing symbols, call‑graphs, and relationships, tokensave lets the agent get the exact symbol, its callers, and a snippet in a single tool call, saving cost and latency.

Key capabilities

• Semantic search – Find code by meaning (e.g., “authentication”) and receive a structured result: entry points, related symbols, and source snippets.
• Impact analysis – Trace callers, callees, and the full change‑radius of any symbol.
• Multi‑branch support – Optional per‑branch databases that reuse work from ancestor branches, so switching branches never forces a full re‑index.
• Crash‑resilient sync – Parsing runs in short‑lived subprocesses; a segfault in a Tree‑sitter grammar only kills the worker, not the whole indexing job.
• Atomic edit primitives – Safe, AST‑aware replace/insert operations that automatically re‑index the affected files.
• Broad language coverage – 50+ languages, including Rust, Go, Python, TypeScript, C/C++, Swift, shader languages, and more.
• Agent integrations – Ready‑to‑use MCP (Meta‑Coding‑Protocol) tool definitions for 12+ agents such as Claude Code, Gemini CLI, Cursor, Copilot, and many others.

How you use it

1. Install – via Homebrew, Scoop, cargo binstall, or pre‑built binaries for macOS, Linux, and Windows.
2. Register with agents – tokensave install --agent <name> writes the necessary MCP server entry and hook configuration into each agent’s native config (e.g., ~/.claude.json). A --local flag lets you keep the registration project‑specific.
3. Create an index – tokensave init creates a .tokensave/ directory containing a libSQL database with the graph. Subsequent changes are applied with tokensave sync.
4. Query from the agent – The agent calls MCP tools like tokensave_search, tokensave_branch_search, or edit primitives; the server returns instant, structured results.

Installation highlights

• Cross‑platform – Binaries for macOS (Apple Silicon), Linux (x86_64/ARM64), and Windows.
• Feature tiers – lite, medium, and full binaries let you trade binary size for language coverage.
• Zero‑trust – All data stays on‑device; no API keys or external services are required.

Advanced features

• Multi‑branch indexing – Commands like tokensave branch add/list/remove let you maintain separate graphs per Git branch, with automatic background tracking via Git hooks.
• Subprocess‑isolated extraction – Prevents a single malformed file from halting the whole sync.
• Cross‑session memory – Certain MCP tools persist context across agent sessions (details in the docs).

Who should consider it – Teams that rely heavily on LLM‑based coding assistants and want to reduce token consumption, improve response speed, and keep their code‑analysis fully local.

Where to learn more – The repository’s README, the docs/BRANCHING-USER-GUIDE.md file, and the crate page on crates.io provide deeper usage instructions and configuration details.