tokensave

Semantische Code-Intelligenz für KI-Coding-Agenten

Weniger Tokens • Weniger Tool-Aufrufe • 100% lokal

Warum tokensave?

KI-Coding-Agenten verschwenden Tokens beim Durchsuchen von Codebasen. Jeder grep-, glob- und Datei-Lesevorgang kostet Geld. Bei komplexen Aufgaben erzeugen Agenten mehrere Explore-Unteragenten, die Hunderte von Dateien scannen, nur um Kontext aufzubauen.

tokensave gibt Agenten einen vorindizierten semantischen Wissensgraphen. Anstatt Dateien zu scannen, fragt der Agent den Graphen ab und erhält sofort strukturierte Antworten – die richtigen Symbole, ihre Beziehungen und den Quellcode, in einem Aufruf.

So funktioniert's

┌──────────────────────────────────────────────────────────────┐
│  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       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Ohne tokensave: Agenten verwenden grep, glob und Read, um Dateien zu scannen – viele API-Aufrufe, hoher Token-Verbrauch.

Mit tokensave: Agenten fragen den Graphen über MCP-Tools ab – sofortige Ergebnisse, lokale Verarbeitung, weniger Tokens.

Hauptfunktionen

Schnellstart

1. Installation

Homebrew (macOS):

brew install aovestdipaperino/tap/tokensave

Scoop (Windows):

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

Cargo (beliebige Plattform):

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

Vorkompilierte Binärdateien (Linux, Windows, macOS):

Laden Sie sie von der neuesten Version herunter und legen Sie die Binärdatei in Ihrem PATH ab.

2. Konfigurieren Sie Ihren Agenten

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 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)

Jeder Agent erhält seinen MCP-Server im nativen Konfigurationsformat registriert. Claude Code erhält zusätzlich einen PreToolUse-Hook (blockiert verschwenderische Explore-Agenten), einen UserPromptSubmit-Hook, einen Stop-Hook, Prompt-Regeln in CLAUDE.md und automatisch erlaubte Tool-Berechtigungen. Kiro erhält eine globale MCP-Konfiguration, tokensave.md-Steuerung als Ressource geladen und einen von tokensave verwalteten Standardagenten mit freizügiger Genehmigung für integrierte/tokensave-Tools, Delegierungs-Leitplanken-Hooks und Post-Write-Sync; benutzerverwaltete Kiro-Agenten bleiben erhalten.

Alle Änderungen sind idempotent – sicher, um sie nach einem Upgrade erneut auszuführen. Nach der Agenten-Einrichtung werden Ihnen globale Git-Post-Commit- und Post-Checkout-Hooks angeboten.

Projektlokale Installation

Standardmäßig registriert tokensave install den MCP-Server in Ihrer globalen Agentenkonfiguration (z. B. ~/.claude.json). Um tokensave stattdessen nur für das aktuelle Projekt zu registrieren, fügen Sie --local hinzu:

tokensave install --local --agent claude

Dies schreibt eine projektbezogene Konfiguration, die Sie committen und mit Ihrem Team teilen können. Für Claude ist das ./.mcp.json, ./.claude/settings.json und ./CLAUDE.md. Unterstützte Agenten: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie (jeder schreibt seine eigene Projektdatei, z. B. .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json). Andere Agenten haben keine projektbezogene Konfiguration und melden einen Fehler mit --local.

Entfernen Sie eine projektlokale Installation mit tokensave uninstall --local.

3. Indizieren Sie Ihr Projekt

cd /path/to/your/project
tokensave init

Dies erstellt ein .tokensave/-Verzeichnis mit der Wissensgraph-Datenbank. Initialisierung und Synchronisation sind separate Befehle: init ist ein einmaliges Opt-in pro Projekt, während sync nur Projekte aktualisiert, die bereits initialisiert wurden. Dies verhindert, dass die globalen Git-Hooks stillschweigend Datenbanken in Repos erstellen, die Sie nie indizieren wollten. Verwenden Sie nach init den Befehl tokensave sync für inkrementelle Aktualisierungen – nur geänderte Dateien werden neu indiziert.

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

Absturzresistente Synchronisation

Tree-Sitter-Grammatiken sind kompilierter C/C++-Code. Sie lösen gelegentlich eine interne Assertion aus oder beenden den Prozess auf andere Weise auf Pfaden, die von der Rust-Panic-Behandlung nicht abgefangen werden können. Ab v4.3.0 wird jede Datei in einem kurzlebigen Worker-Subprozess geparst: Wenn eine Grammatik einen Segfault verursacht, abort() aufruft oder einen Stack-Overflow verursacht, stirbt nur der Worker. Der Pool startet ihn neu, die fehlerhafte Datei wird protokolliert und übersprungen, und sync läuft weiter.

Der Worker ist ein versteckter extract-worker-Unterbefehl, der gegenüber dem Elternprozess über ein 256-Bit-Token pro Start authentifiziert wird, das sowohl als TOKENSAVE_WORKER_TOKEN-Umgebungsvariable als auch als die ersten 32 auf stdin empfangenen Bytes erforderlich ist. Ein direkter Aufruf durch Benutzer schlägt fehl. Standardmäßig werden available_parallelism() Worker verwendet; mit TOKENSAVE_DISABLE_SUBPROCESS=1 deaktivieren.

