tokensave

officiel

Boostez votre Agent avec l'Intelligence Sémantique du Code et économisez 💰 en cours de route !

Que pouvez-vous faire avec Tokensave MCP ?

  • Recherche sémantique de code — Recherchez du code par sa signification, pas seulement par son texte : interrogez tokensave_search pour « authentification » et obtenez login, validateToken et AuthService en un seul appel.
  • Analyse d’impact — Tracez tokensave_callers et tokensave_callees pour voir exactement ce qui casse avant de modifier un symbole.
  • Construction de contexte — Utilisez tokensave_context pour récupérer les points d’entrée, les symboles liés et les extraits de code en un seul appel d’outil, au lieu de parcourir les fichiers.
  • Requêtes inter-branches — Comparez les graphes de code entre branches avec tokensave_branch_diff ou recherchez les symboles d’une autre branche via tokensave_branch_search sans changer de checkout.
  • Mémoire de session — Persistez les décisions de conception avec tokensave_record_decision et rappelez-les plus tard via tokensave_session_recall afin que les choix d’architecture ne soient pas réexpliqués.
  • Modifications atomiques — Appliquez tokensave_str_replace à ancrage unique ou des réécritures AST sans risques liés aux regex ou aux guillemets shell, avec réindexation automatique après écriture.

Documentation

MCP Toplist

TokenSave

Intelligence sémantique du code pour les agents de codage IA

Moins de jetons • Moins d'appels d'outils • 100% local

GitHub stars crates.io License: MIT Rust Built with AI — part of Enzo Lombardi's AI portfolio

macOS Linux Windows Hypercommit Listed in the Lulu MCP marketplace


Pourquoi tokensave ?

Les agents de codage IA gaspillent des jetons à explorer les bases de code. Chaque grep, glob et lecture de fichier coûte de l'argent. Sur des tâches complexes, les agents génèrent plusieurs sous-agents Explore qui analysent des centaines de fichiers juste pour construire le contexte.

tokensave donne aux agents un graphe de connaissances sémantique pré-indexé. Au lieu d'analyser des fichiers, l'agent interroge le graphe et obtient des réponses structurées instantanées -- les bons symboles, leurs relations et le code source, en un seul appel.

Comment ça fonctionne

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

Sans tokensave : Les agents utilisent grep, glob et Read pour analyser les fichiers -- de nombreux appels API, une utilisation élevée de jetons.

Avec tokensave : Les agents interrogent le graphe via les outils MCP -- résultats instantanés, traitement local, moins de jetons.


Fonctionnalités clés

Construction intelligente du contexteRecherche sémantiqueAnalyse d'impact
Un seul appel d'outil renvoie tout ce dont l'agent a besoin -- points d'entrée, symboles associés et extraits de code.Trouvez le code par le sens, pas seulement par le texte. Recherchez « authentification » et trouvez login, validateToken, AuthService.Sachez exactement ce qui casse avant de le modifier. Tracez les appelants, les appelés et le rayon d'impact complet de tout symbole.
80+ outils MCP50+ langages12+ intégrations d'agents
De la traversée du graphe d'appels à la détection de code mort, en passant par les primitives d'édition atomique, les métriques de santé du code, le mappage des tests et l'analyse de complexité.Rust, Go, Java, Python, TypeScript, C, C++, Swift, Svelte, Astro et 43 autres, y compris les shaders WGSL/HLSL/Metal, CUDA/HIP et Markdown. Trois niveaux (lite/medium/full) contrôlent la taille du binaire.Claude Code, Codex CLI, Gemini CLI, Qwen Code, Kiro, Cursor, OpenCode, Copilot, Cline, Roo Code, Zed, Antigravity, Kilo CLI, Kimi CLI, Mistral Vibe, Grok Build, Factory Droid, OMP, Pi, Plank.
Indexation multi-branches (optionnel)100% localToujours à jour
Bases de données optionnelles par branche. Diff et recherche inter-branches sans changer de checkout.Aucune donnée ne quitte votre machine. Aucune clé API. Aucun service externe. Tout fonctionne sur une base de données libSQL locale.Vérification de fraîcheur à la demande à chaque appel MCP (temps de recharge de 30 s) plus synchronisation de rattrapage à la connexion du serveur. Le travail multi-agents est conçu pour utiliser les git worktrees -- chaque agent a son propre checkout et les divergences d'index sont fusionnées par git, pas par un observateur de fichiers.
Extraction isolée en sous-processusAnalytique de santé du codePrimitives d'édition atomique
Un crash natif dans n'importe quelle grammaire tree-sitter (abort, segfault, peu importe) ne tue que le worker ; le pool le relance et la synchronisation continue. La synchronisation ne meurt jamais sur un fichier malformé.Score de santé composite (0-10000), inégalité de Gini, profondeur du DAG de fichiers, matrice de structure de conception, lacunes de test pondérées par le risque et deltas de session.Modifiez les fichiers sans risques d'expression régulière ou de citation shell : str_replace d'ancrage unique, multi-remplacement atomique, réécriture AST, insertion ancrée. Ré-indexation automatique après les écritures.

Démarrage rapide

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 / cargo-binstall (toute plateforme) :

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

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

Binaires précompilés (Linux, Windows, macOS) :

Téléchargez depuis la dernière version et placez le binaire dans votre PATH.

PlateformeArchive
macOS (Apple Silicon)tokensave-vX.Y.Z-aarch64-macos.tar.gz
Linux (x86_64)tokensave-vX.Y.Z-x86_64-linux.tar.gz
Linux (ARM64)tokensave-vX.Y.Z-aarch64-linux.tar.gz
Windows (x86_64)tokensave-vX.Y.Z-x86_64-windows.zip

2. Configurez votre agent

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 omp             # Oh My Pi (OMP)
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 githooks                         # show which global git hooks tokensave owns
tokensave githooks off                     # remove them, leaving any hook content you wrote

Chaque agent voit son serveur MCP enregistré dans le format de configuration natif. Claude Code reçoit en plus un hook PreToolUse (bloque les agents Explore gaspilleurs), un hook UserPromptSubmit, un hook Stop, des règles d'invite dans CLAUDE.md et des autorisations d'outils auto-autorisées. Kiro reçoit une configuration MCP globale, un tokensave.md de guidage chargé comme ressource, et un agent par défaut géré par tokensave avec approbation permissive des outils intégrés/tokensave, hooks de garde-fou de délégation et synchronisation post-écriture ; les agents Kiro gérés par l'utilisateur sont préservés.

Les installations OMP globales ciblent le profil rapporté par omp config path nu, écrivant <resolved-agent-dir>/mcp.json et <resolved-agent-dir>/rules/tokensave.md. Exportez OMP_PROFILE ou le PI_PROFILE compatible d'OMP lors de l'installation dans un profil nommé ; le résolveur d'OMP honore également PI_CONFIG_DIR et PI_CODING_AGENT_DIR. Tokensave fait confiance à ce résolveur natif plutôt que de dupliquer la logique de profil d'OMP. Tokensave installe les règles MCP et consultatives pour OMP ; il n'installe pas l'application des hooks OMP.

Toutes les modifications sont idempotentes -- sans risque de les réexécuter après une mise à niveau. Après la configuration de l'agent, des hooks git globaux post-commit et post-checkout vous seront proposés. tokensave uninstall supprime ces hooks ainsi que les intégrations d'agents ; passez --keep-git-hooks pour les laisser, ou gérez-les séparément avec tokensave githooks.

Installation locale au projet

Par défaut, tokensave install enregistre le serveur MCP dans la configuration globale de votre agent (par ex. ~/.claude.json). Pour enregistrer tokensave uniquement pour le projet actuel, ajoutez --local :

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

Cela écrit une configuration au niveau du projet que vous pouvez valider et partager avec votre équipe. Pour Claude, c'est ./.mcp.json, ./.claude/settings.json et ./CLAUDE.md ; OMP utilise ./.omp/mcp.json et ./.omp/rules/tokensave.md sans invoquer le CLI OMP. Agents pris en charge : claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (chacun écrit son propre fichier de projet, par ex. .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 pour plank). Les autres agents n'ont pas de configuration au niveau du projet et signalent une erreur avec --local.

