Tokensave— agent skill

<p align="center"> <img src="src/resources/logo.png" alt="TokenSave" width="300"> </p>

<h3 align="center">Semantic Code Intelligence for AI Coding Agents</h3>

<p align="center"><strong>Fewer tokens &bull; Fewer tool calls &bull; 100% local</strong></p>

<p align="center"> <a href="https://github.com/aovestdipaperino/tokensave/stargazers"><img src="https://img.shields.io/github/stars/aovestdipaperino/tokensave?logo=github&color=brightgreen" alt="GitHub stars"></a> <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> <a href="https://ai.enzolombardi.net/"><img src="https://img.shields.io/badge/built%20with-AI-D97757?style=flat-square&labelColor=101010&logo=anthropic&logoColor=white" alt="Built with AI — part of Enzo Lombardi's AI portfolio"></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> <!-- Listing badge only. Deliberately not wrapped in a link: the badge's own href points at a monetization page on the marketplace's side (#406). --> <img src="https://getlulu.dev/api/mcps/badge/tokensave" alt="Listed in the Lulu MCP marketplace"> </p>

Beta available: Try the new, improved queries on the beta branch, including optimized search ranking, graph analysis, and indexing cleanup. See the beta changelog for details.

>

Install from source: cargo install --git https://github.com/aovestdipaperino/tokensave.git --branch beta --locked --force

Table of Contents

• Why tokensave?
• Key Features
• Quick Start
• Crash-Resilient Sync
• Multi-Branch Indexing (Optional)
• Cross-Session Memory
• Savings Ledger
• Reproducible Benchmark
• 80+ MCP Tools
• Token Tracking
• Index Freshness
• Self-Upgrade
• Versioning & upgrades
• CLI Reference
• tokensave doctor
• How It Works with Claude Code
• Network Calls & Privacy
• 50+ Languages
• tokensave vs CodeGraph
• Why tokensave Over the Alternatives
• Troubleshooting
• Origin
• Building
• Star History
• Sponsors
• License

Why tokensave?

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.

How It Works

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.

Key Features

Quick Start

1. Install

Choose one installation method:

On Windows with Scoop:

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

You can also download a prebuilt binary and add it to your PATH.

<details> <summary>Installation alternatives and language tiers</summary>

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:

</details>

2. Configure your agent

Run the setup command to auto-detect your installed agents:

tokensave install

To choose an agent, use --agent (for example, codex, claude, or cursor):

tokensave install --agent codex

Supported agents (use the identifier with --agent):

Setup registers the MCP server and the agent's integration. It also offers global Git hooks to keep initialized projects up to date. You can safely run setup again after upgrading.

<details> <summary>Multiple agents, project-local setup, and integration details</summary>

Each agent gets its MCP server registered in the native config format. Claude Code additionally gets a PreToolUse hook (blocks wasteful Explore agents), a UserPromptSubmit hook, a Stop hook, prompt rules in CLAUDE.md, and auto-allowed tool permissions. Pi gets "exposure": "direct" on its MCP entry -- Pi otherwise defaults a server to codemode, which declares none of its tools to the model -- prompt rules in AGENTS.md, and a managed TypeScript extension that supplies the same guardrail, savings reset, and session receipt, because Pi has no shell hooks. Kiro gets global MCP config, tokensave.md steering loaded as a resource, and a tokensave-managed default agent with permissive built-in/tokensave tool approval, delegation guardrail hooks, and post-write sync; user-managed Kiro agents are preserved.

Global OMP installs target the profile reported by bare omp config path, writing <resolved-agent-dir>/mcp.json and <resolved-agent-dir>/rules/tokensave.md. Export OMP_PROFILE or OMP's compatible PI_PROFILE when installing into a named profile; OMP's resolver also honors PI_CONFIG_DIR and PI_CODING_AGENT_DIR. Tokensave trusts that native resolver rather than duplicating OMP's profile logic. Tokensave installs MCP and advisory rules for OMP; it does not install OMP hook enforcement.

All changes are idempotent -- safe to run again after upgrading. After agent setup, you'll be offered global git post-commit and post-checkout hooks. tokensave uninstall removes those hooks along with the agent integrations; pass --keep-git-hooks to leave them, or manage them on their own with tokensave githooks.

#### Install for several agents at once

Repeat --agent to install several agents in a single run. The permission grant, git-hook offer, and global config write each happen once, no matter how many agents you list:

tokensave install --agent claude --agent cursor --agent droid

#### Project-local install

By default tokensave install registers the MCP server in your global agent config (e.g. ~/.claude.json). To register tokensave for just the current project instead, add --local:

tokensave install --local --agent claude
tokensave install --local --agent omp

This writes project-scoped config you can commit and share with your team. For Claude that's ./.mcp.json, ./.claude/settings.json, and ./CLAUDE.md; OMP uses ./.omp/mcp.json and ./.omp/rules/tokensave.md without invoking the OMP CLI. Supported agents: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank, pi (each writes its own project file, e.g. .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json, .omp/mcp.json, .mcp.json for plank, .pi/mcp.json and ./AGENTS.md for pi). Other agents have no project-scoped config and report an error with --local.

Remove a project-local install with tokensave uninstall --local.

To accept or skip the Git hooks without a prompt, add --git-hook yes or --git-hook no. Use tokensave githooks to inspect them, or tokensave githooks off to remove them.

For agent-specific instructions, see Connecting to Your Agent.

</details>

3. Index your project

cd /path/to/your/project
tokensave init

This creates a .tokensave/ directory with the knowledge graph database. Initialization and sync are separate commands: init is a one-time opt-in per project, while sync only updates projects that were already initialized. This prevents the global git hooks from silently creating databases in repos you never intended to index. After init, use tokensave sync to incrementally update -- only changed files are re-indexed.

#### Running from subdirectories

Every command finds the project that owns the current directory by walking up to the nearest .tokensave/, so you can run it from anywhere inside the project:

cd repository
tokensave init                     # creates repository/.tokensave/

cd src/backend/services
tokensave tool search database     # searches the repository's index
tokensave init                     # reports the existing project; exits 0, indexes nothing

cd ../..
tokensave sync                     # syncs the repository's index

The MCP server and the agent hooks resolve the project the same way. Search paths stay relative to the project root (src/backend/db.rs). Note that an MCP server launched from a subdirectory still uses that subdirectory as its default path filter for listing tools.

• Git repositories. If no project exists yet, init from inside a git repository initializes the repository root (or the linked worktree root), not the current directory.
• Repository boundaries. A git repository root is an isolation boundary. Inside a nested, independent repository (a nested clone or a submodule), commands never use an outer repository's index; run tokensave init there to give it its own. A linked worktree nested in its main checkout still borrows the main index, and the borrowed-worktree notice says so.
• Non-git projects. A .tokensave/ in a folder that is not inside a git repository works the same way, including for any repositories inside that folder.
• Explicit roots. tokensave init <path>, --path (-p), and tool --project <path> use the directory you pass, with no discovery.
• Broken installs. A .tokensave/ with a config.json but no database is reported instead of being skipped in favor of an outer project. A config that cannot be parsed is an error that names the file to fix.

<details> <summary><strong>What install writes for Claude Code</strong></summary>

#### MCP server

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

#### PreToolUse hook

The hook runs tokensave 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 to tokensave_files. Regex patterns, git grep, piped commands, non-code extensions, search roots outside the index, and find predicates that change what the command does (-exec, -delete, -mtime) all pass through untouched; set TOKENSAVE_DISABLE_GREP_HOOK=1 to opt out per shell.

Filters are read most-specific-first: an explicit type is authoritative, then an explicit file glob, then the search path. A documentation search such as path: "." with glob: "**/*.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, set TOKENSAVE_DISABLE_GREP_HOOK=1 in 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 strips all hooks. 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.

#### CLAUDE.md rules

Appends instructions to ~/.claude/CLAUDE.md that tell Claude to use tokensave tools before reaching for Explore agents or raw file reads.

</details>

Crash-Resilient Sync

Tree-sitter grammars are compiled C/C++ code. They occasionally hit an internal assertion or otherwise terminate the process by paths that Rust panic handling cannot intercept. As of v4.3.0, every file is parsed inside a short-lived worker subprocess: if a grammar segfaults, calls abort(), or hits a stack overflow, only the worker dies. The pool respawns it, the offending file is logged and skipped, and sync keeps going.

The worker is a hidden extract-worker subcommand authenticated against the parent via a 256-bit per-spawn token, required as both a TOKENSAVE_WORKER_TOKEN env var and as the first 32 bytes received on stdin. Direct invocation by users fails. Worker concurrency follows cpu_usage in .tokensave/config.json: low uses one worker, balanced (default) uses half the available CPUs rounded up, and performance uses all available CPUs. The first tokensave init on a machine benchmarks it once and saves the recommended profile in ~/.tokensave/benchmark.toml, which every project without its own cpu_usage reuses; tokensave config benchmark [--force|--show|--reset] manages that result, and TOKENSAVE_CPU_USAGE or a global cpu_usage in ~/.tokensave/config.toml override it (see the user guide). memory_usage independently limits simultaneous extraction parsers: low uses one, balanced (default) at most two, and performance retains the CPU ceiling. An automatic preflight check can further lower parser concurrency when physical RAM headroom is limited, including in performance mode. This reduces parser memory at a possible throughput cost; total graph memory remains proportional to the project, so it is not a hard RAM cap. TOKENSAVE_WORKERS can lower the subprocess limit further. These limits are not CPU-percentage caps. Restart the MCP server after changing the profile; opt out of subprocess isolation with TOKENSAVE_DISABLE_SUBPROCESS=1.

Edit primitives (tokensave_str_replace, tokensave_insert_at, etc.) still run in-process: they target one file at a time where subprocess overhead would dominate, and an extractor crash there is immediately visible to the agent.

Multi-Branch Indexing (Optional)

tokensave can optionally maintain a separate code graph per git branch. When enabled, switching branches never gives you stale results and never re-indexes files you already parsed on another branch. Multi-branch tracking is opt-in -- without it, tokensave uses a single database for all branches.

How it works

When you track a branch, tokensave copies the nearest ancestor DB and syncs only the files that differ. This means tracking a feature branch off main is nearly instant -- it only parses the files you've changed.

CLI commands

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

Cross-branch MCP tools

Three MCP tools enable cross-branch queries without switching your checkout:

• `tokensave_branch_search` -- search symbols in another branch's graph
• `tokensave_branch_diff` -- compare code graphs between two branches: symbols added, removed, and changed (signature differs). Supports file and kind filters.
• `tokensave_branch_list` -- list tracked branches with DB sizes, parent branch, and sync times

Branch fallback

When the MCP server can't find a database for the current branch, it serves from the nearest ancestor branch's DB and includes a warning in every tool response suggesting you run tokensave branch add.

Automatic branch tracking (v7.3.0)

Once multi-branch mode is bootstrapped (a first manual tokensave branch add created the branch metadata), new branches can be tracked automatically instead of falling back to the ancestor DB. Two independent mechanisms cover this; projects in single-DB mode are never affected, and neither mechanism ever touches the default branch's database.

Git hook (on branch checkout). The post-checkout hook that tokensave install sets up recognizes a branch checkout (as opposed to a file checkout) and runs tokensave branch add in 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 fresh git clone and of a new git worktree add is 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 runs tokensave init first and tokensave branch add after 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 needs auto_track below, or a manual tokensave branch add.

Open-time auto-track (opt-in). When TokenSave::open runs — CLI command or MCP server start — and the active branch is untracked, tokensave can track it on the spot by copying the nearest tracked ancestor's DB and recording it in the branch metadata. This is gated by the auto_track config field (default false) or the TOKENSAVE_AUTO_TRACK environment variable, which overrides the config per-run (any value enables it except 0, false, no, off, or empty). The copy is the same near-instant ancestor-DB copy a manual branch add performs; no sync runs at that moment — the post-commit hook keeps the new branch DB fresh as you commit, or run tokensave sync to refresh immediately. Auto-tracking is strictly best-effort: any failure is reported as a warning and open() proceeds with the usual ancestor fallback, so it can never break a tool call.

Automatic cleanup (opt-in). Set "auto_gc": true in .tokensave/config.json (or TOKENSAVE_AUTO_GC=1 for one run) to collect indexes whose local Git branches have been deleted. Cleanup runs when a project opens and during the MCP server's normal freshness checks. It uses the same collector as tokensave branch gc, preserving the default branch, existing branches, branches used by any Git worktree, and databases served by running TokenSave servers. Failed Git queries or busy sync locks skip automatic cleanup without failing the command. The default is false, so older projects retain their indexes until explicitly cleaned. TOKENSAVE_AUTO_GC=0 overrides an enabled project setting; an explicit tokensave branch gc runs regardless of this setting.

In short: with the hook installed, checking out a new feature branch — including the branch a fresh clone or worktree starts on — transparently gives it its own per-branch graph; with auto_track enabled, even a branch created outside a checkout is picked up the first time tokensave opens the project on it.

See docs/BRANCHING-USER-GUIDE.md for the full guide.

Cross-Session Memory

Three MCP tools persist decisions and code-area context across sessions, stored in the per-project .tokensave/tokensave.db.

Use these so the agent doesn't have to re-explain architecture choices session-to-session.

Savings Ledger

Every MCP call writes an append-only row to ~/.tokensave/global.db (savings_ledger table). Inspect with tokensave gain:

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

Dollar estimates use the existing pricing module (Sonnet input pricing, refreshed daily via LiteLLM).

<p align="center"> <img src="src/resources/gain-screenshot.png" alt="tokensave gain history output" width="700"> </p>

Reproducible Benchmark

tokensave bench runs a fixed query set through tokensave_context and reports retrieval savings vs a full-file baseline (mirrors the CCE methodology):

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

<p align="center"> <img src="src/resources/bench-screenshot.png" alt="tokensave bench output" width="800"> </p>

Measured against this repo (`tokensave` itself) using the shipped generic query set:

Aggregate: 88% mean retrieval savings (142.8k → 5.5k tokens across 10 queries).

The default query set targets patterns present in most application codebases (CLIs, daemons, services). Run it on your own project with tokensave bench to see your numbers, or write a tailored query file (--queries my.toml) for tighter recall.

Criterion bench against large real-world repos

benches/large_repos.rs is a criterion micro-benchmark that exercises the MCP tools end-to-end against four large open-source codebases pinned at constant refs. Each tool is driven by at least 5 queries with arguments (node ids, qualified names, file globs, …) sampled from the indexed graph once per repo, so timings are reproducible across runs.

Repos and pinned refs (defined in benches/repos.rs):

Each repo is shallow-cloned (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) on first use and cached locally; subsequent runs reuse the checkout. Git output is streamed to the terminal so the multi-GB fetch shows real-time progress.

Tools covered (5 queries each). Read tools — search, context, callers, callees, node, by_qualified_name, signature, impact, body, files, complexity, doc_coverage, largest, hotspots, god_class, module_api, derives, dead_code, rank, coupling, circular. Write tools — str_replace, multi_str_replace, insert_at, and (if ast-grep is on PATH) ast_grep_rewrite.

Force-sync on every run. Before any benchmark fires, the harness runs the equivalent of tokensave sync --force on each repo (index_all() regardless of .tokensave/ freshness) so timings always reflect the pinned source.

Write benches and cleanup. Write tools mutate files. To keep the "match must be unique" precondition holding, the harness uses criterion's iter_batched — a small scratch file under <repo>/.tokensave-bench-scratch/ is rewritten with known content before every timed iteration, then the edit tool runs against it. After all benchmarks finish, the harness runs git stash --include-untracked && git stash drop inside every prepared repo so the working tree returns to the pinned ref.

Criterion configuration. The bench overrides criterion's defaults to sample_size = 10 and measurement_time = 30s (vs the stock 100 / 5s), which gives each per-query timing ~30 seconds of measurement — enough that slow tools like tokensave_context on polkadot-sdk produce stable numbers.

Run it:

# Required: a writable cache directory for the cloned repos + their indexes.

<p align="center">
  <a href="https://ai.enzolombardi.net/"><img src="https://img.shields.io/badge/built%20with-AI-D97757?style=flat-square&labelColor=101010&logo=anthropic&logoColor=white" alt="Built with AI — part of Enzo Lombardi's AI portfolio"></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

If TOKENSAVE_BENCH_REPOS_DIR is unset the bench prints a notice and registers zero benchmarks (so cargo bench --all stays cheap on contributors' machines).

Configuration (all optional, via environment):

Filtering benchmarks uses the standard criterion CLI — for example, only the search tool on scipy:

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

Reports (HTML + raw samples) land under target/criterion/.

To change the pinned refs (e.g. to a newer release or a specific SHA), edit REPOS in benches/repos.rs and delete the corresponding $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref marker so the next run re-fetches. If you skip the post-run cleanup (e.g. you Ctrl-C mid-bench), running git stash --include-untracked && git stash drop inside each repo dir restores it manually.

MCP test-matrix probe (scripts/mcp_probe)

scripts/mcp_probe/ is a Python harness that drives tokensave serve over stdio against a configurable set of real repos and exercises every read-only MCP tool with 5 query variants per language, producing a per-tool / per-repo status table. Same harness serves two purposes:

• Regression sweep. New language support, new tool, or a refactor — re-run the matrix and any cell that newly errors, times out, or returns empty results stands out as a 🚩.
• Perf probe. Per-call timings are logged in TSV; the same fixed corpus of repos doubles as a coarse cross-version comparison. The current tokensave_inheritance_depth cycle bug was found by this harness when a single tool on polkadot-sdk timed out at >60 s.

Layout — probe.py is the driver (id-matched JSON-RPC so a slow tool can't poison subsequent calls), isolated.py re-runs a single tool with a fresh server per call (escapes server queueing), build_matrix.py reads the TSV and emits markdown, tools/<lang>.py modules contribute per-language query sets (Rust shipped; add Python/Go/… by dropping a new module), repos.toml lists target repos (override via $TOKENSAVE_PROBE_REPOS).

Quick run:

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

Output cells are ✓ 5/5 (clean), 🐛 e/N (errors), ⏱ N/N (timeouts), ∅ E/N (empty), 🐢 ok/slow (>10 s calls). Any cell carrying an error or timeout earns a 🚩 in the rightmost column. Per-call detail with the first 100 chars of each error landS in the TSV log for follow-up.

Different from the criterion bench above: criterion measures per-iteration latency for a focused tool set on pinned refs and produces statistical reports under target/criterion/; mcp_probe exercises every tool with a broader query set on whatever repos you point it at, optimising for breadth of coverage rather than measurement precision.

80+ MCP Tools

The server exposes more than 80 tools (one fewer when the optional ast-grep binary is not on PATH). Since 7.14.0 only the 11 core tools plus tokensave_more are listed by default; the rest are listed on demand through tokensave_more, stay callable by name, and are all listed with "tools": "full". The tables below group the most commonly used ones by category. Most are read-only, safe to call in parallel, and annotated with readOnlyHint. The edit primitives are scoped to single files and re-index in place; session baseline and memory-recording tools also mutate local .tokensave state and are annotated as non-read-only. The three core tools (tokensave_context, tokensave_search, tokensave_status) are marked anthropic/alwaysLoad so they bypass the client's tool-search round-trip.

Query another initialized project

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

{
  "query": "screenGate",
  "graph_root": "/absolute/path/to/typewhisper"
}

Selected results include canonical root/branch provenance. Node IDs are namespaced to that graph, and the matching selectors must be repeated on follow-up calls. For example, a follow-up to a branch-selected query includes both values:

{
  "node_id": "graph:<fingerprint>:function:<raw-id>",
  "graph_root": "/absolute/path/to/typewhisper",
  "graph_branch": "feature/auth"
}

graph_root must be the exact absolute root of an already initialized project. graph_branch is optional and, when supplied, must name a tracked branch. Selected opens are read-only: they never initialize, sync, migrate, auto-track, or write graph/source data. They also do not contribute to savings accounting. Calls without selectors behave exactly as before.

graph_root is only useful if you know the other project exists, so the server tells you: initialized projects sitting directly beside the served root are named in the MCP instructions, in tokensave_status, and in empty tokensave_search / tokensave_context results — the point at which a session would otherwise conclude a symbol does not exist rather than look next door (#375). Only immediate siblings are offered, at most five, and nothing is opened or indexed on their behalf; querying one still requires an explicit graph_root.

Selectors are intentionally unavailable on tools that write, shell out, or depend on the current checkout: the edit primitives, VCS and branch tools, diagnostics and test execution, dependency and runtime introspection, workflow and session-memory tools, the persistent-cache tool (tokensave_redundancy), and server administration. Those tools reject a selector instead of silently ignoring it.

Discovery

#### Custom source extensions

Map extensions to an enabled extractor in .tokensave/config.json:

"language_aliases": { ".t": "perl", ".ep": "perl" }

This parses legacy Perl tests without renaming them. Keys accept an optional leading dot and match case-insensitively; invalid, conflicting, unknown, or disabled mappings fail sync with a configuration error. Aliases override built-in extension associations and artifact tracking. Use existing project.json entries with language for file/glob overrides, which take priority over aliases. Run tokensave sync after editing mappings (sync -f also works). See the configuration guide.

#### Non-code artifacts

tokensave_files covers more than source. Files whose extension is listed in artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md, .bnd, .bndrun by default) are tracked by path so questions like "where are the .feature files for the login flow?" have a graph answer rather than a blocked find (#323). They are never parsed and contribute no symbols; kind: "artifact" and kind: "code" filter between the two, and analyses that mean "code" exclude them. An extension already handled by a language extractor is ignored in this list, so it cannot be used to stop a language being parsed.

The list also decides what literal search can look inside (#442). A literal (literal: true) search over tokensave_search reads bytes rather than symbols, so it needs no parser -- but it iterates the indexed files, so it can only reach a file the index holds a row for. A tracked .rst document or .tmpl template has neither an extractor nor a default artifact entry, so its matches are missing; add the extension here and run tokensave sync -f and its lines are searched like any other, reported with enclosing: null since there is no symbol context. A literal response that could not reach every tracked file says so in an unscanned block naming the count and the extensions, so a partial answer is never presented as a complete one.

Call Graph & Impact

Code Quality

Code-Health Analytics

Five tools surface structural quality signals from the existing graph. The composite score uses a geometric mean over independent dimensions so no single one can be gamed.

Sessions

Snapshot health metrics at the start of an AI coding session, then diff at the end to see what improved or regressed.

Edit Primitives

Four writer tools that let agents modify files without regex or shell-quoting hazards. Each is single-file, anchored, and triggers an in-place re-index after writing so the graph never goes stale.

Git & Workflow

Type System

Porting

Multi-Branch

#### Branch quality regressions

Compare two existing branch indexes at their Git tips:

tokensave quality-diff --base master --target feature/example
tokensave quality-diff --base master --target HEAD --json --fail-on regression
tokensave quality-diff --base origin/master --target feature/example --cyclomatic 15 --min-increase 5

Each reference must resolve to a commit and name a tracked Tokensave branch. HEAD resolves to the current symbolic branch; detached HEAD requires an explicit branch. Full refs/heads/... and refs/remotes/... names are accepted. Create and sync each index explicitly using the existing tokensave branch add / sync workflow before comparing. Comparison never checks out a branch or rebuilds an index. Missing indexes and empty analysis data are errors, including comparisons of a branch against itself.

The baseline is tip to tip, not the merge base. On diverged branches, a reported difference can originate on either branch; this is not proof that a feature introduced the difference since branching.

Supported diagnostics reuse extracted/indexed data:

Change thresholds with --cyclomatic, --cognitive, --function-lines, and --fan-out (the latter applies to both fan-in and fan-out). Existing above-threshold issues become worsened when their metric increases by at least --min-increase (default 3); smaller increases remain unchanged for gating. Crossing a threshold is new; falling below it or deletion is resolved; a decrease above it is improved. Pre-existing cyclic edges remain unchanged. An existing edge becoming cyclic is new, even if the edge itself predates the comparison. Cycles are reported as edges in cyclic components, not as an enumerated cycle path.

JSON includes deterministic diagnostic order, codes, categories, warning severity, identities, base/target values, locations (1-based for functions), confidence, classification counts and limitations. --fail-on regression exits 1 for new or worsened findings, 0 otherwise. Operational errors and explicitly accepted incomplete results exit 2, independently of --fail-on. Without the flag, complete comparisons exit 0. JSON mode writes a single JSON document to stdout, including on operational errors.

The existing MCP tool accepts the same comparison through:

{"base":"master","head":"feature/example","quality":true,"limit":20,"thresholds":{"cyclomatic":10,"min_increase":3}}

The MCP report shares the CLI schema. Counts cover all findings; details default to 20 (maximum 500), with truncated and total_findings outside the report. Use limit: 0 for counts only. thresholds accepts the option names in the table (cyclomatic, cognitive, function_lines, fan_out), plus min_increase and allow_stale; unknown options are rejected. File/kind filters are rejected in quality mode because cyclicity and coupling require global evidence. No additional MCP tool is exposed. Quality calls skip automatic per-call sync/version reindex; other independent activity in an already-running server retains its normal behavior.

Freshness validation hashes indexed files against Git blobs with the same source decoder as indexing, accepting LF/CRLF line-ending conversion from Git checkout or commit normalization. A mismatched/deleted file or an unindexed source candidate is reported as stale/incomplete. Candidate discovery respects configured exclusion, hidden-file and size rules; branch-specific ignore or manifest policies may explain a candidate, so it is described as uncertain. --allow-stale (MCP thresholds.allow_stale) permits inspection with complete: false and exit 2; it never silently accepts stale evidence as a clean CI result. complete means these index-content checks passed, not that every language or dependency was analyzed. Configured exclusions and unsupported languages remain outside scope; extractor metrics left at zero do not prove low complexity. Indexes must use comparable analysis versions/configuration. Validation does not certify resolver completeness or detect arbitrary manual edits to graph rows.

Locations do not participate in identity. Git-detected file renames normalize function and dependency identities, while qualified symbol names identify functions. Symbol renames, moves not detected by Git, and ambiguous overloads cannot be matched reliably: unmatched findings explicitly carry confidence: "unmatched", and ambiguous same-name/kind/signature metrics are excluded from both snapshots and make the result incomplete. Overloads use their signatures to distinguish otherwise identical qualified names. Review unmatched new/resolved pairs before using them as defects; they can still affect CI. Function-size findings use source span, not executable statement count. Architecture policy, dead-code, test reachability/coverage and module-size regressions are deferred.

Snapshots are read sequentially in database read transactions. Symbol bodies are loaded one indexed file at a time; only compact metric records survive into the comparison. File adjacency and the existing iterative SCC algorithm require O(files + resolved file dependencies) space/time for cycle analysis. No individual cycles are enumerated. Validation uses one Git batch process per snapshot and one decoded blob at a time (64 MiB maximum); it reads indexed content plus Git tree metadata, without scanning the working tree. Total cost also scales with indexed source bytes and symbols; this deliberately trades some I/O for verifiable freshness without commit provenance. No caches, worker pools or background jobs are created by the comparison. Large JSON reports can be substantial; use MCP counts or limited details when token budget matters.

MCP Resources

Four resources are exposed via resources/list and resources/read:

• tokensave://status -- graph statistics as JSON
• tokensave://files -- indexed file tree grouped by directory
• tokensave://overview -- project summary with language distribution and symbol kinds
• tokensave://branches -- tracked branches with DB sizes and parent info

Token Tracking

tokensave measures the tokens it saves on every MCP tool call. Each tool response includes a tokensave_metrics: before=N after=M line showing how many raw-file tokens were avoided by that specific call.

Turning the reporting off. The metrics line, together with a sentence in the MCP instructions, asks the agent to report savings to you — which means the model spends output tokens narrating a saving tokensave made on input tokens. Output tokens are the more expensive kind, so if your agent mentions tokensave on nearly every turn, that narration can offset the win (#356). Set report_savings to false in .tokensave/config.json, or the TOKENSAVE_REPORT_SAVINGS environment variable to override it per-run (any value enables it except 0, false, no, off, or empty). Both the metrics line and the instruction disappear; tokensave install likewise stops writing the reporting rule into agent prompt files. Measurement is untouched either way — every call still lands in the savings ledger, so tokensave gain, tokensave list, status and monitor keep reporting exactly as before. The default stays true.

Only the core tools are listed by default. An MCP client sends the schema of every listed tool on every turn, before any tool is called. The full tokensave surface is about 89 KB of schema, which on a small-context model can be more than half of the window (#576). So tools/list sends only the core tools: context, search, status, read, body, files, callers, callees, impact, str_replace and multi_str_replace (about 17 KB with tokensave_more). The initialize instructions name these tools and the areas tokensave_more can list, so a client that defers tool schemas still knows the rest exist. The setting selects what the server lists, not what it can run: a tool that is not listed still answers a call by name, so agent permission lists and hooks keep working. To list every tool, set "tools": "full" in .tokensave/config.json, or TOKENSAVE_TOOLS=full in the environment of the MCP server; the environment variable wins over the file. A "tools": "full" written by 7.13.0, which wrote it into every config it saved, is read as the old default; set it again after upgrading to keep the full list.

With the core toolset the server also lists tokensave_more. A call with an area (analysis, edit, git, memory, navigate or all) lists the tools of that area for the rest of the session, and the server sends notifications/tools/list_changed so the client fetches the list again. A session pays only for the areas it uses: the git area adds about 6 KB. A client that ignores list_changed keeps the core list. tokensave install grants tokensave_more along with every other tool, so it does not prompt; an install from before this release prompts once, until tokensave reinstall or the upgrade resync refreshes the permission list.

Cost observability

tokensave cost                     # 7-day cost summary (default)
tokensave cost today               # today only
tokensave cost --by-model          # breakdown by Claude model
tokensave cost --by-task           # breakdown by task category (coding, debugging, exploration, ...)
tokensave cost --export json       # JSON export to stdout
tokensave cost --export csv        # CSV export to stdout

Parses Claude Code session transcripts (~/.claude/projects/**/*.jsonl) and prices each API turn with model pricing, reads Pi sessions (~/.pi/agent/sessions/**/*.jsonl) using the cost Pi already reports per message, and ingests Factory Droid session settings in credits. Every turn is classified into one of 13 task categories and stored in ~/.tokensave/global.db for fast aggregate queries. Pricing is refreshed from LiteLLM every 24 hours and falls back to an embedded table when offline.

The tokensave status header includes a cost row showing today's spend, 7-day total, and efficiency ratio (tokens saved / total tokens). The tokensave monitor TUI shows a live cost panel alongside the savings feed. At the end of each Claude Code session, the hook_stop handler prints a one-line receipt to the terminal; in Pi, the installed extension does the same through its agent_settled handler.

Task classification categories: Coding, Debugging, Feature Dev, Refactoring, Testing, Exploration, Planning, Delegation, Git Ops, Build/Deploy, Brainstorming, Conversation, General. Classification is deterministic (pattern matching on tool names and Bash commands), requires no LLM calls, and is adapted from AgentSeal/codeburn.

Live monitor

tokensave monitor

A global TUI that shows MCP tool calls from all projects in real time, via a shared memory-mapped ring buffer at ~/.tokensave/monitor.mmap. Each entry shows the project name, tool name, and token delta. A cost panel at the top shows today's spend, savings, efficiency, and top model (refreshed every 30 seconds).

<p align="center"> <img src="src/resources/monitor-screenshot.png" alt="tokensave monitor TUI" width="800"> </p>

Memory diagnostics

tokensave memory [--clean]

A machine-wide memory report for every tokensave process (MCP servers, syncs, index runs), via a shared memory-mapped table at ~/.tokensave/memory.mmap. Each instance self-samples its RSS best-effort at startup, per MCP tool call, and around the sync/resolution phases, so the report shows current and peak RSS with the phase that produced the peak — the data needed to attribute high memory use (see #253). Rows are flagged alive, dead (an OOM-killed process leaves its peak/phase behind as a forensic record), or orphan (still running but reparented to init). --clean purges dead slots.

PEAK PHASE names the highest sample, so it is only as precise as the sampling. Incremental sync records, in order: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. A full index records index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Each is recorded after the work it names. They used to be recorded before it, so every sample reported the previous step's RSS under the next step's label — which attributed 73 MiB to the node load that in fact belonged to loading the unresolved references, a step with no sample at all, and pointed a memory investigation at the wrong subsystem for months (#409). If you add a phase, sample after the work, not before it, and add one for any step large enough to hold the peak.

Session and lifetime counters

tokensave current-counter          # show per-project session counter
tokensave reset-counter            # reset the session counter
tokensave status                   # shows project + global lifetime totals + cost

tokensave status renders the project index stats, language breakdown, cost row (today / 7d / efficiency), and project + worldwide lifetime totals:

<p align="center"> <img src="src/resources/status-screenshot.png" alt="tokensave status output" width="640"> </p>

Worldwide counter

All tokensave users contribute to an anonymous aggregate counter. tokensave status shows both your project total and the worldwide total. The upload sends only a single number (e.g. 4823) with no identifying information. Opt out with tokensave disable-upload-counter.

Index Freshness

tokensave keeps the graph up to date without a background daemon or an OS-level file watcher.

On-demand staleness check. Every MCP tool call checks whether any indexed files have been modified since the last sync. If stale files are found, they are re-extracted before the tool response is returned. A 30-second cooldown prevents back-to-back calls from re-walking the tree on every keystroke.

Catch-up sync on connect. When the MCP server starts, it immediately runs a non-blocking catch-up sync that picks up any changes made while no agent was attached — a git pull, an IDE edit, a build step — so the very first tool call of a session sees a fresh index.

Multi-agent work and git worktrees. When multiple agents work on the same project concurrently, the strong assumption is that each agent operates in its own git worktree. Worktrees are independent filesystem checkouts of the same repository: agent A and agent B each have their own copy of every file, so they never overwrite each other's in-flight edits. tokensave automatically detects when a query comes from a worktree nested inside the main checkout and serves results from the correct branch graph. Changes accumulate independently and are eventually reconciled via git merge or rebase — the same process used for any other parallel development. This design avoids the complexity and failure modes of cross-agent locking over a shared mutable directory.

CLI-only workflows. If you run tokensave commands without an attached agent (no MCP server), the staleness check is not running between commands. Install git hooks to keep the index fresh automatically after every commit or clone:

cp scripts/post-commit scripts/post-checkout .git/hooks/
chmod +x .git/hooks/post-commit .git/hooks/post-checkout

Upgrading from 5.x

The standalone tokensave daemon command and its launchd/systemd/Windows Service autostart were removed in 6.0.0. The embedded OS-level file watcher that replaced the daemon was itself removed in 6.1.1 (it caused runaway CPU and memory on large monorepos with deep node_modules or target trees). The on-demand staleness model above is the current design.

If you still have a daemon autostart from 5.x, remove it:

• macOS: launchctl unload ~/Library/LaunchAgents/com.tokensave.daemon.plist && rm ~/Library/LaunchAgents/com.tokensave.daemon.plist
• Linux: systemctl --user disable --now tokensave-daemon && rm ~/.config/systemd/user/tokensave-daemon.service
• Windows: sc.exe delete tokensave-daemon (from an elevated terminal)

If you don't recall the exact name: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Self-Upgrade

tokensave upgrade                  # upgrade to latest in current channel
tokensave channel                  # show current channel (stable/beta)
tokensave channel beta             # switch to beta channel
tokensave channel stable           # switch back to stable

tokensave upgrade downloads the correct platform binary from GitHub releases and replaces the running binary in place. Supports stable and beta channels independently.

Versioning & upgrades

tokensave version numbers look like SemVer but do not follow it: the component that changes encodes the maintenance the update requires, which tokensave performs automatically on the next launch — you never run a reinstall or reindex by hand.

Global reinstall. On the first run of a new minor or major build, tokensave silently re-runs install for each agent it has registered, so the agent config always points at the current binary and exposes the current tool set. Patch bumps skip this — the running version marker is simply advanced.

The reinstall is genuinely silent: the per-agent setup output you see from an explicit tokensave install is suppressed here, so it never appears in front of an ordinary tokensave init or tokensave sync. If an agent's config can't be refreshed — the app isn't installed, or its config lives somewhere read-only — you get one line naming the agents that failed:

warning: could not refresh tokensave config for: copilot.
  Run tokensave install to see the error.

Run tokensave install to see the underlying error. The version markers advance either way, so a config path that can never be written is reported once per upgrade rather than retried on every subsequent command.

Per-project forced reindex (major only). A major bump means project indexes must be rebuilt. tokensave does this lazily and per project: on the first MCP tool call in a project after a major upgrade, it spawns a background full reindex (equivalent to tokensave sync --force) that never blocks the tool response.

Brew / cargo fallback. External upgrades that replace the binary outside of tokensave upgrade — brew upgrade tokensave or cargo install tokensave — are detected the same way: if the running version is newer than the last version that performed an install, the reinstall runs on the next launch just as it would after a self-upgrade.

See TOKENSAVE-VERSIONING.md for why tokensave diverges from SemVer (encoding maintenance in the version is what makes zero-touch upgrades possible), the marker mechanics, the independent database schema version, and the maintainer rules for cutting releases.

CLI Reference

tokensave init [path]              # Initialize a new project (full index); without a path, the git root