Bearbeitungsprimitive (tokensave_str_replace, tokensave_insert_at usw.) werden weiterhin im Prozess ausgeführt: Sie zielen jeweils auf eine Datei ab, bei der der Subprozess-Overhead dominieren würde, und ein Extraktor-Absturz ist dort für den Agenten sofort sichtbar.

Multi-Branch-Indizierung (Optional)

tokensave kann optional einen separaten Code-Graphen pro Git-Branch verwalten. Wenn diese Option aktiviert ist, erhalten Sie beim Wechseln von Branches niemals veraltete Ergebnisse und müssen Dateien, die Sie bereits in einem anderen Branch geparst haben, nicht erneut indizieren. Die Multi-Branch-Verfolgung ist ein Opt-in – ohne sie verwendet tokensave eine einzige Datenbank für alle Branches.

So funktioniert's

Wenn Sie einen Branch verfolgen, kopiert tokensave die nächstgelegene Vorgänger-Datenbank und synchronisiert nur die abweichenden Dateien. Das bedeutet, dass die Verfolgung eines Feature-Branches von main nahezu sofort erfolgt – es werden nur die von Ihnen geänderten Dateien geparst.

CLI-Befehle

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

Branch-übergreifende MCP-Tools

Drei MCP-Tools ermöglichen branch-übergreifende Abfragen, ohne den Checkout zu wechseln:

• tokensave_branch_search – Symbole im Graphen eines anderen Branches suchen
• tokensave_branch_diff – Code-Graphen zwischen zwei Branches vergleichen: hinzugefügte, entfernte und geänderte Symbole (Signatur abweichend). Unterstützt Datei- und Art-Filter.
• tokensave_branch_list – Verfolgte Branches mit DB-Größen, Eltern-Branch und Synchronisationszeiten auflisten

Branch-Fallback

Wenn der MCP-Server keine Datenbank für den aktuellen Branch finden kann, bedient er die Anfrage aus der Datenbank des nächstgelegenen Vorgänger-Branches und fügt jeder Tool-Antwort eine Warnung hinzu, die vorschlägt, tokensave branch add auszuführen.

Automatische Branch-Verfolgung (v7.3.0)

Sobald der Multi-Branch-Modus gebootstrappt ist (ein erstes manuelles tokensave branch add hat die Branch-Metadaten erstellt), können neue Branches automatisch verfolgt werden, anstatt auf die Vorgänger-Datenbank zurückzufallen. Zwei unabhängige Mechanismen decken dies ab; Projekte im Einzel-DB-Modus sind niemals betroffen, und keiner der Mechanismen berührt jemals die Datenbank des Standard-Branches.

Git-Hook (beim Branch-Checkout). Der post-checkout-Hook, den tokensave install einrichtet, erkennt einen Branch-Checkout (im Gegensatz zu einem Datei-Checkout) und führt tokensave branch add im Hintergrund aus. Dieser Befehl ist ein No-Op, wenn der Branch bereits verfolgt wird oder der Standard-Branch ist, sodass das gewöhnliche Wechseln zwischen bekannten Branches nichts kostet.

Automatische Verfolgung beim Öffnen (Opt-in). Wenn TokenSave::open ausgeführt wird – CLI-Befehl oder MCP-Server-Start – und der aktive Branch nicht verfolgt wird, kann tokensave ihn sofort verfolgen, indem die Datenbank des nächstgelegenen verfolgten Vorgängers kopiert und in den Branch-Metadaten aufgezeichnet wird. Dies wird durch das Konfigurationsfeld auto_track (Standard false) oder die Umgebungsvariable TOKENSAVE_AUTO_TRACK gesteuert, die die Konfiguration pro Ausführung überschreibt (jeder Wert aktiviert sie, außer 0, false, no, off oder leer). Die Kopie ist dieselbe nahezu sofortige Vorgänger-DB-Kopie, die ein manuelles branch add durchführt; zu diesem Zeitpunkt wird keine Synchronisation ausgeführt – der post-commit-Hook hält die neue Branch-DB bei Commits aktuell, oder führen Sie tokensave sync aus, um sie sofort zu aktualisieren. Die automatische Verfolgung erfolgt strikt nach bestem Bemühen: Jeder Fehler wird als Warnung gemeldet und open() fährt mit dem üblichen Vorgänger-Fallback fort, sodass ein Tool-Aufruf niemals unterbrochen werden kann.

Kurz gesagt: Wenn der Hook installiert ist, erhält ein neuer Feature-Branch beim Auschecken transparent seinen eigenen Branch-Graphen; mit aktiviertem auto_track wird sogar ein Branch, der außerhalb eines Checkouts erstellt wurde (z. B. in einem neuen Worktree), beim ersten Öffnen des Projekts durch tokensave darauf erfasst.

Siehe docs/BRANCHING-USER-GUIDE.md für die vollständige Anleitung.

Sitzungsübergreifender Speicher

Drei MCP-Tools speichern Entscheidungen und Code-Bereichs-Kontext sitzungsübergreifend, abgelegt im projektspezifischen .tokensave/tokensave.db.