Supprimez une installation locale au projet avec tokensave uninstall --local.

3. Indexez votre projet

cd /path/to/your/project
tokensave init

Cela crée un répertoire .tokensave/ avec la base de données du graphe de connaissances. L'initialisation et la synchronisation sont des commandes séparées : init est une adhésion unique par projet, tandis que sync ne met à jour que les projets déjà initialisés. Cela empêche les hooks git globaux de créer silencieusement des bases de données dans des dépôts que vous n'aviez jamais prévu d'indexer. Après init, utilisez tokensave sync pour une mise à jour incrémentale -- seuls les fichiers modifiés sont ré-indexés.

Ce que l'installation écrit pour Claude Code

Serveur MCP

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

Hook PreToolUse

Le hook exécute tokensave hook-pre-tool-use -- une commande Rust native (pas besoin de bash ou jq). Il intercepte les appels d'outils Agent, Grep, Glob et Bash : les agents Explore sont bloqués d'emblée, les invocations grep/rg/ag en forme de symbole (identifiants simples, alternances, noms enveloppés \b) sont redirigées vers l'outil MCP tokensave correspondant, et la découverte en forme de chemin (Glob, find -name, fd --extension) sur les extensions de code est redirigée vers tokensave_files. Les motifs d'expression régulière, git grep, les commandes avec pipe, les extensions non-code, les racines de recherche hors index et les prédicats find qui changent ce que fait la commande (-exec, -delete, -mtime) passent tous sans modification ; définissez TOKENSAVE_DISABLE_GREP_HOOK=1 pour vous désinscrire par shell.

Les filtres sont lus du plus spécifique au plus général : un type explicite est prioritaire, puis un glob de fichier explicite, puis le chemin de recherche. Une recherche de documentation telle que path: "." avec glob: "**/*.md" passe donc au lieu d'être traitée comme une recherche de code sur le chemin large, tandis qu'un glob uniquement code (**/*.rs) est toujours redirigé même sous un chemin non-code. Les globs mixtes (**/*.{rs,md}) passent, car ils peuvent renvoyer de la documentation.

Dispatch sans tête / sous-agent (claude -p). Les processus enfants dispatchés par une session orchestratrice héritent de son ~/.claude/settings.json, y compris ce hook. Pour laisser un enfant exécuter des recherches brutes, définissez TOKENSAVE_DISABLE_GREP_HOOK=1 dans l'environnement de l'enfant -- le binaire natif l'honore et fait passer chaque chemin (Grep, Glob, Bash, Agent), donc pas besoin du --settings '{"hooks": {}}' brutal qui supprime tous les hooks. Le garde-fou est sans état : il ne consulte jamais l'historique des citations, donc il ne redirige que les recherches en forme de symbole décrites ci-dessus et oriente le fan-out de recherche non typé ; les commandes ordinaires ne sont pas affectées, que la session soit interactive ou sans tête.

Règles CLAUDE.md

Ajoute des instructions à ~/.claude/CLAUDE.md qui disent à Claude d'utiliser les outils tokensave avant de recourir aux agents Explore ou aux lectures de fichiers brutes.


Synchronisation résistante aux crashs

Les grammaires tree-sitter sont du code C/C++ compilé. Elles atteignent parfois une assertion interne ou terminent autrement le processus par des chemins que la gestion de panique Rust ne peut pas intercepter. Depuis la v4.3.0, chaque fichier est analysé dans un processus worker de courte durée : si une grammaire segfaute, appelle abort() ou atteint un débordement de pile, seul le worker meurt. Le pool le relance, le fichier fautif est journalisé et ignoré, et sync continue.

Le worker est une sous-commande extract-worker cachée authentifiée contre le parent via un jeton de 256 bits par génération, requis à la fois comme variable d'environnement TOKENSAVE_WORKER_TOKEN et comme les 32 premiers octets reçus sur stdin. L'invocation directe par les utilisateurs échoue. Par défaut, available_parallelism() workers ; désinscription avec TOKENSAVE_DISABLE_SUBPROCESS=1.

Les primitives d'édition (tokensave_str_replace, tokensave_insert_at, etc.) s'exécutent toujours dans le processus : elles ciblent un fichier à la fois où la surcharge du sous-processus dominerait, et un crash d'extraction y est immédiatement visible pour l'agent.


Indexation multi-branches (optionnel)

tokensave peut optionnellement maintenir un graphe de code séparé par branche git. Lorsqu'elle est activée, changer de branche ne donne jamais de résultats obsolètes et ne ré-indexe jamais les fichiers déjà analysés sur une autre branche. Le suivi multi-branches est optionnel -- sans lui, tokensave utilise une base de données unique pour toutes les branches.

Comment ça fonctionne

Lorsque vous suivez une branche, tokensave copie la base de données ancêtre la plus proche et synchronise uniquement les fichiers qui diffèrent. Cela signifie que suivre une branche de fonctionnalité issue de main est presque instantané -- il ne parse que les fichiers que vous avez modifiés.

Commandes CLI

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

Outils MCP inter-branches

Trois outils MCP permettent des requêtes inter-branches sans changer votre checkout :

  • tokensave_branch_search -- rechercher des symboles dans le graphe d'une autre branche
  • tokensave_branch_diff -- comparer les graphes de code entre deux branches : symboles ajoutés, supprimés et modifiés (signature différente). Prend en charge les filtres de fichier et de type.
  • tokensave_branch_list -- lister les branches suivies avec les tailles de base de données, la branche parente et les heures de synchronisation

Repli de branche

Lorsque le serveur MCP ne trouve pas de base de données pour la branche actuelle, il sert depuis la base de données de la branche ancêtre la plus proche et inclut un avertissement dans chaque réponse d'outil suggérant d'exécuter tokensave branch add.

Suivi automatique de branche (v7.3.0)

Une fois le mode multi-branches amorcé (un premier tokensave branch add manuel a créé les métadonnées de branche), les nouvelles branches peuvent être suivies automatiquement au lieu de retomber sur la base de données ancêtre. Deux mécanismes indépendants couvrent cela ; les projets en mode base de données unique ne sont jamais affectés, et aucun mécanisme ne touche jamais la base de données de la branche par défaut. Git hook (lors du changement de branche). Le hook post-checkout que tokensave install configure reconnaît un changement de branche (par opposition à un changement de fichier) et exécute tokensave branch add en arrière-plan. Cette commande est sans effet lorsque la branche est déjà suivie ou est la branche par défaut, donc le basculement ordinaire entre branches connues ne coûte rien. Le premier checkout d'un nouveau git clone et d'une nouvelle git worktree add est aussi un changement de branche, et il peut atterrir sur une branche qui n'est pas celle par défaut (git clone -b feature, git worktree add -b feature) ; là, le hook exécute tokensave init d'abord puis tokensave branch add ensuite, dans cet ordre. Un hook écrit par une version antérieure conserve le corps avec lequel il a été installé — l'installateur ne réécrit jamais un hook existant — donc sur ces installations, un nouveau worktree nécessite encore auto_track ci-dessous, ou un tokensave branch add manuel.

