Fewer tokens • Fewer tool calls • 100% local
AI coding agents waste tokens exploring codebases. Every grep, glob, and file read costs money. On complex tasks, agents spawn multiple Explore sub-agents that scan hundreds of files just to build context.
tokensave gives agents a pre-indexed semantic knowledge graph. Instead of scanning files, the agent queries the graph and gets instant, structured answers -- the right symbols, their relationships, and source code, in one call.
flowchart TB
subgraph agent["AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)"]
task["Implement user authentication"]
first["Sub-agent"]
second["Sub-agent"]
task --> first
task --> second
first --- second
end
subgraph server["tokensave MCP Server"]
search["Search: auth"]
callers["Callers: login()"]
context["Context for task"]
db[("libSQL Graph DB<br/>Instant lookups<br/>FTS5 search")]
search --> db
callers --> db
context --> db
end
first --> search
first --> callers
second --> context
Without tokensave: Agents use grep, glob, and Read to scan files -- many API calls, high token usage.
With tokensave: Agents query the graph via MCP tools -- instant results, local processing, fewer tokens.
| Smart Context Building | Semantic Search | Impact Analysis |
| One tool call returns everything the agent needs -- entry points, related symbols, and code snippets. | Find code by meaning, not just text. Search for "authentication" and find login, validateToken, AuthService. |
Know exactly what breaks before you change it. Trace callers, callees, and the full impact radius of any symbol. |
| 80+ MCP Tools | 50+ Languages | 12+ Agent Integrations |
| From call graph traversal to dead code detection, atomic edit primitives, code-health metrics, test mapping, and complexity analysis. | Rust, Go, Java, Python, TypeScript, C, C++, Swift, Svelte, Astro, and 43 more including WGSL/HLSL/Metal shaders, CUDA/HIP, and Markdown. Three tiers (lite/medium/full) control binary size. | Claude Code, Codex CLI, Gemini CLI, Qwen Code, Kiro, Cursor, OpenCode, Copilot, Cline, Roo Code, Zed, Antigravity, Kilo CLI, Kimi CLI, Mistral Vibe, Grok Build, Factory Droid, OMP, Pi, Plank. |
| Multi-Branch Indexing (opt-in) | 100% Local | Always Fresh |
| Optional per-branch databases. Cross-branch diff and search without switching your checkout. | No data leaves your machine. No API keys. No external services. Everything runs on a local libSQL database. | On-demand staleness check on every MCP call (30 s cooldown) plus catch-up sync when the server connects. Multi-agent work is expected to use git worktrees — each agent gets its own checkout and the index diverges are merged by git, not by a file watcher. |
| Subprocess-Isolated Extraction | Code-Health Analytics | Atomic Edit Primitives |
| A native crash in any tree-sitter grammar (abort, segfault, anything) kills only the worker; the pool respawns it and sync continues. Sync never dies on a malformed file. | Composite health score (0-10000), Gini inequality, file-DAG depth, design-structure matrix, risk-weighted test gaps, and session deltas. | Edit files without regex or shell-quoting hazards: unique-anchor str_replace, atomic multi-replace, AST-rewrite, anchored insert. Auto re-indexes after writes. |
Choose one installation method:
| Platform | Command |
|---|---|
| Any platform (Cargo) | cargo install tokensaveor, with cargo-binstall, cargo binstall tokensave |
| macOS (Homebrew) | brew install aovestdipaperino/tap/tokensave |
| Windows (Scoop) | scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucketscoop install tokensave |
You can also download a prebuilt binary and add it to your PATH.
To build unreleased code from the upstream master branch, see
Installing from upstream master.
Installation alternatives and language tiers
The default Cargo build includes all supported languages. For a smaller build:
cargo install tokensave --no-default-features --features medium
cargo install tokensave --no-default-features # lite (smallest binary)Prebuilt release archives:
| Platform | Archive |
|---|---|
| macOS (Apple Silicon) | tokensave-vX.Y.Z-aarch64-macos.tar.gz |
| Linux (x86_64) | tokensave-vX.Y.Z-x86_64-linux.tar.gz |
| Linux (ARM64) | tokensave-vX.Y.Z-aarch64-linux.tar.gz |
| Windows (x86_64) | tokensave-vX.Y.Z-x86_64-windows.zip |
Run the setup command to auto-detect your installed agents:
tokensave installTo choose an agent, use --agent (for example, codex, claude, or cursor):
tokensave install --agent codexSetup registers the MCP server and the agent's integration for Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot, Kiro, Pi, Zed, and more than a dozen other agents. It also offers global Git hooks to keep initialized projects up to date. You can safely run setup again after upgrading. See Agent Integrations for project-local installs, several agents at once, and what setup writes for each agent.
cd /path/to/your/project
tokensave initThis creates a .tokensave/ directory with the knowledge graph database. init
is a one-time opt-in per project; after it, tokensave sync updates the index
incrementally, and a connected agent keeps it fresh automatically. Commands work
from any subdirectory of the project. See
Indexing and Freshness for details.
The full documentation lives in docs/guide/ and is
mirrored to the GitHub Wiki.
| Topic | What it covers |
|---|---|
| Installation and Upgrades | Language tiers, self-upgrade and channels, versioning, building from source |
| Agent Integrations | Supported agents, project-local setup, what install writes |
| Indexing and Freshness | Project discovery, index freshness, crash-resilient sync, custom extensions |
| MCP Tools | The 80+ tools by category, cross-project queries, MCP resources |
| Multi-Branch Indexing | Per-branch graphs, automatic tracking, branch quality regressions |
| Token Tracking and Cost | Savings ledger, cost reports, live monitor, memory diagnostics |
| CLI Reference | Every command at a glance |
| Supported Languages | 50+ languages and their feature tiers |
| Network Calls and Privacy | What leaves your machine and how to opt out |
| Troubleshooting | tokensave doctor and common problems |
| Benchmarks | Retrieval-savings and performance benchmarks |
| Comparisons | tokensave compared with CodeGraph and alternatives |
The long-form User Guide walks through everyday use in more depth. To contribute, see CONTRIBUTING.md.
This project is a Rust port of the original CodeGraph TypeScript implementation by @colbymchenry. The port maintains the same architecture and MCP tool interface while leveraging Rust for performance and native tree-sitter bindings.
To build from source, see Building from source and CONTRIBUTING.md.
|
Free code signing on Windows provided by SignPath.io, certificate by SignPath Foundation |
MIT License -- see LICENSE for details.