tokensave

-

Semantic code search— Ask for symbols by meaning, e.g. "find authentication code", andtokensave_searchreturns matches likelogin,validateToken, andAuthServicewithout grepping files.

Impact analysis— Before editing a function, asktokensave_callersortokensave_impactto trace every caller and callee so you know exactly what breaks.

Context building— Usetokensave_contextto get entry points, related symbols, and code snippets for a task in one call instead of reading multiple files.

Cross-branch comparison— Querytokensave_branch_diffto see symbols added, removed, or changed between two git branches without switching checkouts.

Session memory— Save design decisions withtokensave_record_decisionand recall them later viatokensave_session_recallso the agent doesn't re-explain architecture choices.

Atomic code edits— Apply unique-anchor replacements withtokensave_str_replaceor multi-file edits viatokensave_multi_str_replace, avoiding regex and shell-quoting hazards.

Semantic Code Intelligence for AI Coding Agents

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.

┌──────────────────────────────────────────────────────────────┐ │ AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...) │ │ │ │ "Implement user authentication" │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Sub-agent │ ───── │ Sub-agent │ │ │ └────────┬────────┘ └─────────┬───────┘ │ └───────────┼──────────────────────────┼───────────────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ tokensave MCP Server │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Search │ │ Callers │ │ Context │ │ │ │ "auth" │ │ "login()" │ │ for task │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌───────────────────────┐ │ │ │ libSQL Graph DB │ │ │ │ • Instant lookups │ │ │ │ • FTS5 search │ │ │ └───────────────────────┘ │ └──────────────────────────────────────────────────────────────┘

Without tokensave:Agents usegrep,glob, andReadto scan files -- many API calls, high token usage.

With tokensave:Agents query the graph via MCP tools -- instant results, local processing, fewer tokens.

brew install aovestdipaperino/tap/tokensave

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

cargo install tokensave # full (50+ languages, default) cargo install tokensave --features medium # medium tier cargo install tokensave --no-default-features # lite (smallest binary)

Prebuilt binaries (Linux, Windows, macOS):

Download from thelatest releaseand place the binary in yourPATH.

tokensave install # auto-detects installed agents tokensave install --agent antigravity # Google Antigravity (formerly Windsurf) tokensave install --agent auggie # AugmentCode tokensave install --agent claude # Claude Code tokensave install --agent cline # Cline tokensave install --agent codex # OpenAI Codex CLI tokensave install --agent copilot # GitHub Copilot tokensave install --agent cursor # Cursor tokensave install --agent droid # Factory Droid tokensave install --agent gemini # Gemini CLI tokensave install --agent kilo # Kilo CLI tokensave install --agent kiro # AWS Kiro tokensave install --agent kimi # Moonshot Kimi CLI tokensave install --agent opencode # OpenCode tokensave install --agent pi # Pi (pi.dev) tokensave install --agent plank # Plank (macOS only) tokensave install --agent qwen # Qwen Code tokensave install --agent roo-code # Roo Code tokensave install --agent vibe # Mistral Vibe tokensave install --agent zed # Zed tokensave install --agent grok # Grok Build (xAI) tokensave install --git-hook yes # auto-install the global post-commit and post-checkout hooks (no prompt) tokensave install --git-hook no # skip the post-commit and post-checkout hooks (no prompt)

tokensave install --local --agent claude

{ "mcpServers": { "tokensave": { "command": "/path/to/tokensave", "args": ["serve"] } } }

The hook runstokensave hook-pre-tool-use-- a native Rust command (no bash or jq required). It intercepts Agent, Grep, Glob, and Bash tool calls: Explore agents are blocked outright, symbol-shaped grep/rg/ag invocations (plain identifiers, alternations,\b-wrapped names) are redirected to the matching tokensave MCP tool, and path-shaped discovery (Glob,find -name,fd --extension) over code extensions is redirected totokensave_files. Regex patterns,git grep, piped commands, non-code extensions, search roots outside the index, andfindpredicates that change what the command does (-exec,-delete,-mtime) all pass through untouched; setTOKENSAVE_DISABLE_GREP_HOOK=1to opt out per shell.

Filters are read most-specific-first: an explicittypeis authoritative, then an explicit file glob, then the search path. A documentation search such aspath: "."withglob: "/.md"therefore passes through rather than being treated as a code search on the broad path, while a code-only glob (/.rs) still redirects even under a non-code path. Mixed globs (/.{rs,md}) pass through, since they can return documentation.

Headless / subagent dispatch (claude -p).Child processes dispatched by an orchestrating session inherit its~/.claude/settings.json, including this hook. To let a child run raw searches, setTOKENSAVE_DISABLE_GREP_HOOK=1in the child's environment -- the native binary honors it and passes every path (Grep, Glob, Bash, Agent) through, so there is no need for the blunt--settings '{"hooks": {}}'that stripsallhooks. The guardrail is stateless: it never consults citation history, so it only ever redirects the symbol-shaped searches described above and steers untyped research fan-out; ordinary commands are unaffected whether the session is interactive or headless.

tokensave branch add # track the current branch tokensave branch list # see tracked branches and DB sizes tokensave branch remove <name> # stop tracking a branch tokensave branch removeall # remove all tracked branches except default tokensave branch gc # clean up branches deleted from git

Git hook (on branch checkout).Thepost-checkouthook thattokensave installsets up recognizes abranchcheckout (as opposed to a file checkout) and runstokensave branch addin the background. That command is a no-op when the branch is already tracked or is the default branch, so ordinary switching between known branches costs nothing. The initial checkout of a freshgit cloneand of a newgit worktree addis a branch checkout too, and it can land on a branch that is not the default one (git clone -b feature,git worktree add -b feature); there the hook runstokensave initfirst andtokensave branch addafter it, in that order. A hook written by an earlier version keeps the body it was installed with — the installer never rewrites an existing one — so on those installs a fresh worktree still needsauto_trackbelow, or a manualtokensave branch add.

tokensave gain # current project, last 30 days tokensave gain --all # all projects tokensave gain --history --range 7d tokensave gain --json

tokensave bench # ships with 10 default queries tokensave bench --queries my-queries.toml --json tokensave bench --max-nodes 5

# Required: a writable cache directory for the cloned repos + their indexes. <p align="center"> <a href="https://ai.enzolombardi.net/"></a> </p> # Expect several GB of disk and a long first run (shallow clone + full index of each repo). export TOKENSAVE_BENCH_REPOS_DIR=~/tokensave-bench-cache cargo bench --bench large_repos

cargo bench --bench large_repos -- 'scipy/tokensave_search'

cargo build --release --bin tokensave python3 scripts/mcp_probe/probe.py python3 scripts/mcp_probe/build_matrix.py > matrix.md

Semantic read tools can query an explicitly selected local graph without restarting the MCP server: