tokensave

Intelligence de Code Sémantique pour Agents de Codage IA

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

Pourquoi tokensave ?

Les agents de codage IA gaspillent des tokens à 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 de multiples sous-agents d'exploration qui scannent des centaines de fichiers juste pour construire le contexte.

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

Comment ça marche

┌──────────────────────────────────────────────────────────────┐
│  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 scanner les fichiers -- nombreux appels API, utilisation élevée de tokens.

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

Fonctionnalités clés

Démarrage rapide

1. Installer

Homebrew (macOS) :

brew install aovestdipaperino/tap/tokensave

Scoop (Windows) :

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

Cargo (toute plateforme) :

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.

2. Configurer 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 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)

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 inutiles), un hook UserPromptSubmit, un hook Stop, des règles d'invite dans CLAUDE.md et des permissions d'outils auto-autorisées. Kiro reçoit la configuration MCP globale, le pilotage tokensave.md 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.

Toutes les modifications sont idempotentes -- exécutable à nouveau sans risque 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.

Installation locale au projet

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

tokensave install --local --agent claude

Ceci écrit une configuration limitée au projet que vous pouvez commiter et partager avec votre équipe. Pour Claude, il s'agit de ./.mcp.json, ./.claude/settings.json et ./CLAUDE.md. Agents supportés : claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie (chacun écrit son propre fichier 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). Les autres agents n'ont pas de configuration limitée au projet et signalent une erreur avec --local.

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

3. Indexer votre projet

cd /path/to/your/project
tokensave init

Ceci 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 l'intention d'indexer. Après init, utilisez tokensave sync pour mettre à jour de manière incrémentielle -- seuls les fichiers modifiés sont ré-indexés.

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

Synchronisation résiliente aux crashs

Les grammaires tree-sitter sont du code C/C++ compilé. Elles rencontrent occasionnellement 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 sous-processus worker de courte durée : si une grammaire provoque une segfault, appelle abort() ou rencontre un dépassement de pile, seul le worker meurt. Le pool le régénère, le fichier incriminé est journalisé et ignoré, et sync continue.

Le worker est une sous-commande extract-worker cachée authentifiée auprès du 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ésengagez 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'extracteur y est immédiatement visible pour l'agent.

Indexation multi-branche (Optionnelle)

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

Comment ça marche

Lorsque vous suivez une branche, tokensave copie la base de données de l'ancêtre le plus proche et synchronise uniquement les fichiers qui diffèrent. Cela signifie que suivre une branche de fonctionnalité à partir de main est quasi instantané -- cela n'analyse 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 DB, 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 à partir de la DB 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 des branches (v7.3.0)

Une fois le mode multi-branche amorcé (une première commande manuelle tokensave branch add a créé les métadonnées de branche), les nouvelles branches peuvent être suivies automatiquement au lieu de se replier sur la DB ancêtre. Deux mécanismes indépendants couvrent cela ; les projets en mode DB unique ne sont jamais affectés, et aucun des deux mécanismes ne touche jamais à la base de données de la branche par défaut.

Hook git (au checkout de branche). Le hook post-checkout que tokensave install met en place reconnaît un checkout de branche (par opposition à un checkout 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.

Suivi automatique à l'ouverture (optionnel). 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 DB de l'ancêtre suivi le plus proche et en l'enregistrant dans les métadonnées de 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 par 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 DB ancêtre qu'effectue un branch add manuel ; aucune synchronisation n'est exécutée à ce moment-là — le hook post-commit garde la nouvelle DB de branche à jour au fur et à mesure de vos commits, ou exécutez tokensave sync pour rafraîchir immédiatement. Le suivi automatique est strictement au mieux : tout échec est signalé comme un avertissement et open() procède avec le repli ancêtre habituel, donc il ne peut jamais interrompre un appel d'outil.

En bref : avec le hook installé, le checkout d'une nouvelle branche de fonctionnalité 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 (par ex. dans un nouveau worktree) est prise en charge la première fois que tokensave ouvre le projet dessus.

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

Mémoire inter-session

Trois outils MCP conservent les décisions et le contexte de zone de code entre les sessions, stockés dans le fichier .tokensave/tokensave.db propre au projet.

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

Registre des économies

Chaque appel MCP écrit une ligne en ajout seulement 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 des entrées Sonnet, actualisée quotidiennement via LiteLLM).

Benchmark reproductible