Nutzen Sie diese, damit der Agent Architekturentscheidungen nicht von Sitzung zu Sitzung erneut erklären muss.

Einsparungs-Ledger

Jeder MCP-Aufruf schreibt eine reine Anfüge-Zeile in ~/.tokensave/global.db (savings_ledger-Tabelle). Einsicht mit tokensave gain:

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

Dollar-Schätzungen verwenden das bestehende Preismodul (Sonnet-Eingabepreise, täglich aktualisiert via LiteLLM).

Reproduzierbarer Benchmark

tokensave bench führt einen festen Abfragesatz durch tokensave_context aus und berichtet Abrufeinsparungen im Vergleich zu einer Voll-Datei-Basislinie (spiegelt die CCE-Methodik wider):

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

Gemessen an diesem Repository (tokensave selbst) unter Verwendung des mitgelieferten generischen Abfragesatzes:

Aggregat: 88 % durchschnittliche Abrufeinsparung (142,8k → 5,5k Tokens über 10 Abfragen).

Der Standard-Abfragesatz zielt auf Muster ab, die in den meisten Anwendungscodebasen vorhanden sind (CLIs, Daemons, Dienste). Führen Sie ihn in Ihrem eigenen Projekt mit tokensave bench aus, um Ihre Zahlen zu sehen, oder schreiben Sie eine maßgeschneiderte Abfragedatei (--queries my.toml) für eine präzisere Trefferquote.

Criterion-Benchmark gegen große reale Repositories

benches/large_repos.rs ist ein criterion-Mikro-Benchmark, der die MCP-Tools Ende-zu-Ende gegen vier große Open-Source-Codebasen mit festen Referenzen testet. Jedes Tool wird von mindestens 5 Abfragen mit Argumenten (Knoten-IDs, qualifizierte Namen, Datei-Globs, …) angesteuert, die einmal pro Repository aus dem indizierten Graphen entnommen werden, sodass die Zeitmessungen über Läufe hinweg reproduzierbar sind.

Repositories und feste Referenzen (definiert in benches/repos.rs):

Jedes Repository wird bei der ersten Verwendung flach geklont (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) und lokal zwischengespeichert; nachfolgende Läufe verwenden den Checkout erneut. Die Git-Ausgabe wird an das Terminal gestreamt, sodass der Multi-GB-Abruf den Fortschritt in Echtzeit anzeigt.

Abgedeckte Tools (je 5 Abfragen). Lese-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. Schreib-Tools — str_replace, multi_str_replace, insert_at und (wenn ast-grep auf PATH steht) ast_grep_rewrite.

Force-Sync bei jedem Lauf. Bevor ein Benchmark ausgelöst wird, führt das Test-Harness das Äquivalent von tokensave sync --force für jedes Repository aus (index_all() unabhängig von der .tokensave/-Aktualität), sodass die Zeitmessungen immer die festgelegte Quelle widerspiegeln.

Schreib-Benchmarks und Bereinigung. Schreib-Tools verändern Dateien. Um die Vorbedingung "Übereinstimmung muss eindeutig sein" aufrechtzuerhalten, verwendet das Harness criterions iter_batched — eine kleine Scratch-Datei unter <repo>/.tokensave-bench-scratch/ wird vor jeder zeitgesteuerten Iteration mit bekanntem Inhalt neu geschrieben, dann wird das Bearbeitungstool darauf ausgeführt. Nach Abschluss aller Benchmarks führt das Harness git stash --include-untracked && git stash drop in jedem vorbereiteten Repository aus, sodass der Arbeitsbaum zur festgelegten Referenz zurückkehrt.

Criterion-Konfiguration. Der Benchmark überschreibt die Standardwerte von criterion auf sample_size = 10 und measurement_time = 30s (im Vergleich zu den Standardwerten 100 / 5s), was jeder Abfragezeitmessung etwa 30 Sekunden Messzeit gibt — genug, damit langsame Tools wie tokensave_context auf polkadot-sdk stabile Zahlen liefern.

Ausführen:

# Required: a writable cache directory for the cloned repos + their indexes.
# 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

Wenn TOKENSAVE_BENCH_REPOS_DIR nicht gesetzt ist, gibt der Benchmark einen Hinweis aus und registriert null Benchmarks (damit cargo bench --all auf den Rechnern von Mitwirkenden günstig bleibt).

Konfiguration (alles optional, über Umgebungsvariablen):

Filtern von Benchmarks verwendet die standardmäßige criterion-CLI — zum Beispiel nur das search-Tool auf scipy:

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

Berichte (HTML + Rohdaten) landen unter target/criterion/.

Um die festgelegten Referenzen zu ändern (z. B. auf eine neuere Version oder einen bestimmten SHA), bearbeiten Sie REPOS in benches/repos.rs und löschen Sie die entsprechende $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref-Markierung, damit der nächste Lauf sie erneut abruft. Wenn Sie die Bereinigung nach dem Lauf überspringen (z. B. wenn Sie Ctrl-C mitten im Benchmark abbrechen), stellt die Ausführung von git stash --include-untracked && git stash drop in jedem Repo-Verzeichnis es manuell wieder her.

