headroom vs tokensave : compresser ou indexer le code ?

Fait partie du pilier réduire l'usage des tokens dans Claude Code. Cette page oppose les deux conceptions les plus contraires de la catégorie.

headroom ou tokensave : lequel choisir ?

tokensave porte moins de risque ; headroom porte plus de potentiel sur les charges étroites qui lui conviennent. Ils ne se recoupent pas du tout. headroom réécrit le tableau de messages avant chaque appel API. tokensave donne un index à l'agent pour qu'il cesse d'avoir autant à lire. L'un intervient sur ce que voit le fournisseur, l'autre sur ce que demande l'agent, et cette différence décide presque tout le reste. Je maintiens un benchmark ouvert de sessions longues et je vends un outil concurrent. Sur ce benchmark, headroom termine 53 % plus cher que sans aucun outil, dernier sur douze. tokensave n'y est pas passé et ne publie aucun benchmark : ses économies sont non quantifiées. Ce sont deux affirmations différentes, et aucune n'est un verdict sur l'ingénierie.

Que fait headroom exactement ?

Il compresse toute la fenêtre de conversation avant chaque appel. SDK Python, proxy CLI et serveur MCP, Apache 2.0, environ 18,7k étoiles, en trois étapes : CacheAligner sort timestamps et UUID du préfixe statique vers une queue non cachée ; ContentRouter route chaque contenu vers un compresseur spécifique à son format via détection ML — JSON, code, texte, logs, diffs, HTML ; IntelligentContext note le reste sur six dimensions de pertinence. C'est réversible. Les originaux restent dans un cache LRU local et le modèle reçoit un outil headroom_retrieve injecté, avec sous-recherche BM25 optionnelle, pour en rapatrier un. Les taux de compression par charge sont réellement forts : 92 % sur les résultats de recherche de code et les logs d'incidents SRE, 73 % sur le triage d'issues. SmartCrusher échantillonne les grands tableaux JSON à 70–95 % en conservant toujours les lignes d'erreur, un détail qui montre que le projet a réfléchi à ses modes de défaillance. L'empreinte est lourde : Python 3.10+, un modèle ModernBERT de 150M de paramètres, détection de contenu Magika, 16 à 50 ms par appel.

Que fait tokensave exactement ?

Il construit un index de symboles et le sert en MCP. Un serveur Rust avec un graphe de connaissances sémantique en libSQL et FTS5, bâti par extraction tree-sitter sur 34 langages, exposant 48 outils MCP. Ses traits distinctifs tiennent à la forme de l'outil plus qu'à un taux de compression :

Compilé. Démarrage rapide, mémoire faible, aucun runtime à installer. Homebrew sur macOS, Scoop sur Windows, binaires précompilés ailleurs.
Indexation multi-branches. Comparer et chercher entre branches sans changer de checkout — rien d'autre dans la catégorie ne le fait, et cela supprime une classe d'allers-retours git checkout coûteux en contexte.
Isolation par sous-processus. Un parseur qui plante sur un fichier malformé n'emporte pas le service, ce qui compte avec 34 grammaires en jeu.
Primitives d'édition atomiques avec réécriture AST. L'agent renomme un symbole via l'arbre plutôt que via une regex, ce qui évite les pièges d'échappement shell et de correspondance partielle qui font échouer les éditions agentiques en silence.

Ses manques : pas de filtrage de sorties, donc les sorties de commandes arrivent en taille réelle ; navigation seule, sans recherche vectorielle sémantique ni compression structurelle ; détection de frameworks limitée à quatorze frameworks codés en dur ; et aucun chiffre publié.

Pourquoi le compresseur porte-t-il plus de risque ?

Parce qu'il dépense le cache de prompts pour acheter du volume de tokens. Le cache ne paie que si le préfixe est identique octet pour octet d'un tour à l'autre, et l'entrée en cache est facturée une fraction de l'entrée fraîche chez tous les grands fournisseurs. Un outil qui réécrit la fenêtre change le préfixe dès que ses décisions de compression changent — c'est-à-dire dès que le contenu change, donc à chaque tour d'une boucle d'agent. Le cache rate et vous repayez plein tarif un contexte déjà acheté. CacheAligner existe pour combattre exactement cela, ce qui montre que le projet a identifié le risque. Sur une longue boucle interactive, ça ne suffit pas. Il y a un second chemin. Quand la version compressée ne suffit pas, le modèle appelle headroom_retrieve et rapatrie l'original : vous avez payé la copie compressée, l'original, et l'aller-retour. Rare sur une tâche courte, cumulatif sur une session. Un index n'a pas d'équivalent. Il ne touche pas au préfixe, donc le cache continue de fonctionner. Son pire cas est un index périmé qui donne une réponse fausse avec assurance : cela coûte une correction, pas un multiplicateur systématique. Cette asymétrie est le vrai contenu de cette comparaison.

