Tokensave

<p align="center"> <img src="src/resources/logo.png" alt="TokenSave" width="300"> </p> <h3 align="center">Supercharge Claude Code with Semantic Code Intelligence</h3> <p align="center"><strong>Fewer tokens &bull; Fewer tool calls &bull; 100% local</strong></p> <p align="center"> <a href="https://crates.io/crates/tokensave"><img src="https://img.shields.io/crates/v/tokensave.svg" alt="crates.io"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/Rust-1.70+-orange.svg" alt="Rust"></a> </p> <p align="center"> <img src="https://img.shields.io/badge/macOS-supported-blue.svg" alt="macOS"> <img src="https://img.shields.io/badge/Linux-supported-blue.svg" alt="Linux"> <img src="https://img.shields.io/badge/Windows-supported-blue.svg" alt="Windows"> <a href="https://hypercommit.com/tokensave"><img src="https://img.shields.io/badge/Hypercommit-DB2475" alt="Hypercommit"></a> </p>

---

Why tokensave?

When Claude Code works on a complex task, it spawns Explore agents that scan your codebase using grep, glob, and file reads. Every tool call consumes tokens.

tokensave gives Claude a pre-indexed semantic knowledge graph. Instead of scanning files, Claude queries the graph instantly — fewer API calls, less token usage, same code understanding.

How It Works

┌──────────────────────────────────────────────────────────────┐
│  Claude Code                                                 │
│                                                              │
│  "Implement user authentication"                             │
│        │                                                     │
│        ▼                                                     │
│  ┌─────────────────┐       ┌─────────────────┐               │
│  │  Explore Agent  │ ───── │  Explore Agent  │               │
│  └────────┬────────┘       └─────────┬───────┘               │
└───────────┼──────────────────────────┼───────────────────────┘
            │                          │
            ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│  tokensave MCP Server                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Search    │  │   Callers   │  │   Context   │           │
│  │   "auth"    │  │  "login()"  │  │   for task  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌───────────────────────┐                       │
│              │   libSQL Graph DB     │                       │
│              │   • Instant lookups   │                       │
│              │   • FTS5 search       │                       │
│              │   • Vector embeddings │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Without tokensave: Explore 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.

---

Key Features

| | | | |---|---|---| | Smart Context Building | Semantic Search | Impact Analysis | | One tool call returns everything Claude 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. | | 31 Languages | 100% Local | Always Fresh | | Rust, Go, Java, Python, TypeScript, C, C++, Swift, and 22 more — all with the same API. Three tiers (lite/medium/full) let you control binary size. | No data leaves your machine. No API keys. No external services. Everything runs on a local libSQL database. | Git hooks automatically sync the index as you work. Your code intelligence is always up to date. |

---

What's New in v3.3

sync --doctor

The sync command now accepts a --doctor flag that lists every added, modified, and removed file after an incremental sync. Useful for verifying what changed in the index without digging through logs.

34 MCP Tools

Five new tools round out the analysis suite:

• tokensave_commit_context — semantic summary of uncommitted changes for drafting commit messages
• tokensave_pr_context — semantic diff between git refs for pull request descriptions
• tokensave_simplify_scan — quality analysis of changed files (duplications, dead code, complexity, coupling)
• tokensave_test_map — source-to-test mapping at the symbol level, with uncovered symbol detection
• tokensave_type_hierarchy — recursive type hierarchy tree for traits, interfaces, and classes

All 34 tools now include MCP annotations (readOnlyHint, title) and the three core tools (tokensave_context, tokensave_search, tokensave_status) are marked anthropic/alwaysLoad so they bypass the client's tool-search round-trip.

Upgrade-Aware Daemon

The background daemon now detects when its binary has been replaced (via brew upgrade, cargo install, scoop update, or any package manager) and automatically restarts with the new version. On Windows, the service is configured with SCM failure recovery actions for automatic restart.

MCP Resources

Three resources are exposed via resources/list and resources/read: tokensave://status, tokensave://files, and tokensave://overview.

<details> <summary>Previous releases</summary>

v3.2 — 13-26x Faster Indexing

Full index performance improved through rayon parallel extraction, prepared-statement DB writes, suffix-indexed reference resolution, and bulk-load mode. A 1,782-file codebase now indexes in 1.2s (down from 14.8s). A 28K-file monorepo indexes in 22s (down from 565s). New databases get the final schema in one shot instead of running migrations sequentially.

v3.1 — Edge Deduplication

Incremental syncs could accumulate duplicate edges over time. v3.1 adds a unique index on edges and deduplicates existing databases on upgrade. Also adds concurrent sync prevention via PID-based lockfile, and tokensave doctor now runs VACUUM.

v3.0 — Bundled Grammars & Daemon

All 31 language grammars ship as a single bundled dependency. tokensave install offers to set up the background daemon as an autostart service (launchd/systemd/Windows Service).

</details>

31 Languages

tokensave supports 31 programming languages with deep extraction: functions, classes, methods, fields, imports, call graphs, inheritance chains, docstrings, complexity metrics, and cross-file dependency tracking.

Feature Flag Tiers

Three compilation tiers control which extractors are compiled:

Full (default)  ── 31 languages
Medium          ── 20 languages
Lite            ── 11 languages

All grammars are always present via the bundled crate; the lang-* feature flags control which extractors are included.

See Supported Languages for the full tier breakdown.

Deep Nix Support

The Nix extractor goes beyond basic function/variable extraction:

• Derivation field extraction — mkDerivation, mkShell, buildPythonPackage, buildGoModule, and other builder calls have their attrset arguments extracted as Field nodes. tokensave_search("my-app") finds the pname field, and tokensave_search("buildInputs") shows what each derivation depends on.

• Import path resolution — import ./path.nix now creates a file-level dependency edge. tokensave_callers and tokensave_impact can trace which Nix files depend on which, enabling cross-file change impact analysis.

• Flake output schema awareness — In flake.nix files, standard output attributes (packages, devShells, apps, nixosModules, checks, overlays, lib, formatter) are recognized as semantic Module nodes. tokensave_search("devShells") finds your dev shell definition with its buildInputs as child Field nodes.

Protobuf Schema Graphs

Protobuf files are now first-class citizens with dedicated node kinds:

• message definitions become ProtoMessage nodes with their fields as children
• service definitions become ProtoService nodes
• rpc methods become ProtoRpc nodes
• Nested messages, enums, oneof fields, and import statements are all tracked

This enables queries like "what services depend on this message type?" via tokensave_callers.

Porting Assessment Tools

Two new MCP tools help assess and plan cross-language porting:

• tokensave_port_status — compare symbols between a source and target directory in the same project. Matches by name with cross-language kind compatibility (class ↔ struct, interface ↔ trait). Reports coverage percentage, unmatched symbols grouped by file, and target-only symbols.

• tokensave_port_order — topological sort of source symbols for porting. Returns symbols in dependency-leaf-first order: utility functions and constants at level 0, classes that use them at level 1, services that depend on those classes at level 2, etc. Detects and flags dependency cycles that should be ported together.

Both tools assume source and target live in the same indexed project (e.g., src/python/ and src/rust/ side by side).

SQLite Fallback & Feedback Loop

Agent prompt rules now include two new instructions:

1. SQLite fallback — when MCP tools can't answer a code analysis question, the agent is instructed to query .tokensave/tokensave.db directly via SQL (tables: nodes, edges, files). This handles edge cases and complex structural