MCP-Testmatrix-Sonde (scripts/mcp_probe)

scripts/mcp_probe/ ist ein Python-Harness, das tokensave serve über stdio gegen einen konfigurierbaren Satz echter Repositories ansteuert und jedes schreibgeschützte MCP-Tool mit 5 Abfragevarianten pro Sprache testet, wodurch eine Status-Tabelle pro Tool / pro Repository erstellt wird. Dasselbe Harness dient zwei Zwecken:

• Regressionsdurchlauf. Neue Sprachunterstützung, neues Tool oder ein Refactoring — führen Sie die Matrix erneut aus, und jede Zelle, die neu Fehler verursacht, eine Zeitüberschreitung hat oder leere Ergebnisse zurückgibt, fällt als 🚩 auf.
• Performance-Sonde. Zeitmessungen pro Aufruf werden in TSV protokolliert; derselbe feste Korpus von Repositories dient gleichzeitig als grober versionsübergreifender Vergleich. Der aktuelle tokensave_inheritance_depth-Zyklusfehler wurde von diesem Harness gefunden, als ein einzelnes Tool auf polkadot-sdk bei >60 s eine Zeitüberschreitung hatte.

Layout — probe.py ist der Treiber (ID-abgeglichenes JSON-RPC, sodass ein langsames Tool nachfolgende Aufrufe nicht beeinträchtigen kann), isolated.py führt ein einzelnes Tool mit einem frischen Server pro Aufruf erneut aus (entgeht Server-Warteschlangen), build_matrix.py liest die TSV und gibt Markdown aus, tools/<lang>.py-Module steuern sprachspezifische Abfragesätze bei (Rust wird mitgeliefert; fügen Sie Python/Go/… hinzu, indem Sie ein neues Modul ablegen), repos.toml listet Ziel-Repositories auf (überschreibbar über $TOKENSAVE_PROBE_REPOS).

Schnellstart:

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

Ausgabezellen sind ✓ 5/5 (sauber), 🐛 e/N (Fehler), ⏱ N/N (Zeitüberschreitungen), ∅ E/N (leer), 🐢 ok/slow (>10 s Aufrufe). Jede Zelle, die einen Fehler oder eine Zeitüberschreitung enthält, erhält ein 🚩 in der Spalte ganz rechts. Details pro Aufruf mit den ersten 100 Zeichen jedes Fehlers landen zur Nachverfolgung im TSV-Protokoll.

Anders als der obige criterion-Benchmark: criterion misst die Latenz pro Iteration für einen fokussierten Tool-Satz auf festgelegten Referenzen und erstellt statistische Berichte unter target/criterion/; mcp_probe testet jedes Tool mit einem breiteren Abfragesatz auf den Repositories, auf die Sie es verweisen, und optimiert auf Abdeckungsbreite statt auf Messpräzision.

80+ MCP-Tools

Der Server stellt mehr als 80 Tools bereit (eines weniger, wenn die optionale ast-grep-Binärdatei nicht in PATH ist); die folgenden Tabellen gruppieren die am häufigsten verwendeten nach Kategorie. Die meisten sind schreibgeschützt, sicher parallel aufrufbar und mit readOnlyHint annotiert. Die Bearbeitungsprimitive sind auf einzelne Dateien beschränkt und indizieren direkt neu; Sitzungsbasislinien- und Speicheraufzeichnungs-Tools verändern ebenfalls den lokalen .tokensave-Zustand und sind als nicht schreibgeschützt annotiert. Die drei Kern-Tools (tokensave_context, tokensave_search, tokensave_status) sind mit anthropic/alwaysLoad markiert, sodass sie den Tool-Such-Roundtrip des Clients umgehen.

Erkennung

Aufrufgraph & Auswirkungen

Codequalität

Code-Zustandsanalyse

Fünf Tools zeigen strukturelle Qualitätssignale aus dem vorhandenen Graphen an. Die zusammengesetzte Bewertung verwendet ein geometrisches Mittel über unabhängige Dimensionen, sodass keine einzelne manipuliert werden kann.

Sitzungen

Erfassen Sie Zustandsmetriken zu Beginn einer KI-Codierungssitzung und vergleichen Sie sie am Ende, um zu sehen, was sich verbessert oder verschlechtert hat.

Bearbeitungsprimitive

Vier Schreibtools, mit denen Agenten Dateien ohne Regex- oder Shell-Quoting-Risiken ändern können. Jedes ist auf eine einzelne Datei beschränkt, verankert und löst nach dem Schreiben eine Neuindizierung aus, sodass der Graph nie veraltet.

Git & Workflow

Typsystem

Portierung

Multi-Branch

MCP-Ressourcen

Vier Ressourcen werden über resources/list und resources/read bereitgestellt:

• tokensave://status – Graphstatistiken als JSON
• tokensave://files – Indizierter Dateibaum, gruppiert nach Verzeichnis
• tokensave://overview – Projektzusammenfassung mit Sprachverteilung und Symbolarten
• tokensave://branches – Verfolgte Branches mit DB-Größen und übergeordneten Informationen

Token-Tracking