tokensave bench exécute un ensemble de requêtes fixe via tokensave_context et rapporte les économies de récupération par rapport à une base de référence fichier complet (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

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

Agrégat : 88 % d'économie moyenne de récupération (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 personnalisé (--queries my.toml) pour un rappel plus précis.

Banc d'essai Criterion sur 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 sur 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œud, noms qualifiés, globs de fichiers, …) échantillonnés à partir du graphe indexé une fois par dépôt, afin que les temps soient reproductibles d'une exécution à l'autre.

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

Chaque dépôt est cloné superficiellement (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) lors de la première utilisation et mis en cache localement ; les exécutions suivantes réutilisent l'extraction. La sortie Git est diffusée vers le terminal afin que la récupération de plusieurs Go affiche la 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 tout déclenchement de benchmark, le harnais exécute l'équivalent de tokensave sync --force sur chaque dépôt (index_all() quelle que soit la fraîcheur de .tokensave/) afin que les temps reflètent toujours la source épinglée.

Bancs d'essai d'écriture et nettoyage. Les outils d'écriture modifient les fichiers. Pour maintenir la condition préalable « la correspondance doit être unique », le harnais utilise iter_batched de criterion — un petit fichier temporaire 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. Une fois tous les benchmarks terminés, 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 banc d'essai remplace les valeurs par défaut de criterion par sample_size = 10 et measurement_time = 30s (au lieu des 100 / 5s standard), ce qui donne à chaque mesure de temps par requête environ 30 secondes — suffisamment pour que des outils lents comme tokensave_context sur polkadot-sdk produisent des chiffres stables.

Exécutez-le :

# 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

Si TOKENSAVE_BENCH_REPOS_DIR n'est pas défini, le banc d'essai affiche un avis et enregistre zéro benchmark (afin que cargo bench --all reste léger sur les machines des contributeurs).

Configuration (tout optionnel, via l'environnement) :

Le filtrage des benchmarks utilise la 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) se trouvent 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 refasse la récupération. Si vous sautez le nettoyage post-exécution (par ex. vous faites Ctrl-C en cours de banc d'essai), 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 sur un ensemble configurable de dépôts réels et exerce chaque outil MCP en lecture seule avec 5 variantes de requête par langage, produisant une table de statut par outil / par dépôt. Le même harnais sert deux objectifs :

• Balayage de régression. Nouveau support de langage, nouvel outil ou refactorisation — réexécutez la matrice et toute cellule qui génère une nouvelle erreur, expire ou retourne 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 également de comparaison grossière entre versions. Le bogue actuel du cycle tokensave_inheritance_depth a été trouvé par ce harnais lorsqu'un seul outil sur polkadot-sdk a expiré à >60 s.

Disposition — probe.py est le pilote (JSON-RPC à identifiant apparié pour 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 fournissent des ensembles de requêtes par langage (Rust livré ; 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 se trouve dans le journal TSV pour suivi.

Différent du banc d'essai 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 pointez, en optimisant pour l'étendue de la couverture plutôt que la précision de la mesure.

Plus de 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, peuvent être appelés en parallèle en toute sécurité et sont 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 en mémoire modifient également l'état local .tokensave et sont annotés comme non 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'outils du client.

Découverte

Graphe d'appel et impact

Qualité du code

Analyses de santé du code

Cinq outils font émerger 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 manipulée isolément.

Sessions

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

Primitives d'édition

Quatre outils d'écriture permettant aux agents de modifier des fichiers sans les risques liés aux expressions régulières ou à l'échappement shell. Chacun est mono-fichier, ancré, et déclenche une réindexation sur place après écriture afin que le graphe ne soit jamais obsolète.

Git & Flux de travail

Système de types

Portage

Multi-branche

Ressources MCP

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

• tokensave://status -- statistiques du graphe au format 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 BDD et informations sur le parent

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 indiquant combien de jetons de fichier brut ont été évités par cet appel spécifique.

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 du modèle, 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 utilise une table intégrée en mode hors ligne.

L'en-tête tokensave status inclut une ligne de coût indiquant les dépenses du jour, le total sur 7 jours et le ratio d'efficacité (jetons économisés / total des jetons). L'ATH tokensave monitor affiche un panneau de coûts 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 (reconnaissance 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

Une IHM globale qui montre les appels d'outils MCP de tous les projets en temps réel, via un tampon circulaire 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ûts en haut affiche les dépenses du jour, les économies, l'efficacité et le modèle principal (actualisé toutes les 30 secondes).

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

Compteur mondial

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

Fraîcheur de l'index

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

Vérification de l'obsolescence à 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 obsolètes sont trouvés, ils sont ré-extraits avant que la réponse de l'outil ne soit renvoyée. Un délai de 30 secondes empêche les appels consécutifs de ré-explorer 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 prend en compte toutes les modifications effectuées lorsqu'aucun agent n'était attaché — un git pull, une édition dans l'IDE, une étape de build — afin que le tout premier appel d'outil d'une session voie un index frais.

Travail multi-agents et arborescences 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 sa propre arborescence de travail git. Les arborescences de travail sont des extractions indépendantes du même dépôt sur le système de fichiers : l'agent A et l'agent B ont chacun leur propre copie de chaque fichier, de sorte qu'ils n'écrasent jamais les modifications en cours de l'autre. tokensave détecte automatiquement quand une requête provient d'une arborescence de travail imbriquée dans l'extraction principale et sert les résultats à partir du graphe de la branche correcte. 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 d'obsolescence ne s'exécute pas entre les commandes. Installez des hooks git pour maintenir 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 la 5.x

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

Si vous avez encore un démarrage automatique de démon de la version 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 releases GitHub et remplace le binaire en cours d'exécution sur place. Prend en charge les canaux stable et bêta indépendamment.

Versionnage & mises à niveau

Les numéros de version de tokensave ressemblent à SemVer mais ne le suivent pas : le composant qui change encode la maintenance requise par la mise à jour, que tokensave effectue automatiquement au prochain lancement — vous n'exécutez jamais de réinstallation ou de réindexation manuellement.

Réinstallation globale. Lors de la première exécution d'une nouvelle version mineure ou majeure, tokensave ré-exécute silencieusement install pour chaque agent qu'il a enregistré, afin que la configuration de l'agent pointe toujours vers le binaire actuel et expose l'ensemble d'outils actuel. Les incréments de correctif sautent cette étape — le marqueur de version en cours est simplement avancé.

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 : lors du 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.

Solution de repli Brew / cargo. Les mises à niveau externes qui remplacent le binaire en dehors de tokensave upgrade — brew 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 elle le ferait après une auto-mise à niveau.

Voir TOKENSAVE-VERSIONING.md pour comprendre pourquoi tokensave diverge de SemVer (encoder la maintenance dans la version est ce qui rend les mises à niveau sans intervention possibles), les mécanismes de marqueur, la version indépendante du schéma de base de données, et les règles pour le mainteneur lors de la publication de releases.

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

Exécutez un bilan de santé complet de votre installation tokensave :

tokensave doctor

Vérifications : emplacement du binaire, index du projet, BDD globale, configuration utilisateur, intégration de l'agent (serveur MCP, hooks, permissions, règles d'invite) et connectivité réseau. Si des permissions d'outils sont manquantes après une mise à niveau, il vous indique 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 a besoin de comprendre votre base de code. Trois couches se renforcent mutuellement :

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 & Confidentialité

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

Le téléversement du compteur mondial envoie une seule requête HTTP POST avec un corps JSON comme {"amount": 4823}. Pas de cookies, pas de pistage, pas d'identifiant utilisateur. Le Worker Cloudflare enregistre le pays de votre adresse IP (déduit 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 -- il s'agit d'une simple requête HTTPS GET. 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 en tant que 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).

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

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

Les langages individuels peuvent également être sélectionnés sans un 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'appel, chaînes d'héritage, docstrings, métriques de complexité, extraction de décorateurs/annotations et suivi des dépendances inter-fichiers.

tokensave vs CodeGraph

tokensave est une réécriture Rust complète 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.

CodeGraph a été le pionnier de l'approche et reste un choix solide si vous préférez l'outillage 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 démarque.

Binaire natif unique, zéro dépendance

Chaque alternative nécessite un environnement d'exécution : Python, Node.js, ou les deux. tokensave est livré sous la forme d'un seul binaire Rust d'environ 25 Mo avec toutes les grammaires tree-sitter (plus de 50) incluses. Rien d'autre à installer.

Intelligence de code la plus approfondie

tokensave fonctionne 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) fonctionnent au niveau du fichier -- 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 plus de 80 outils MCP spécialisés de tokensave couvrent le parcours du graphe d'appel, 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 de complexité, l'analyse de santé du code (Gini, DSM, profondeur de dépendance, écarts de test pondérés par le risque), les primitives d'édition atomique, et plus encore. Le concurrent le plus proche (code-review-graph) a 22 outils ; d'autres en ont 5 à 9.

Prise en charge d'agents la plus large

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 obtient des hooks, des règles d'invite et des autorisations d'outils auto-autorisées. Kiro obtient une configuration MCP globale, tokensave.md chargé en tant que ressource, un agent géré avec approbation permissive des outils intégrés/tokensave, et des hooks pour les garde-fous de délégation plus la synchronisation post-écriture. Les autres agents obtiennent 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 optionnelles par branche et une comparaison et recherche inter-branches. Lorsqu'elle est activée, le changement de branche est instantané -- aucune ré-indexation requise.

Suivi des tokens par appel

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

Entièrement open source

Sous licence MIT Rust, 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 AGPL-3.0, ce qui exige que les travaux dérivés 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) :

Dépannage

« tokensave non initialisé »

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 lorsqu'un agent est connecté

Désactiver tokensave pour des projets spécifiques

Si un projet est trop volumineux et que tokensave utilise trop de RAM, vous pouvez le désactiver par projet en définissant DISABLE_TOKENSAVE=true dans l'environnement du serveur MCP. Le serveur s'arrête proprement sans s'initialiser.

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

{
  "mcpServers": {
    "tokensave": {
      "command": "tokensave",
      "args": ["serve"],
      "env": {
        "DISABLE_TOKENSAVE": "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 (DISABLE_TOKENSAVE=true claude), mais cela désactive tokensave pour tous les projets de la session.

Origine

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

Compilation

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

Sponsors

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