Auto-suivi à l'ouverture (opt-in). Lorsque TokenSave::open s'exécute — commande CLI ou démarrage du serveur MCP — et que la branche active n'est pas suivie, tokensave peut la suivre sur-le-champ en copiant la base de données de l'ancêtre suivi le plus proche et en l'enregistrant dans les métadonnées de la branche. Ceci est contrôlé par le champ de configuration auto_track (par défaut false) ou la variable d'environnement TOKENSAVE_AUTO_TRACK, qui remplace la configuration à chaque exécution (toute valeur l'active sauf 0, false, no, off ou vide). La copie est la même copie quasi instantanée de la base de données de l'ancêtre qu'un branch add manuel effectue ; aucune synchronisation ne s'exécute à ce moment — le hook post-commit maintient la nouvelle base de données de branche à jour pendant que vous committez, ou exécutez tokensave sync pour rafraîchir immédiatement. L'auto-suivi est strictement au mieux : toute défaillance est signalée comme un avertissement et open() continue avec le repli habituel sur l'ancêtre, donc cela ne peut jamais casser un appel d'outil.

En bref : avec le hook installé, le checkout d'une nouvelle branche de fonctionnalité — y compris la branche sur laquelle un nouveau clone ou worktree démarre — lui donne de manière transparente son propre graphe par branche ; avec auto_track activé, même une branche créée en dehors d'un checkout est détectée la première fois que tokensave ouvre le projet dessus.

Voir docs/BRANCHING-USER-GUIDE.md pour le guide complet.


Mémoire inter-sessions

Trois outils MCP persistent les décisions et le contexte de zones de code entre les sessions, stockés dans le .tokensave/tokensave.db par projet.

OutilObjectif
tokensave_record_decisionEnregistrer une décision de conception/architecture avec raison, fichiers et tags optionnels
tokensave_record_code_areaMarquer un chemin où l'agent a travaillé (compteur de touches + last_touched_at)
tokensave_session_recallRequête FTS5 sur les décisions enregistrées ; à associer avec les deux outils d'écriture

Utilisez-les pour que l'agent n'ait pas à réexpliquer les choix d'architecture à chaque session.


Registre des économies

Chaque appel MCP écrit une ligne en ajout seul dans ~/.tokensave/global.db (table savings_ledger). Inspectez avec tokensave gain :

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

Les estimations en dollars utilisent le module de tarification existant (tarification d'entrée Sonnet, actualisée quotidiennement via LiteLLM).

tokensave gain history output


Benchmark reproductible

tokensave bench exécute un ensemble de requêtes fixes via tokensave_context et rapporte les économies de récupération par rapport à une base de référence de fichiers complets (reflète la méthodologie CCE) :

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

tokensave bench output

Mesuré sur ce dépôt (tokensave lui-même) en utilisant l'ensemble de requêtes génériques fourni :

#RequêteBaseContexteÉconomiesFichiersNœuds
1Comment la configuration est-elle chargée au démarrage ?45,3k45499 %45
2Où les arguments de ligne de commande sont-ils analysés et distribués ?94840258 %33
3Comment le point d'entrée principal est-il organisé ?6,1k25196 %38
4Comment les erreurs sont-elles définies, enveloppées et propagées ?3,5k81977 %23
5Où la journalisation ou la sortie de diagnostic est-elle émise ?8,6k51494 %614
6Comment les tests sont-ils organisés et quel harnais de test est utilisé ?3,5k81877 %23
7Comment les données sont-elles persistées sur disque ou dans une base de données ?11,9k33097 %36
8Comment les tâches asynchrones ou le travail en arrière-plan sont-ils lancés ?29,4k36499 %23
9Comment la construction câble-t-elle les dépendances et initialise-t-elle l'état ?10,9k1,4k88 %45
10Comment les surfaces d'API publiques sont-elles exposées (points de terminaison HTTP, exports de bibliothèque ou commandes CLI) ?22,5k23599 %45

Agrégat : 88 % d'économies de récupération moyennes (142,8k → 5,5k tokens sur 10 requêtes).

L'ensemble de requêtes par défaut cible des motifs présents dans la plupart des bases de code applicatives (CLI, démons, services). Exécutez-le sur votre propre projet avec tokensave bench pour voir vos chiffres, ou écrivez un fichier de requêtes sur mesure (--queries my.toml) pour un rappel plus précis.

Bench Criterion contre de grands dépôts réels

benches/large_repos.rs est un micro-benchmark criterion qui exerce les outils MCP de bout en bout contre quatre grandes bases de code open source épinglées à des références constantes. Chaque outil est piloté par au moins 5 requêtes avec des arguments (identifiants de nœuds, noms qualifiés, globs de fichiers, …) échantillonnés depuis le graphe indexé une fois par dépôt, donc les temps sont reproductibles entre les exécutions.

Dépôts et références épinglées (définis dans benches/repos.rs) :

DépôtURLRéférence
polkadot-sdkhttps://github.com/paritytech/polkadot-sdkpolkadot-stable2412
emacshttps://github.com/emacs-mirror/emacsemacs-30.1
scipyhttps://github.com/scipy/scipyv1.14.1
nodehttps://github.com/nodejs/nodev22.11.0

Chaque dépôt est cloné en profondeur limitée (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) à la première utilisation et mis en cache localement ; les exécutions suivantes réutilisent le checkout. La sortie Git est diffusée vers le terminal afin que le téléchargement multi-Go montre une progression en temps réel.

Outils couverts (5 requêtes chacun). Outils de lecture — 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. Outils d'écriture — str_replace, multi_str_replace, insert_at, et (si ast-grep est sur PATH) ast_grep_rewrite.

Synchronisation forcée à chaque exécution. Avant que tout benchmark ne se déclenche, le harnais exécute l'équivalent de tokensave sync --force sur chaque dépôt (index_all() indépendamment de la fraîcheur de .tokensave/) afin que les temps reflètent toujours la source épinglée.

Benchs d'écriture et nettoyage. Les outils d'écriture modifient des fichiers. Pour maintenir la précondition « la correspondance doit être unique », le harnais utilise le iter_batched de criterion — un petit fichier brouillon sous <repo>/.tokensave-bench-scratch/ est réécrit avec un contenu connu avant chaque itération chronométrée, puis l'outil d'édition s'exécute dessus. Après la fin de tous les benchmarks, le harnais exécute git stash --include-untracked && git stash drop dans chaque dépôt préparé afin que l'arbre de travail revienne à la référence épinglée.

Configuration de criterion. Le bench remplace les valeurs par défaut de criterion par sample_size = 10 et measurement_time = 30s (au lieu des 100 / 5 s standard), ce qui donne à chaque timing par requête environ 30 secondes de mesure — suffisant pour que des outils lents comme tokensave_context sur polkadot-sdk produisent des chiffres stables.

Exécution :

# 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

Si TOKENSAVE_BENCH_REPOS_DIR n'est pas défini, le bench affiche un avis et enregistre zéro benchmark (donc cargo bench --all reste peu coûteux sur les machines des contributeurs).

Configuration (tout optionnel, via l'environnement) :

VariableEffet
TOKENSAVE_BENCH_REPOS_DIRRequis. Répertoire racine où chaque dépôt est cloné vers $DIR/<repo-name>/.
TOKENSAVE_BENCH_REPOSSous-ensemble séparé par des virgules de noms de dépôts à tester, par ex. TOKENSAVE_BENCH_REPOS=emacs,scipy. Par défaut, les quatre.
TOKENSAVE_BENCH_SKIP_CLONES'il est défini, le bench échoue rapidement pour tout dépôt non déjà à sa référence épinglée au lieu de récupérer. Utile en CI / exécutions hors ligne.

Filtrage des benchmarks utilise le CLI standard de criterion — par exemple, uniquement l'outil search sur scipy :

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

Les rapports (HTML + échantillons bruts) atterrissent sous target/criterion/.

Pour changer les références épinglées (par ex. vers une version plus récente ou un SHA spécifique), modifiez REPOS dans benches/repos.rs et supprimez le marqueur $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref correspondant afin que la prochaine exécution récupère à nouveau. Si vous sautez le nettoyage post-exécution (par ex. vous Ctrl-C en plein bench), exécuter git stash --include-untracked && git stash drop dans chaque répertoire de dépôt le restaure manuellement.

Sonde de matrice de test MCP (scripts/mcp_probe)

scripts/mcp_probe/ est un harnais Python qui pilote tokensave serve via stdio contre un ensemble configurable de dépôts réels et exerce chaque outil MCP en lecture seule avec 5 variantes de requêtes par langage, produisant un tableau de statut par outil / par dépôt. Le même harnais sert à deux fins :

  • Balayage de régression. Nouveau support de langage, nouvel outil ou refactorisation — relancez la matrice et toute cellule qui échoue nouvellement, expire ou renvoie des résultats vides ressort comme un 🚩.
  • Sonde de performance. Les temps par appel sont journalisés en TSV ; le même corpus fixe de dépôts sert de comparaison grossière entre versions. Le bug actuel du cycle tokensave_inheritance_depth a été trouvé par ce harnais lorsqu'un seul outil sur polkadot-sdk a expiré à >60 s.

Dispositionprobe.py est le pilote (JSON-RPC à correspondance d'ID afin qu'un outil lent ne puisse pas empoisonner les appels suivants), isolated.py ré-exécute un seul outil avec un serveur frais par appel (échappe à la file d'attente du serveur), build_matrix.py lit le TSV et émet du markdown, les modules tools/<lang>.py contribuent des ensembles de requêtes par langage (Rust fourni ; ajoutez Python/Go/… en déposant un nouveau module), repos.toml liste les dépôts cibles (remplacez via $TOKENSAVE_PROBE_REPOS).

Exécution rapide :

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

Les cellules de sortie sont ✓ 5/5 (propre), 🐛 e/N (erreurs), ⏱ N/N (expirations), ∅ E/N (vide), 🐢 ok/slow (appels >10 s). Toute cellule portant une erreur ou une expiration gagne un 🚩 dans la colonne la plus à droite. Le détail par appel avec les 100 premiers caractères de chaque erreur atterrit dans le journal TSV pour suivi.

Différent du bench criterion ci-dessus : criterion mesure la latence par itération pour un ensemble d'outils ciblé sur des références épinglées et produit des rapports statistiques sous target/criterion/ ; mcp_probe exerce chaque outil avec un ensemble de requêtes plus large sur les dépôts que vous lui pointez, optimisant pour la largeur de couverture plutôt que la précision de mesure.


80+ Outils MCP

Le serveur expose plus de 80 outils (un de moins lorsque le binaire optionnel ast-grep n'est pas sur PATH) ; les tableaux ci-dessous regroupent les plus couramment utilisés par catégorie. La plupart sont en lecture seule, sûrs à appeler en parallèle, et annotés avec readOnlyHint. Les primitives d'édition sont limitées à des fichiers uniques et ré-indexent sur place ; les outils de base de session et d'enregistrement de mémoire mutent également l'état local .tokensave et sont annotés comme non en lecture seule. Les trois outils principaux (tokensave_context, tokensave_search, tokensave_status) sont marqués anthropic/alwaysLoad afin de contourner l'aller-retour de recherche d'outil du client.

Interroger un autre projet initialisé

Les outils de lecture sémantique peuvent interroger un graphe local explicitement sélectionné sans redémarrer le serveur MCP :

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

Les résultats sélectionnés incluent la provenance canonique racine/branche. Les identifiants de nœuds sont espacés de noms pour ce graphe, et les sélecteurs correspondants doivent être répétés sur les appels de suivi. Par exemple, un suivi d'une requête sélectionnée par branche inclut les deux valeurs :

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

graph_root doit être la racine absolue exacte d'un projet déjà initialisé. graph_branch est optionnel et, lorsqu'il est fourni, doit nommer une branche suivie. Les ouvertures sélectionnées sont en lecture seule : elles n'initialisent jamais, ne synchronisent pas, ne migrent pas, n'auto-suivent pas, ni n'écrivent de données de graphe/source. Elles ne contribuent pas non plus à la comptabilité des économies. Les appels sans sélecteurs se comportent exactement comme avant. graph_root n'est utile que si vous savez que l'autre projet existe, c'est pourquoi le serveur vous informe : les projets initialisés situés directement à côté de la racine servie sont nommés dans le MCP instructions, dans tokensave_status, et dans les résultats vides de tokensave_search / tokensave_context — le point où une session conclurait autrement qu'un symbole n'existe pas plutôt que de regarder à côté (#375). Seuls les voisins immédiats sont proposés, au maximum cinq, et rien n'est ouvert ou indexé en leur nom ; les interroger nécessite toujours un graph_root explicite.

Les sélecteurs sont intentionnellement indisponibles sur les outils qui écrivent, exécutent des commandes externes, ou dépendent du checkout courant : les primitives d'édition, les outils VCS et de branche, le diagnostic et l'exécution de tests, l'introspection des dépendances et de l'exécution, les outils de workflow et de mémoire de session, l'outil de cache persistant (tokensave_redundancy), et l'administration du serveur. Ces outils rejettent un sélecteur au lieu de l'ignorer silencieusement.

Découverte

OutilObjectif
tokensave_contextObtenir le contexte de code pertinent pour une tâche -- points d'entrée, symboles liés, extraits de code
tokensave_searchTrouver des symboles par nom (fonctions, classes, types)
tokensave_nodeObtenir les détails + le code source d'un symbole spécifique
tokensave_filesLister les fichiers de projet indexés (source et artefacts suivis) avec filtrage
tokensave_module_apiSurface d'API publique d'un fichier ou d'un répertoire
tokensave_similarTrouver des symboles avec des noms similaires
tokensave_annotationsIntrospection des attributs/annotations/décorateurs -- histogramme de toutes les annotations ou listes par site avec filtres de cible
tokensave_docDocumentation Markdown associée à un fichier source -- contenu du doc, fichiers couverts, et signal de fraîcheur
tokensave_dependenciesIntrospection des manifestes de paquets dans 17 écosystèmes -- résumé d'espace de travail, recherche par paquet, surface de licence, dérive de versions
tokensave_statusStatut d'index, statistiques, jetons économisés

Artefacts non-code

tokensave_files couvre plus que le source. Les fichiers dont l'extension est listée dans artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md par défaut) sont suivis par chemin afin que des questions comme « où sont les fichiers .feature pour le flux de connexion ? » aient une réponse de graphe plutôt qu'un find bloqué (#323). Ils ne sont jamais analysés et ne contribuent aucun symbole ; kind: "artifact" et kind: "code" filtrent entre les deux, et les analyses qui signifient « code » les excluent. Une extension déjà gérée par un extracteur de langage est ignorée dans cette liste, donc elle ne peut pas être utilisée pour empêcher un langage d'être analysé.

La liste décide aussi de ce que la recherche littérale peut inspecter (#442). Une recherche littérale (literal: true) sur tokensave_search lit les octets plutôt que les symboles, donc elle n'a besoin d'aucun analyseur -- mais elle itère sur les fichiers indexés, donc elle ne peut atteindre qu'un fichier pour lequel l'index a une ligne. Un modèle .html suivi ou une feuille de style .css n'a ni extracteur ni entrée d'artefact par défaut, donc ses correspondances manquent ; ajoutez l'extension ici et exécutez tokensave sync -f et ses lignes sont recherchées comme n'importe quelle autre, rapportées avec enclosing: null puisqu'il n'y a pas de contexte de symbole. Une réponse littérale qui n'a pas pu atteindre chaque fichier suivi le dit dans un bloc unscanned nommant le compte et les extensions, donc une réponse partielle n'est jamais présentée comme complète.

Graphe d'appels et impact

OutilObjectif
tokensave_callersTrouver ce qui appelle une fonction
tokensave_calleesTrouver ce qu'une fonction appelle
tokensave_impactVoir ce qui est affecté par la modification d'un symbole
tokensave_affectedTrouver les fichiers de test affectés par les modifications du source
tokensave_rename_previewToutes les références à un symbole (aperçu de l'impact d'un renommage)
tokensave_hotspotsSymboles les plus connectés (nombre d'appels le plus élevé)

Qualité du code

OutilObjectif
tokensave_complexityClasser les fonctions par complexité cyclomatique et cognitive, profondeur d'imbrication, métriques Halstead, indice de maintenabilité, CRAP, et métriques de sécurité
tokensave_dead_codeTrouver les symboles inaccessibles (aucun bord entrant ; les symboles nommés comme candidat d'ambiguïté sont exclus)
tokensave_ambiguous_callsSites d'appel que le résolveur n'a pas pu fixer sur une seule cible, avec chaque candidat lié
tokensave_god_classTrouver les classes avec trop de membres
tokensave_couplingClasser les fichiers par fan-in/fan-out
tokensave_inheritance_depthTrouver les hiérarchies d'héritage les plus profondes
tokensave_circularDétecter les dépendances circulaires de fichiers
tokensave_importsDépendances d'import au niveau module, cycles, et simulation de coupe
tokensave_recursionDétecter les cycles d'appels récursifs/mutuellement récursifs
tokensave_unused_importsInstructions d'import jamais référencées
tokensave_doc_coverageSymboles publics sans documentation
tokensave_simplify_scanAnalyse de qualité des fichiers modifiés (duplications, code mort, complexité)

Analytique de santé du code

Cinq outils font ressortir des signaux de qualité structurelle à partir du graphe existant. Le score composite utilise une moyenne géométrique sur des dimensions indépendantes afin qu'aucune ne puisse être jouée individuellement.

OutilObjectif
tokensave_healthSignal de qualité composite (0-10000) à partir de l'acyclicité, la profondeur, l'égalité, la redondance et la modularité
tokensave_giniCoefficient d'inégalité de Gini pour toute métrique (complexité, lignes, fan-in/out, membres) -- trouve les fichiers god et la distribution inégale
tokensave_dependency_depthChaînes de dépendance de fichiers les plus longues (levelisation Lakos) avec reconstruction complète de chaîne après rupture de cycle Tarjan SCC
tokensave_dsmMatrice de structure de conception en forme stats, clusters ou matrix -- révèle les violations de couches et le couplage caché
tokensave_test_riskAnalyse du manque de tests pondérée par le risque combinant complexité, fan-in, couverture et churn git sur 90 jours en un seul score

Sessions

Capturez des métriques de santé au début d'une session de codage IA, puis différenciez à la fin pour voir ce qui s'est amélioré ou régressé.

OutilObjectif
tokensave_session_startEnregistrer les métriques de santé actuelles comme référence JSON pour comparaison ultérieure
tokensave_session_endRecalculer et différencier par rapport à la référence -- deltas par dimension, réussite/échec, nettoyage automatique

Primitives d'édition

Quatre outils d'écriture qui permettent aux agents de modifier des fichiers sans risques de regex ou de citation shell. Chacun est mono-fichier, ancré, et déclenche une ré-indexation en place après l'écriture afin que le graphe ne devienne jamais obsolète.

OutilObjectif
tokensave_str_replaceRemplacer un old_str unique par new_str ; échoue si 0 ou >1 correspondance (protège contre les bugs multi-édition)
tokensave_multi_str_replaceAppliquer N remplacements (old, new) atomiquement -- transaction tout-ou-rien
tokensave_insert_atInsérer du contenu avant ou après une chaîne d'ancrage unique ou un numéro de ligne
tokensave_ast_grep_rewriteRéécriture structurelle de code via le CLI ast-grep en mode --rewrite

Git et workflow

OutilObjectif
tokensave_diff_contextContexte sémantique pour les fichiers modifiés -- symboles modifiés, dépendances, tests affectés
tokensave_commit_contextRésumé sémantique des modifications non validées pour la rédaction de messages de commit
tokensave_pr_contextDiff sémantique entre références git pour les descriptions de pull request
tokensave_changelogDiff sémantique entre deux références git
tokensave_test_mapMappage source-vers-test au niveau symbole, avec détection de symboles non couverts
tokensave_test_coverageCumul de couverture par fichier/symbole/fonction de test avec expansion transitive des bords d'appel

Système de types

OutilObjectif
tokensave_type_hierarchyArbre de hiérarchie de types récursif pour traits, interfaces et classes
tokensave_rankClasser les nœuds par nombre de relations (interface la plus implémentée, classe la plus étendue)
tokensave_distributionRépartition des types de nœuds par fichier ou répertoire
tokensave_largestClasser les nœuds par taille -- plus grandes classes, plus longues méthodes

Portage

OutilObjectif
tokensave_port_statusComparer les symboles entre répertoires source/cible pour suivre la progression du portage
tokensave_port_orderTri topologique des symboles pour le portage -- porter les feuilles d'abord, puis les dépendants

Multi-branche

OutilObjectif
tokensave_branch_searchRechercher des symboles dans le graphe d'une autre branche
tokensave_branch_diffComparer les symboles entre branches (ajoutés/supprimés/modifiés)
tokensave_branch_listLister les branches suivies avec tailles de base de données et temps de synchronisation

Ressources MCP

Quatre ressources sont exposées via resources/list et resources/read :

  • tokensave://status -- statistiques du graphe en JSON
  • tokensave://files -- arborescence de fichiers indexés groupée par répertoire
  • tokensave://overview -- résumé du projet avec distribution des langages et types de symboles
  • tokensave://branches -- branches suivies avec tailles de base de données et informations parentes

Suivi des jetons

tokensave mesure les jetons qu'il économise à chaque appel d'outil MCP. Chaque réponse d'outil inclut une ligne tokensave_metrics: before=N after=M montrant combien de jetons de fichier brut ont été évités par cet appel spécifique.

Désactiver le rapport. La ligne de métriques, avec une phrase dans le MCP instructions, demande à l'agent de vous rapporter les économies — ce qui signifie que le modèle dépense des jetons de sortie pour narrer une économie que tokensave a faite sur les jetons d'entrée. Les jetons de sortie sont le type le plus coûteux, donc si votre agent mentionne tokensave à presque chaque tour, cette narration peut annuler le gain (#356). Définissez report_savings sur false dans .tokensave/config.json, ou la variable d'environnement TOKENSAVE_REPORT_SAVINGS pour la remplacer par exécution (toute valeur l'active sauf 0, false, no, off ou vide). La ligne de métriques et l'instruction disparaissent ; tokensave install cesse également d'écrire la règle de rapport dans les fichiers d'invite d'agent. La mesure reste intacte dans les deux cas — chaque appel atterrit toujours dans le registre des économies, donc tokensave gain, tokensave list, status et monitor continuent de rapporter exactement comme avant. La valeur par défaut reste true.

Observabilité des coûts

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

Analyse les transcriptions de session Claude Code (~/.claude/projects/**/*.jsonl), classe chaque tour d'API dans l'une des 13 catégories de tâches, calcule le coût en dollars en utilisant la tarification des modèles, et stocke les résultats dans ~/.tokensave/global.db pour des requêtes agrégées rapides. La tarification est actualisée depuis LiteLLM toutes les 24 heures et revient à une table intégrée hors ligne.

L'en-tête tokensave status inclut une ligne de coût montrant les dépenses du jour, le total sur 7 jours et le ratio d'efficacité (jetons économisés / jetons totaux). Le TUI tokensave monitor montre un panneau de coût en direct à côté du flux d'économies. À la fin de chaque session Claude Code, le gestionnaire hook_stop imprime un reçu d'une ligne dans le terminal.

Catégories de classification des tâches : Codage, Débogage, Développement de fonctionnalités, Refactorisation, Tests, Exploration, Planification, Délégation, Opérations Git, Build/Déploiement, Brainstorming, Conversation, Général. La classification est déterministe (correspondance de motifs sur les noms d'outils et les commandes Bash), ne nécessite aucun appel LLM, et est adaptée de AgentSeal/codeburn.

Moniteur en direct

tokensave monitor

Un TUI global qui montre les appels d'outils MCP de tous les projets en temps réel, via un tampon en anneau partagé mappé en mémoire à ~/.tokensave/monitor.mmap. Chaque entrée montre le nom du projet, le nom de l'outil et le delta de jetons. Un panneau de coût en haut montre les dépenses du jour, les économies, l'efficacité et le meilleur modèle (actualisé toutes les 30 secondes).

tokensave monitor TUI

Diagnostics mémoire

tokensave memory [--clean]

Un rapport mémoire à l'échelle de la machine pour chaque processus tokensave (serveurs MCP, synchronisations, exécutions d'index), via une table partagée mappée en mémoire à ~/.tokensave/memory.mmap. Chaque instance échantillonne son RSS au mieux de ses capacités au démarrage, à chaque appel d'outil MCP, et autour des phases de synchronisation/résolution, de sorte que le rapport affiche le RSS actuel et le pic avec la phase qui a produit le pic — les données nécessaires pour attribuer une utilisation mémoire élevée (voir #253). Les lignes sont marquées alive, dead (un processus tué par OOM laisse son pic/phase derrière lui comme enregistrement médico-légal), ou orphan (toujours en cours d'exécution mais réparenté à init). --clean purge les emplacements morts.

PEAK PHASE nomme l'échantillon le plus élevé, il n'est donc précis qu'à hauteur de l'échantillonnage. Les enregistrements de synchronisation incrémentale, dans l'ordre : sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Un index complet enregistre index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Chacun est enregistré après le travail qu'il nomme. Ils étaient auparavant enregistrés avant, de sorte que chaque échantillon rapportait le RSS de l'étape précédente sous l'étiquette de l'étape suivante — ce qui attribuait 73 Mio au chargement des nœuds alors qu'il appartenait en réalité au chargement des références non résolues, une étape sans échantillon du tout, et orientait une enquête mémoire vers le mauvais sous-système pendant des mois (#409). Si vous ajoutez une phase, échantillonnez après le travail, pas avant, et ajoutez-en une pour toute étape suffisamment grande pour contenir le pic.

Compteurs de session et de durée de vie

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 rend les statistiques de l'index du projet, la répartition par langage, la ligne de coût (aujourd'hui / 7j / efficacité), et les totaux de durée de vie du projet et mondiaux :

tokensave status output

Compteur mondial

Tous les utilisateurs de tokensave contribuent à un compteur agrégé anonyme. tokensave status affiche à la fois votre total de projet et le total mondial. L'envoi ne transmet qu'un seul nombre (par ex. 4823) sans aucune information d'identification. Désactivez-le avec tokensave disable-upload-counter.


Fraîcheur de l'index

tokensave maintient le graphe à jour sans démon en arrière-plan ni observateur de fichiers au niveau du système d'exploitation.

Vérification de péremption à la demande. Chaque appel d'outil MCP vérifie si des fichiers indexés ont été modifiés depuis la dernière synchronisation. Si des fichiers périmés sont trouvés, ils sont ré-extraits avant que la réponse de l'outil ne soit renvoyée. Un temps de recharge de 30 secondes empêche les appels consécutifs de reparcourir l'arborescence à chaque frappe.

Synchronisation de rattrapage à la connexion. Lorsque le serveur MCP démarre, il exécute immédiatement une synchronisation de rattrapage non bloquante qui récupère toute modification effectuée pendant qu'aucun agent n'était attaché — un git pull, une modification IDE, une étape de build — de sorte que le tout premier appel d'outil d'une session voit un index frais.

Travail multi-agents et arbres de travail git. Lorsque plusieurs agents travaillent simultanément sur le même projet, l'hypothèse forte est que chaque agent opère dans son propre arbre de travail git. Les arbres de travail sont des extractions indépendantes du système de fichiers du même dépôt : l'agent A et l'agent B ont chacun leur propre copie de chaque fichier, donc ils ne s'écrasent jamais mutuellement leurs modifications en cours. tokensave détecte automatiquement lorsqu'une requête provient d'un arbre de travail imbriqué dans le checkout principal et sert les résultats depuis le graphe de branches correct. Les modifications s'accumulent indépendamment et sont finalement réconciliées via git merge ou rebase — le même processus utilisé pour tout autre développement parallèle. Cette conception évite la complexité et les modes de défaillance du verrouillage inter-agents sur un répertoire mutable partagé.

Flux de travail CLI uniquement. Si vous exécutez des commandes tokensave sans agent attaché (pas de serveur MCP), la vérification de péremption ne s'exécute pas entre les commandes. Installez des hooks git pour garder l'index frais automatiquement après chaque commit ou clone :

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

Mise à niveau depuis 5.x

La commande autonome tokensave daemon et son démarrage automatique launchd/systemd/Windows Service ont été supprimés dans 6.0.0. L'observateur de fichiers intégré au niveau du système d'exploitation qui a remplacé le démon a lui-même été supprimé dans 6.1.1 (il provoquait une utilisation excessive du processeur et de la mémoire sur les grands monorepos avec des arborescences profondes node_modules ou target). Le modèle de péremption à la demande ci-dessus est la conception actuelle.

Si vous avez encore un démarrage automatique de démon depuis 5.x, supprimez-le :

  • 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 (depuis un terminal élevé)

Si vous ne vous souvenez pas du nom exact : launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.


Auto-mise à niveau

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 télécharge le binaire de plateforme correct depuis les versions GitHub et remplace le binaire en cours d'exécution sur place. Prend en charge les canaux stable et bêta indépendamment.


Versionnage et mises à niveau

Les numéros de version de tokensave ressemblent à SemVer mais ne le suivent pas : le composant qui change encode la maintenance que la mise à jour nécessite, que tokensave effectue automatiquement au prochain lancement — vous ne réinstallez ni ne réindexez jamais à la main.

IncrémentExempleLa mise à jour nécessiteAction automatique
Correctif (x.y.Z)7.2.0 → 7.2.1RienAucune — pas de réinstallation, pas de réindexation
Mineur (x.Y.0)7.2.0 → 7.3.0Une réinstallation (nouveaux harnais, nouveaux outils, nouvelle configuration)Réinstallation globale de chaque intégration d'agent installée (actualise les permissions, les hooks et la configuration MCP)
Majeur (X.0.0)7.2.0 → 8.0.0Une réinstallation + resynchronisation complèteRéinstallation globale et une réindexation forcée par projet (équivalent sync -f)

Réinstallation globale. Au premier lancement d'une nouvelle version mineure ou majeure, tokensave réexécute silencieusement install pour chaque agent qu'il a enregistré, de sorte que la configuration de l'agent pointe toujours vers le binaire actuel et expose l'ensemble d'outils actuel. Les incréments de correctif ignorent cela — le marqueur de version en cours d'exécution est simplement avancé.

La réinstallation est réellement silencieuse : la sortie de configuration par agent que vous voyez lors d'un tokensave install explicite est supprimée ici, donc elle n'apparaît jamais devant un tokensave init ou tokensave sync ordinaire. Si la configuration d'un agent ne peut pas être actualisée — l'application n'est pas installée, ou sa configuration se trouve dans un emplacement en lecture seule — vous obtenez une ligne nommant les agents en échec :

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

Exécutez tokensave install pour voir l'erreur sous-jacente. Les marqueurs de version avancent dans les deux cas, donc un chemin de configuration qui ne peut jamais être écrit est signalé une fois par mise à niveau plutôt que réessayé à chaque commande ultérieure.

Réindexation forcée par projet (majeur uniquement). Un incrément majeur signifie que les index de projet doivent être reconstruits. tokensave le fait paresseusement et par projet : au premier appel d'outil MCP dans un projet après une mise à niveau majeure, il lance une réindexation complète en arrière-plan (équivalent à tokensave sync --force) qui ne bloque jamais la réponse de l'outil.

Repli Brew / cargo. Les mises à niveau externes qui remplacent le binaire en dehors de tokensave upgradebrew upgrade tokensave ou cargo install tokensave — sont détectées de la même manière : si la version en cours d'exécution est plus récente que la dernière version ayant effectué une installation, la réinstallation s'exécute au prochain lancement comme après une auto-mise à niveau.

Voir TOKENSAVE-VERSIONING.md pour savoir pourquoi tokensave diverge de SemVer (encoder la maintenance dans la version est ce qui rend les mises à niveau sans intervention possibles), la mécanique des marqueurs, la version indépendante du schéma de base de données, et les règles de maintenance pour publier des versions.


Référence CLI

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 [--idle-timeout-secs N]   # Start MCP server (N: exit after N idle seconds)
tokensave servers [--json]         # List running servers and the index each one holds
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave memory [--clean]         # Per-instance RSS report for all tokensave processes
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave githooks [on|off] [--local]  # Manage git hooks (--local: this repo only, no core.hooksPath)
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

Exécutez un contrôle de santé complet de votre installation tokensave :

tokensave doctor

Vérifications : emplacement du binaire, index du projet, base de données globale, configuration utilisateur, intégration d'agent (serveur MCP, hooks, permissions, règles d'invite), et connectivité réseau. Si des permissions d'outil manquent après une mise à niveau, il vous dit d'exécuter tokensave install. Utilisez --agent pour vérifier un agent spécifique uniquement.

Doctor valide également que chaque hook installé utilise la sous-commande tokensave correcte et répare automatiquement les hooks cassés.


Comment cela fonctionne avec Claude Code

Une fois configuré, Claude Code utilise automatiquement tokensave au lieu de lire les fichiers bruts lorsqu'il doit comprendre votre base de code. Trois couches se renforcent mutuellement :

CoucheCe qu'elle faitPourquoi c'est important
Serveur MCPExpose plus de 80 outils tokensave_* à ClaudeClaude peut interroger le graphe directement
Règles CLAUDE.mdDit à Claude de préférer tokensave aux agents/lectures de fichiersEmpêche le modèle de retomber dans des schémas coûteux
Hook PreToolUseLe hook natif Rust bloque les agents ExploreAttrape les cas où le modèle ignore les règles CLAUDE.md
Hook UserPromptSubmitS'exécute à la soumission de l'inviteSuivi du cycle de vie pour la comptabilité des jetons
Hook StopS'exécute à la fin de la sessionVide les compteurs de jetons

Le résultat : Claude obtient la même compréhension du code avec beaucoup moins de jetons. Un agent Explore typique lit 20 à 50 fichiers ; tokensave renvoie les symboles, relations et extraits de code pertinents depuis son index pré-construit.


Appels réseau et confidentialité

La fonctionnalité principale de tokensave (indexation, recherche, requêtes de graphe, serveur MCP) est 100 % locale — votre code ne quitte jamais votre machine.

AppelDonnées envoyéesQuandDésactivation
Envoi du compteur mondialNombre de jetons (un nombre) + pays (depuis l'IP)synchronisation, statut, sessions MCPtokensave disable-upload-counter
Lecture du compteur mondialRien (requête GET)statutN/A (lecture seule, délai d'expiration 1 s)
Vérification de versionRien (requête GET)statut (cache 5 min), synchronisation (parallèle)N/A (délai d'expiration 1 s, sans effet en cas d'échec)
Actualisation des prix des modèlesRien (requête GET)tokensave cost (cache 24 h)N/A (délai d'expiration 5 s, repli sur les prix intégrés)

L'envoi du compteur mondial transmet un seul POST HTTP avec un corps JSON comme {"amount": 4823}. Pas de cookies, pas de suivi, pas d'identifiant utilisateur. Le Cloudflare Worker journalise le pays de votre adresse IP (dérivé des en-têtes de requête) pour des statistiques géographiques agrégées — votre adresse IP réelle n'est pas stockée.

L'actualisation des prix des modèles récupère un fichier JSON public depuis GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) pour maintenir à jour les prix des modèles Claude pour tokensave cost. Aucune donnée n'est envoyée — c'est un simple GET HTTPS. La réponse est mise en cache à ~/.tokensave/pricing.json pendant 24 heures. Si la récupération échoue, tokensave utilise sa table de prix compilée.


Plus de 50 langages

tokensave prend en charge plus de 50 langages de programmation organisés en trois niveaux contrôlés par des indicateurs de fonctionnalité Cargo. Chaque niveau inclut tous les langages du niveau inférieur. Les en-têtes Markdown sont extraits comme nœuds Module avec des arêtes hiérarchiques Contains afin que la structure du document participe aux requêtes de graphe aux côtés du code source.

Lite -- --no-default-features

Toujours compilé. Le plus petit binaire pour les langages les plus populaires, plus Svelte et Astro (extraction de blocs de script via l'extracteur TypeScript, sans dépendance de grammaire supplémentaire).

LangageExtensions
Rust.rs
Go.go
Java.java
Scala.scala, .sc
TypeScript.ts, .tsx
JavaScript.js, .jsx
Python.py
C.c, .h
C++.cpp, .hpp, .cc, .cxx, .hh
Kotlin.kt, .kts
C#.cs
Swift.swift
Svelte.svelte
Astro.astro

Moyen (Lite + 9 de plus) -- --features medium

LangueExtensionsIndicateur de fonctionnalité
Dart.dartlang-dart
Pascal.pas, .pp, .dprlang-pascal
PHP.phplang-php
Ruby.rblang-ruby
Bash.sh, .bashlang-bash
Protobuf.protolang-protobuf
PowerShell.ps1, .psm1lang-powershell
Nix.nixlang-nix
VB.NET.vblang-vbnet

Complet (Medium + tout le reste) -- par défaut

LangueExtensionsIndicateur de fonctionnalité
ActionScript.aslang-actionscript
Lua.lualang-lua
Zig.ziglang-zig
Objective-C.m, .mmlang-objc
Perl.pl, .pmlang-perl
Batch/CMD.bat, .cmdlang-batch
Fortran.f90, .f95, .f03, .f08, .f18, .f, .forlang-fortran
COBOL.cob, .cbl, .cpylang-cobol
MS BASIC 2.0.baslang-msbasic2
GW-BASIC.gwlang-gwbasic
QBasic.qblang-qbasic
QuickBASIC 4.5.bi, .bmlang-qbasic
DockerfileDockerfile, .dockerfilelang-dockerfile
GLSL.glsl, .vert, .frag, .complang-glsl
Godot Shader.gdshader, .gdshaderinclang-glsl
Minecraft Function.mcfunctionlang-mcfunction
WGSL.wgsllang-wgsl
HLSL.hlsl, .fxlang-hlsl
Verilog / SystemVerilog.v, .vh, .sv, .svhlang-systemverilog
Metal.metallang-metal
CUDA / HIP.cu, .cuhlang-cuda
Markdown.md, .markdownlang-markdown
R.r, .Rlang-r
SQL.sqllang-sql
Julia.jllang-julia
Haskell.hs, .lhslang-haskell
OCaml.ml, .mlilang-ocaml
Clojure.clj, .cljs, .cljclang-clojure
Erlang.erl, .hrllang-erlang
Elixir.ex, .exslang-elixir
F#.fs, .fsi, .fsxlang-fsharp
F*.fst, .fstilang-fstar
Quint.qntlang-quint
Terraform.tf, .tfvarslang-terraform
TOML.tomllang-toml
Lean.leanlang-lean

Les langages individuels peuvent également être sélectionnés individuellement sans niveau complet :

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

Tous les extracteurs partagent la même profondeur : fonctions, classes, méthodes, champs, imports, graphes d'appels, chaînes d'héritage, docstrings, métriques de complexité, extraction de décorateurs/annotations, et suivi des dépendances entre fichiers.


tokensave vs CodeGraph

tokensave est une réécriture complète en Rust de CodeGraph (Node.js/TypeScript). Les deux construisent des graphes de code sémantiques pour les agents de codage IA, mais ils divergent considérablement en termes de portée et de capacités.

tokensaveCodeGraph
RuntimeBinaire natif (Rust)Node.js 18+
Installationbrew install, cargo install, scoop installnpx @colbymchenry/codegraph
Langages50+ (3 niveaux : lite/medium/full)19+
Outils MCP80+9
Intégrations d'agents12+ (Claude, Codex, Gemini, Qwen, OpenCode, Cursor, Cline, Copilot, Roo Code, Zed, Antigravity, Kilo, Kiro, Kimi, Vibe, Grok, OMP, Pi, Plank, Factory Droid)1 (Claude Code)
Fraîcheur de l'indexVérification de péremption à la demande à chaque appel MCP ; synchronisation de rattrapage à la connexion ; le travail multi-agents est censé utiliser les git worktreesObservateur de fichiers natif au niveau du système d'exploitation (FSEvents/inotify/ReadDirectoryChangesW, debounce de 2 s) ; synchronisation de rattrapage à la connexion
Indexation multi-branchesOui, sur option (bases de données par branche, diff/recherche inter-branches)Non
Métriques de complexitéExtraites par AST (branches, boucles, profondeur d'imbrication, complexité cyclomatique et cognitive, Halstead, indice de maintenabilité, CRAP)Non
Outils de portageOui (port_status, port_order)Non
Visualiseur de grapheSupprimé (v4.0.1)Oui
Recherche sémantiqueExpansion de mots-clés pilotée par l'agent (coût nul)Embeddings locaux (nomic-embed-text-v1.5 via ONNX)
Ressources MCP4 (statut, fichiers, aperçu, branches)Non
Annotations MCPOui (readOnlyHint, alwaysLoad)Non
Détection de code mortOuiNon
Détection de dépendances circulairesOuiNon
Hiérarchie de typesOuiNon
Analyse de classe god / couplageOuiNon
Contexte de commit / PROuiNon
Mappage de testsOuiNon
Aperçu de renommageOuiNon
Suivi de tokensMétriques par appel, moniteur TUI en direct, compteurs de session et à vieNon
Analytique de santé du codeScore composite, Gini, profondeur de dépendance, DSM, lacunes de test pondérées par risque, deltas de sessionNon
Primitives d'édition4 rédacteurs atomiques (str_replace, multi_str_replace, insert_at, ast_grep_rewrite) avec ré-indexation automatiqueNon
Résilience aux crashsExtraction isolée en sous-processus ; les abandons de grammaire native sautent le fichier, la synchronisation continueNon
Auto-mise à niveautokensave upgrade avec canaux stable/bêtanpm update
Moteur de base de donnéeslibsql (fork SQLite, WAL, asynchrone)better-sqlite3 / wa-sqlite (WASM)
Vitesse d'indexation~1,2 s pour 1 782 fichiers~4 s pour 1 782 fichiers
Taille du binaire~25 Mo (toutes les grammaires incluses)~80 Mo (node_modules + WASM)

CodeGraph a été le pionnier de l'approche et reste un choix solide si vous préférez les outils npm et n'avez besoin que de l'intégration Claude Code. tokensave étend le concept avec une analyse plus approfondie, plus d'agents, la prise en charge multi-branches et un binaire natif sans dépendances d'exécution.

Pour des comparaisons détaillées avec CodeGraph, Dual-Graph (GrapeRoot), code-review-graph et OpenWolf, voir docs/COMPARABLE-TOOLS.md.


Pourquoi tokensave plutôt que les alternatives

Plusieurs outils réduisent l'utilisation de tokens pour les agents de codage IA. Voici pourquoi tokensave se distingue.

Un seul binaire natif, zéro dépendance

Chaque alternative nécessite un runtime : Python, Node.js, ou les deux. tokensave est fourni sous forme d'un seul binaire Rust d'environ 25 Mo avec les 50+ grammaires tree-sitter incluses. Rien d'autre à installer.

La plus profonde intelligence de code

tokensave travaille au niveau des symboles : fonctions, structures, champs, arêtes d'appel, hiérarchies de types, métriques de complexité. Les alternatives comme Dual-Graph (GrapeRoot) travaillent au niveau des fichiers -- elles savent quels fichiers existent mais ne peuvent pas répondre à « qui appelle cette fonction ? » ou « qu'est-ce qui casse si je modifie cette structure ? » Les 80+ outils MCP spécialisés de tokensave couvrent la traversée de graphes d'appels, l'analyse d'impact, la détection de code mort, le mappage de tests, l'aperçu de renommage, les hiérarchies de types, la détection de dépendances circulaires, le classement par complexité, l'analytique de santé du code (Gini, DSM, profondeur de dépendance, lacunes de test pondérées par risque), les primitives d'édition atomiques, et plus encore. Le concurrent le plus proche (code-review-graph) a 22 outils ; les autres en ont 5 à 9.

Le plus large support d'agents

Plus d'une douzaine d'intégrations d'agents de codage IA avec des formats de configuration natifs par agent. Aucun autre outil ne couvre autant d'agents avec une intégration aussi profonde. Claude Code bénéficie de hooks, de règles de prompt et d'autorisations d'outils auto-autorisées. Kiro bénéficie d'une configuration MCP globale, d'un pilotage tokensave.md chargé comme ressource, d'un agent géré avec approbation d'outils permissive intégrée/tokensave, et de hooks pour les garde-fous de délégation plus une synchronisation post-écriture. Les autres agents bénéficient de l'enregistrement du serveur MCP dans leur format de configuration natif.

Indexation multi-branches

Le seul outil dans cet espace avec des bases de données de graphes par branche optionnelles et un diff et une recherche inter-branches. Lorsqu'elle est activée, le changement de branche est instantané -- aucune ré-indexation requise.

Suivi de tokens par appel

Le seul outil qui rapporte exactement combien de tokens chaque appel d'outil MCP individuel a économisés, plus un moniteur TUI en direct sur tous les projets et des compteurs à vie.

Entièrement open source

Rust sous licence MIT, auditable de bout en bout. Le moteur principal de Dual-Graph (graperoot sur PyPI) est propriétaire -- vous ne pouvez pas voir ce qu'il fait avec votre graphe de code. OpenWolf est sous AGPL-3.0, ce qui exige que les œuvres dérivées soient open source.

Performance

Benchmark d'indexation complète sur une base de code mixte Rust/Java/Scala de 1 782 fichiers (57K nœuds, 103K arêtes) :

OutilTempsAccélération
CodeGraph (TypeScript)31,2 s1x
tokensave (Rust)1,2 s26x

Dépannage

« tokensave not initialized »

Le répertoire .tokensave/ n'existe pas dans votre projet.

tokensave init

Le serveur MCP ne se connecte pas

L'agent IA ne voit pas les outils tokensave.

  1. Assurez-vous que la configuration de l'agent inclut le serveur MCP tokensave (exécutez tokensave doctor)
  2. Redémarrez complètement l'agent
  3. Vérifiez que tokensave est dans votre PATH : which tokensave

Symboles manquants dans la recherche

  • Exécutez tokensave sync pour mettre à jour l'index
  • Vérifiez que le langage est pris en charge (voir le tableau ci-dessus)
  • Vérifiez que le fichier n'est pas exclu par .gitignore

L'indexation est lente

Les grands projets prennent plus de temps lors de la première indexation complète.

  • Les exécutions suivantes utilisent la synchronisation incrémentale et sont beaucoup plus rapides
  • Utilisez tokensave sync (pas --force) pour les mises à jour quotidiennes
  • La péremption est vérifiée automatiquement à chaque appel d'outil MCP pendant qu'un agent est connecté

Désactivation de tokensave pour des projets spécifiques

Si un projet est trop grand et que tokensave utilise trop de RAM, vous pouvez désactiver le serveur MCP par projet en définissant TOKENSAVE_DISABLE_SERVER=true dans son environnement. Le serveur se ferme proprement sans s'initialiser.

Claude Code — ajoutez à votre .claude/settings.json de projet :

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

Autres agents — définissez la variable d'environnement dans la configuration que votre agent utilise pour lancer les serveurs MCP.

Vous pouvez également la définir globalement via le shell (TOKENSAVE_DISABLE_SERVER=true claude), mais cela désactive le serveur MCP tokensave pour tous les projets de la session.

DISABLE_TOKENSAVE=true reste pris en charge comme alias de compatibilité obsolète pour les configurations créées avant que cette variable ne soit espacée par espace de noms.


Origine

Ce projet est un portage Rust de l'implémentation TypeScript originale CodeGraph par @colbymchenry. Le portage maintient la même architecture et la même interface d'outils MCP tout en tirant parti de Rust pour la performance et les liaisons natives tree-sitter.


Construction

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

Historique des étoiles

Star history

Sponsors

SignPath Signature de code gratuite sur Windows fournie par SignPath.io, certificat par SignPath Foundation

Licence

Licence MIT -- voir LICENSE pour plus de détails.

tokensave.dev