tokensave misst die Token, die es bei jedem MCP-Toolaufruf einspart. Jede Tool-Antwort enthält eine tokensave_metrics: before=N after=M-Zeile, die anzeigt, wie viele Rohdatei-Token durch diesen spezifischen Aufruf vermieden wurden.

Kostenbeobachtbarkeit

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

Parst Claude Code-Sitzungstranskripte (~/.claude/projects/**/*.jsonl), klassifiziert jede API-Runde in eine von 13 Aufgabenkategorien, berechnet die Dollarkosten anhand der Modellpreise und speichert die Ergebnisse in ~/.tokensave/global.db für schnelle aggregierte Abfragen. Die Preisgestaltung wird alle 24 Stunden von LiteLLM aktualisiert und greift offline auf eine eingebettete Tabelle zurück.

Der tokensave status-Header enthält eine Kostenzeile, die die heutigen Ausgaben, die 7-Tage-Summe und das Effizienzverhältnis (eingesparte Token / Gesamt-Token) anzeigt. Die tokensave monitor TUI zeigt ein Live-Kostenpanel neben dem Einsparungs-Feed. Am Ende jeder Claude Code-Sitzung gibt der hook_stop-Handler eine einzeilige Quittung im Terminal aus.

Aufgabenklassifizierungskategorien: Programmierung, Debugging, Feature-Entwicklung, Refactoring, Testen, Exploration, Planung, Delegation, Git-Operationen, Build/Deploy, Brainstorming, Konversation, Allgemein. Die Klassifizierung ist deterministisch (Musterabgleich auf Toolnamen und Bash-Befehle), erfordert keine LLM-Aufrufe und ist von AgentSeal/codeburn adaptiert.

Live-Monitor

tokensave monitor

Eine globale TUI, die MCP-Toolaufrufe aus allen Projekten in Echtzeit über einen gemeinsam genutzten, speicherabgebildeten Ringpuffer unter ~/.tokensave/monitor.mmap anzeigt. Jeder Eintrag zeigt den Projektnamen, den Toolnamen und das Token-Delta. Ein Kostenpanel oben zeigt die heutigen Ausgaben, Einsparungen, Effizienz und das Top-Modell (alle 30 Sekunden aktualisiert).

Sitzungs- und Lebenszeitzähler

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 stellt die Projektindex-Statistiken, Sprachaufschlüsselung, Kostenzeile (heute / 7 Tage / Effizienz) sowie Projekt- und weltweite Lebenszeitsummen dar:

Weltweiter Zähler

Alle tokensave-Benutzer tragen zu einem anonymen Gesamtzähler bei. tokensave status zeigt sowohl Ihre Projektsumme als auch die weltweite Summe an. Der Upload sendet nur eine einzelne Zahl (z. B. 4823) ohne identifizierende Informationen. Abmeldung mit tokensave disable-upload-counter.

Index-Aktualität

tokensave hält den Graphen ohne Hintergrunddienst oder Dateisystem-Überwachung auf Betriebssystemebene aktuell.

On-Demand-Veraltungsprüfung. Jeder MCP-Toolaufruf prüft, ob indizierte Dateien seit der letzten Synchronisierung geändert wurden. Wenn veraltete Dateien gefunden werden, werden sie vor der Rückgabe der Tool-Antwort erneut extrahiert. Eine 30-Sekunden-Abkühlphase verhindert, dass aufeinanderfolgende Aufrufe den Baum bei jedem Tastendruck erneut durchlaufen.

Nachhol-Synchronisierung bei Verbindung. Wenn der MCP-Server startet, führt er sofort eine nicht blockierende Nachhol-Synchronisierung durch, die alle Änderungen erfasst, die vorgenommen wurden, während kein Agent verbunden war – ein git pull, eine IDE-Bearbeitung, ein Build-Schritt – sodass der allererste Toolaufruf einer Sitzung einen aktuellen Index sieht.

Multi-Agent-Arbeit und Git-Worktrees. Wenn mehrere Agenten gleichzeitig am selben Projekt arbeiten, gilt die starke Annahme, dass jeder Agent in seinem eigenen Git-Worktree arbeitet. Worktrees sind unabhängige Dateisystem-Checkouts desselben Repositorys: Agent A und Agent B haben jeweils ihre eigene Kopie jeder Datei, sodass sie sich nie gegenseitig die laufenden Bearbeitungen überschreiben. tokensave erkennt automatisch, wenn eine Abfrage von einem Worktree kommt, der im Haupt-Checkout verschachtelt ist, und liefert Ergebnisse aus dem korrekten Branch-Graphen. Änderungen sammeln sich unabhängig voneinander an und werden schließlich über Git-Merge oder -Rebase abgeglichen – derselbe Prozess, der für jede andere parallele Entwicklung verwendet wird. Dieses Design vermeidet die Komplexität und Fehleranfälligkeit von agentenübergreifenden Sperren über ein gemeinsam genutztes, veränderliches Verzeichnis.

Nur-CLI-Workflows. Wenn Sie tokensave-Befehle ohne angeschlossenen Agenten (kein MCP-Server) ausführen, wird die Veraltungsprüfung nicht zwischen den Befehlen ausgeführt. Installieren Sie Git-Hooks, um den Index nach jedem Commit oder Klon automatisch aktuell zu halten:

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