Où la surface de 48 outils de tokensave vous coûte-t-elle ?

À chaque tour, avant même que vous n'appeliez quoi que ce soit. Les définitions d'outils MCP sont envoyées en tokens d'entrée avant votre premier message, utilisées ou non. Un serveur à 48 outils est un coût permanent plus élevé qu'un serveur à 10, et il est invisible si vous ne le cherchez pas. Ce n'est pas une raison de l'éviter — les outils sont le produit — mais c'est une raison de le déconnecter sur les sessions de pur travail terminal, et une raison de ne pas faire tourner deux index à la fois.

Que ne fait ni l'un ni l'autre ?

Les sorties de commandes. tokensave ne les voit jamais. headroom les compresse dans la fenêtre, après qu'elles ont été produites et payées une fois en limite d'outil.
Les lectures de fichiers entiers pour éditer. Un index dit quel fichier ; il ne le réduit pas. Un compresseur le réduit et met le cache en danger.
Les manifestes MCP. Aucun ne les diffère. tokensave en ajoute un gros.
Les relectures. Même fichier, quatre fois, quatre facturations. Un index en réduit la probabilité ; aucun ne déduplique.

Lequel choisir ?

Prenez tokensave si vous travaillez sur de nombreux langages, voulez un binaire compilé unique sans runtime, ou relisez assez de branches pour que la recherche multi-branches corresponde à votre flux réel. Les primitives d'édition atomiques sont un vrai gain de sûreté sur tout agent qui édite via des commandes shell. Prenez headroom si votre charge est batch plutôt qu'interactive : des payloads longs et stables traités une fois, où le préfixe n'est pas invalidé à chaque tour et où 92 % sur un gros blob JSON est toute l'histoire. C'est un vrai cas d'usage, et ce n'est pas une boucle de code agentique. Ne prenez ni l'un ni l'autre pour l'instant si votre dépense est surtout en sorties de commandes. Aucun n'est positionné sur ce canal d'une façon qui survive à une session.

Comment appliquer ça aujourd'hui

Vérifiez votre taux de hit de cache avant d'installer quoi que ce soit qui réécrit la fenêtre. S'il est élevé, un compresseur dépense votre meilleur actif.
Comptez les appels d'outils sur une session si vous évaluez l'index. C'est la métrique qu'il déplace et celle que vous pouvez vérifier vous-même.
Déconnectez ce que vous n'interrogez pas. Un manifeste de 48 outils sur une session purement terminal est une perte sèche.
Mesurez sur une semaine, pas sur une tâche. Ces deux outils n'ont pas du tout la même allure aux deux échelles.

Ce qui tourne mal (anti-patterns)

Lire un taux de compression par charge comme une économie de session. 92 % sur un blob et 53 % plus cher sur une session sont tous deux vrais de headroom. Prendre « non benchmarké » pour « ne marche pas ». tokensave ne publie aucun chiffre. C'est une preuve manquante, pas la preuve d'un échec. Faire tourner un compresseur au-dessus d'un index. L'index rend la fenêtre petite ; le compresseur déstabilise ensuite le préfixe qui venait de rétrécir. Vous cumulez les deux inconvénients. Ignorer le coût de manifeste d'une grosse surface MCP. Il est facturé à chaque tour, y compris ceux où vous ne touchez aucun de ces outils.

À lire aussi :

Réduire l'usage des tokens dans Claude Code — le pilier, indépendant de l'outil
Alternatives à headroom — le champ autour de headroom
tokensave vs codegraph — tokensave face à l'autre index de code
Benchmark des optimiseurs de tokens — la mesure ouverte derrière le résultat de headroom
Recherche sémantique vs grep — pourquoi indexer bat grepper, et où ça s'arrête