Upgrade von 5.x

Der eigenständige tokensave daemon-Befehl und sein launchd/systemd/Windows-Dienst-Autostart wurden in 6.0.0 entfernt. Die eingebettete Dateisystemüberwachung auf Betriebssystemebene, die den Daemon ersetzte, wurde selbst in 6.1.0 entfernt (sie verursachte unkontrollierte CPU- und Speicherauslastung bei großen Monorepos mit tiefen node_modules- oder target-Bäumen). Das obige On-Demand-Veraltungsmodell ist das aktuelle Design.

Wenn Sie noch einen Daemon-Autostart von 5.x haben, entfernen Sie ihn:

• 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 (aus einem erhöhten Terminal)

Wenn Sie sich nicht an den genauen Namen erinnern: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Selbst-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 lädt die korrekte Plattform-Binärdatei von GitHub Releases herunter und ersetzt die laufende Binärdatei direkt. Unterstützt stabile und Beta-Kanäle unabhängig voneinander.

Versionierung & Upgrades

tokensave-Versionsnummern sehen aus wie SemVer, folgen diesem aber nicht: Die Komponente, die sich ändert, kodiert den Wartungsaufwand, den das Update erfordert und den tokensave beim nächsten Start automatisch durchführt – Sie führen nie eine Neuinstallation oder Neuindizierung von Hand durch.

Globale Neuinstallation. Beim ersten Start eines neuen Minor- oder Major-Builds führt tokensave stillschweigend install für jeden registrierten Agenten erneut aus, sodass die Agentenkonfiguration immer auf die aktuelle Binärdatei verweist und den aktuellen Tool-Satz bereitstellt. Patch-Erhöhungen überspringen dies – die laufende Versionsmarkierung wird einfach fortgeschrieben.

Projektbezogene erzwungene Neuindizierung (nur Major). Eine Major-Erhöhung bedeutet, dass Projektindizes neu aufgebaut werden müssen. tokensave erledigt dies verzögert und pro Projekt: Beim ersten MCP-Toolaufruf in einem Projekt nach einem Major-Upgrade wird eine vollständige Neuindizierung im Hintergrund gestartet (entspricht tokensave sync --force), die die Tool-Antwort niemals blockiert.

Brew / Cargo-Fallback. Externe Upgrades, die die Binärdatei außerhalb von tokensave upgrade ersetzen – brew upgrade tokensave oder cargo install tokensave – werden auf die gleiche Weise erkannt: Wenn die laufende Version neuer ist als die letzte Version, die eine Installation durchgeführt hat, wird die Neuinstallation beim nächsten Start genauso ausgeführt wie nach einem Selbst-Upgrade.

Siehe TOKENSAVE-VERSIONING.md für die Gründe, warum tokensave von SemVer abweicht (die Kodierung des Wartungsaufwands in der Version ermöglicht Upgrades ohne manuelles Eingreifen), die Markierungsmechanik, die unabhängige Datenbankschemaversion und die Betreuerregeln für die Veröffentlichung von Releases.

CLI-Referenz

tokensave init [path]              # Initialize a new project (full index)
tokensave sync [path]              # Incremental sync (must be initialized first)
tokensave sync --force [path]      # Force a full re-index
tokensave sync --doctor [path]     # Sync and list added/modified/removed files
tokensave status [path]            # Show statistics + cost summary
tokensave status [path] --json     # Show statistics (JSON output)
tokensave status --details         # Include node-kind breakdown
tokensave cost [range]             # Token cost summary (default: 7d)
tokensave cost --by-model          # Cost grouped by model
tokensave cost --by-task           # Cost grouped by task category
tokensave cost --export json|csv   # Export cost data
tokensave query <search> [path]    # Search symbols
tokensave files [--filter dir] [--pattern glob] [--json]   # List indexed files
tokensave affected <files...> [--stdin] [--depth N]        # Find affected test files
tokensave install [--agent NAME]   # Configure agent integration
tokensave reinstall                # Refresh settings for all installed agents
tokensave uninstall [--agent NAME] # Remove agent integration
tokensave serve                    # Start MCP server
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave branch add|list|remove|removeall|gc   # Multi-branch management
tokensave current-counter          # Show per-project token counter
tokensave reset-counter            # Reset per-project token counter
tokensave disable-upload-counter   # Opt out of worldwide counter uploads
tokensave enable-upload-counter    # Re-enable worldwide counter uploads

tokensave doctor

Führen Sie eine umfassende Gesundheitsprüfung Ihrer tokensave-Installation durch:

tokensave doctor

Prüfungen: Binärspeicherort, Projektindex, globale DB, Benutzerkonfiguration, Agentenintegration (MCP-Server, Hooks, Berechtigungen, Prompt-Regeln) und Netzwerkkonnektivität. Wenn nach einem Upgrade Tool-Berechtigungen fehlen, werden Sie aufgefordert, tokensave install auszuführen. Verwenden Sie --agent, um nur einen bestimmten Agenten zu überprüfen.

Doctor validiert auch, dass jeder installierte Hook den korrekten tokensave-Unterbefehl verwendet, und repariert defekte Hooks automatisch.

Funktionsweise mit Claude Code

Einmal konfiguriert, verwendet Claude Code automatisch tokensave anstelle des Lesens von Rohdateien, wenn es Ihre Codebasis verstehen muss. Drei Ebenen verstärken sich gegenseitig:

Das Ergebnis: Claude erhält das gleiche Codeverständnis mit weit weniger Token. Ein typischer Explore-Agent liest 20-50 Dateien; tokensave gibt die relevanten Symbole, Beziehungen und Codeausschnitte aus seinem vorgefertigten Index zurück.

Netzwerkaufrufe & Datenschutz

Die Kernfunktionalität von tokensave (Indizierung, Suche, Graphabfragen, MCP-Server) ist 100% lokal – Ihr Code verlässt niemals Ihren Rechner.

Der weltweite Zähler-Upload sendet einen einzelnen HTTP-POST mit einem JSON-Body wie {"amount": 4823}. Keine Cookies, kein Tracking, keine Benutzer-ID. Der Cloudflare Worker protokolliert das Land Ihrer IP-Adresse (abgeleitet aus den Anfrage-Headern) für aggregierte geografische Statistiken – Ihre tatsächliche IP-Adresse wird nicht gespeichert.

Die Modellpreis-Aktualisierung ruft eine öffentliche JSON-Datei von GitHub ab (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json), um die Claude-Modellpreise für tokensave cost aktuell zu halten. Es werden keine Daten gesendet – es handelt sich um ein einfaches HTTPS-GET. Die Antwort wird unter ~/.tokensave/pricing.json für 24 Stunden zwischengespeichert. Wenn der Abruf fehlschlägt, verwendet tokensave seine eingebaute Preistabelle.

Über 50 Sprachen

tokensave unterstützt mehr als 50 Programmiersprachen, die in drei Stufen organisiert sind und über Cargo-Feature-Flags gesteuert werden. Jede Stufe enthält alle Sprachen der darunterliegenden Stufe. Markdown-Überschriften werden als Module-Knoten mit hierarchischen Contains-Kanten extrahiert, sodass die Dokumentstruktur zusammen mit dem Quellcode an Graphabfragen teilnimmt.

Lite -- --no-default-features

Immer kompiliert. Die kleinste Binärdatei für die beliebtesten Sprachen, plus Svelte und Astro (Extraktion von Skriptblöcken über den TypeScript-Extraktor, keine zusätzliche Grammatikabhängigkeit).

Medium (Lite + 9 weitere) -- --features medium

Full (Medium + alles andere) -- Standard

Einzelne Sprachen können auch ohne eine vollständige Stufe ausgewählt werden:

cargo install tokensave --no-default-features --features lang-nix,lang-bash

Alle Extraktoren teilen sich die gleiche Tiefe: Funktionen, Klassen, Methoden, Felder, Importe, Aufrufgraphen, Vererbungsketten, Docstrings, Komplexitätsmetriken, Dekorator-/Annotationsextraktion und dateiübergreifende Abhängigkeitsverfolgung.

tokensave vs CodeGraph

tokensave ist eine grundlegende Rust-Neuimplementierung von CodeGraph (Node.js/TypeScript). Beide erstellen semantische Codegraphen für KI-Coding-Agenten, unterscheiden sich jedoch erheblich in Umfang und Fähigkeiten.

CodeGraph war der Pionier dieses Ansatzes und bleibt eine solide Wahl, wenn Sie npm-Tooling bevorzugen und nur Claude Code-Integration benötigen. tokensave erweitert das Konzept um tiefere Analysen, mehr Agenten, Multi-Branch-Unterstützung und eine native Binärdatei ohne Laufzeitabhängigkeiten.

Für detaillierte Vergleiche mit CodeGraph, Dual-Graph (GrapeRoot), code-review-graph und OpenWolf siehe docs/COMPARABLE-TOOLS.md.

Warum tokensave gegenüber den Alternativen

Mehrere Tools reduzieren die Token-Nutzung für KI-Coding-Agenten. Hier erfahren Sie, warum tokensave heraussticht.

Einzelne native Binärdatei, null Abhängigkeiten

Jede Alternative benötigt eine Laufzeitumgebung: Python, Node.js oder beides. tokensave wird als einzelne ~25 MB große Rust-Binärdatei mit allen über 50 gebündelten Tree-Sitter-Grammatiken ausgeliefert. Nichts weiter zu installieren.

Tiefste Code-Intelligenz

tokensave arbeitet auf Symbolebene: Funktionen, Structs, Felder, Aufrufkanten, Typhierarchien, Komplexitätsmetriken. Alternativen wie Dual-Graph (GrapeRoot) arbeiten auf Dateiebene – sie wissen, welche Dateien existieren, können aber nicht beantworten: „Wer ruft diese Funktion auf?“ oder „Was geht kaputt, wenn ich diesen Struct ändere?“. Die über 80 spezialisierten MCP-Tools von tokensave decken Aufrufgraph-Traversierung, Auswirkungsanalyse, Erkennung von totem Code, Testzuordnung, Umbenennungsvorschau, Typhierarchien, Erkennung zirkulärer Abhängigkeiten, Komplexitätsranking, Code-Health-Analysen (Gini, DSM, Abhängigkeitstiefe, risikogewichtete Testlücken), atomare Bearbeitungsprimitive und mehr ab. Der nächste Konkurrent (code-review-graph) hat 22 Tools; andere haben 5-9.

Breiteste Agentenunterstützung

Mehr als ein Dutzend KI-Coding-Agenten-Integrationen mit nativen Konfigurationsformaten pro Agent. Kein anderes Tool deckt so viele Agenten mit einer so tiefen Integration ab. Claude Code erhält Hooks, Prompt-Regeln und automatisch erlaubte Tool-Berechtigungen. Kiro erhält globale MCP-Konfiguration, tokensave.md-Steuerung als Ressource geladen, einen verwalteten Agenten mit freizügiger Genehmigung für integrierte/tokensave-Tools und Hooks für Delegierungsleitplanken plus Post-Write-Synchronisation. Andere Agenten erhalten die MCP-Server-Registrierung in ihrem nativen Konfigurationsformat.

Multi-Branch-Indizierung

Das einzige Tool in diesem Bereich mit optionalen Pro-Branch-Graphdatenbanken und branchübergreifendem Diff und Suche. Wenn aktiviert, ist der Branch-Wechsel sofort – keine Neuindizierung erforderlich.

Token-Tracking pro Aufruf

Das einzige Tool, das genau meldet, wie viele Token jeder einzelne MCP-Tool-Aufruf gespart hat, plus einen Live-TUI-Monitor über alle Projekte hinweg und Lebenszeitzähler.

Vollständig Open Source

MIT-lizenziertes Rust, durchgängig prüfbar. Die Kern-Engine von Dual-Graph (graperoot auf PyPI) ist proprietär – Sie können nicht sehen, was es mit Ihrem Codegraphen macht. OpenWolf ist AGPL-3.0, was erfordert, dass abgeleitete Werke Open Source sein müssen.

Leistung

Vollindex-Benchmark auf einer gemischten Rust/Java/Scala-Codebasis mit 1.782 Dateien (57K Knoten, 103K Kanten):

Fehlerbehebung

„tokensave not initialized“

Das Verzeichnis .tokensave/ existiert nicht in Ihrem Projekt.

tokensave init

MCP-Server verbindet sich nicht

Der KI-Agent sieht die tokensave-Tools nicht.

1. Stellen Sie sicher, dass die Agentenkonfiguration den tokensave MCP-Server enthält (führen Sie tokensave doctor aus)
2. Starten Sie den Agenten vollständig neu
3. Überprüfen Sie, ob tokensave in Ihrem PATH ist: which tokensave

Fehlende Symbole in der Suche

• Führen Sie tokensave sync aus, um den Index zu aktualisieren
• Überprüfen Sie, ob die Sprache unterstützt wird (siehe Tabelle oben)
• Stellen Sie sicher, dass die Datei nicht durch .gitignore ausgeschlossen ist

Indizierung ist langsam

Große Projekte benötigen beim ersten vollständigen Index mehr Zeit.

• Nachfolgende Durchläufe nutzen inkrementelle Synchronisierung und sind deutlich schneller
• Verwenden Sie tokensave sync (nicht --force) für alltägliche Aktualisierungen
• Die Aktualität wird bei jedem MCP-Toolaufruf automatisch geprüft, solange ein Agent verbunden ist

Deaktivieren von tokensave für bestimmte Projekte

Wenn ein Projekt zu groß ist und tokensave zu viel RAM verbraucht, können Sie es pro Projekt deaktivieren, indem Sie DISABLE_TOKENSAVE=true in der MCP-Server-Umgebung setzen. Der Server beendet sich sauber ohne Initialisierung.

Claude Code — fügen Sie dies zur .claude/settings.json Ihres Projekts hinzu:

{
  "mcpServers": {
    "tokensave": {
      "command": "tokensave",
      "args": ["serve"],
      "env": {
        "DISABLE_TOKENSAVE": "true"
      }
    }
  }
}

Andere Agenten — setzen Sie die Umgebungsvariable in der Konfiguration, die Ihr Agent zum Starten von MCP-Servern verwendet.

Sie können sie auch global über die Shell setzen (DISABLE_TOKENSAVE=true claude), aber das deaktiviert tokensave für alle Projekte in der Sitzung.

Ursprung

Dieses Projekt ist ein Rust-Port der ursprünglichen CodeGraph TypeScript-Implementierung von @colbymchenry. Der Port behält die gleiche Architektur und MCP-Tool-Schnittstelle bei und nutzt gleichzeitig Rust für Performance und native tree-sitter-Bindungen.

Bauen

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

cargo test                                     # run all tests (requires full)
cargo check --no-default-features              # verify lite compiles
cargo clippy --all

Star-Verlauf

Sponsoren

Kostenlose Codesignatur unter Windows bereitgestellt von SignPath.io, Zertifikat durch SignPath Foundation

Lizenz

MIT-Lizenz — siehe LICENSE für Details.

tokensave.dev