Fait partie du pilier réduire l'usage des tokens dans Claude Code. Cette page est le face-à-face : deux outils Python avec des théories opposées sur l'endroit où se trouve le gaspillage.
À lire aussi :
headroom ou graphify : lequel convient ?
graphify si la connaissance de votre projet vit hors des sources ; headroom seulement si votre charge est batch plutôt qu'interactive. headroom réduit le tableau de messages avant chaque appel API. graphify construit une carte interrogeable du projet — code, documentation, PDF, images, vidéo — pour que l'agent interroge la carte au lieu de lire des fichiers. Les deux sont gratuits, les deux sont en Python, et aucun n'affiche d'économie de coût mesurable sur mon benchmark ouvert de sessions longues. headroom fait pire : il termine 53 % plus cher que sans aucun outil, dernier sur douze. Je maintiens ce benchmark et je vends un outil concurrent : ce qui suit est le mécanisme, pas le tableau de scores.Que fait headroom exactement ?
Il réécrit la fenêtre de conversation avant chaque appel. SDK Python, proxy CLI et serveur MCP, Apache 2.0, environ 18,7k étoiles.CacheAligner sort timestamps et UUID du préfixe statique vers une queue non cachée ; ContentRouter route les contenus vers des compresseurs spécifiques à leur format via détection ML — JSON, code, texte, logs, diffs, HTML ; IntelligentContext note ce qui reste sur six dimensions de pertinence.
C'est réversible : les originaux vivent dans un cache LRU local avec un outil headroom_retrieve injecté et une sous-recherche BM25 optionnelle. La compression par charge est forte — 92 % sur les résultats de recherche de code et les logs d'incidents SRE, 73 % sur le triage d'issues — et SmartCrusher échantillonne les grands tableaux JSON à 70–95 % en préservant toujours les lignes d'erreur.
L'empreinte est lourde : Python 3.10+, un modèle ModernBERT de 150M de paramètres, détection Magika, 16 à 50 ms par appel.
Que fait graphify exactement ?
Il cartographie le projet dans un graphe de connaissances que l'agent peut interroger. Python, licence MIT, installable depuis PyPI, invoqué par une commande/graphify sur Claude Code, Codex, opencode, Cursor, Copilot, Aider, OpenClaw et d'autres.
Sa particularité, c'est ce qu'il ingère. La plupart des outils de la catégorie indexent le code source et s'arrêtent là. graphify prend aussi la documentation, les PDF, les images et la vidéo — ce qui compte dans les projets où la réponse à « pourquoi est-ce construit ainsi » vit dans un document de conception, une spécification scannée ou un enregistrement de passation plutôt que dans un corps de fonction.
Il produit aussi un artefact persistant et inspectable : graph.json, plus une vue HTML et un rapport Markdown. Le graphe peut être interrogé plus tard sans relire le dépôt, et la vue HTML permet à une personne d'auditer l'index au lieu de lui faire confiance à l'aveugle. C'est plus rare que ça ne devrait l'être.
Le coût, c'est que l'indexation est une étape explicite à relancer à mesure que le projet bouge, et qu'un graphe périmé n'échoue pas bruyamment : il induit en erreur en silence.
Comment chacun échoue-t-il ?
C'est la comparaison utile, parce que les deux échouent, et pas de la même façon. headroom échoue en dépensant le cache de prompts. Le cache ne paie que si le préfixe est identique octet pour octet entre les tours, et l'entrée en cache est facturée une fraction de l'entrée fraîche chez tous les grands fournisseurs. Un réécriveur de fenêtre change le préfixe dès que ses décisions de compression changent — donc à chaque tour, puisque le contenu change. 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 voit le risque ; sur une longue boucle interactive, ça ne suffit pas.
Il a un second chemin d'échec : quand la version compressée se révèle insuffisante, le modèle appelle headroom_retrieve et rapatrie l'original. Vous avez alors payé la copie compressée, l'original, et l'aller-retour.
graphify échoue en n'étant pas consulté. Une commande slash est opt-in : l'agent n'interroge le graphe que si quelque chose l'y conduit. Ajoutez le coût propre de la passe d'indexation, et un graphe qui a dérivé de l'arbre de travail, et l'agent peut dépenser des tokens à réconcilier la carte et le territoire.
La différence de gravité compte. L'échec de headroom est systématique : il s'applique à chaque appel. Celui de graphify est situationnel : il s'applique quand vous oubliez de réindexer ou n'invoquez jamais l'outil. L'un est un multiplicateur, l'autre une occasion manquée.
À quelles sessions chacun convient-il ?
headroom convient au batch. 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. Ce n'est pas une boucle de code agentique. graphify convient aux projets riches en documents. Travail réglementé avec spécifications, passations de conseil, tout ce où un PDF ou une session enregistrée détient une connaissance absente des sources. Si votre dépôt est du code pur avec un README maigre, le différenciateur de graphify ne s'applique pas à vous, et un index limité aux sources sera plus simple.Que ne fait ni l'un ni l'autre ?
- Les sorties de commandes en limite d'outil. graphify ne les voit jamais. headroom les compresse dans la fenêtre, après qu'elles ont été produites et payées une fois.
- Les relectures. Même fichier, quatre fois, quatre facturations. Aucun ne déduplique.
- Les manifestes MCP. Chaque serveur connecté envoie ses définitions d'outils avant votre premier message. Aucun ne les diffère.
- Les lectures de fichiers entiers pour éditer. Une carte dit quel fichier ; un compresseur le réduit et met le cache en danger.
Comment appliquer ça aujourd'hui
- Vérifiez d'abord votre taux de hit de cache. S'il est élevé, n'installez pas un réécriveur de fenêtre sans mesurer avant et après. Ce seul chiffre décide de tout le cas headroom.
- Demandez-vous si la connaissance de votre projet est dans les sources. Si oui, l'ingestion non-code de graphify ne vous apporte rien. Si non, rien d'autre dans la catégorie ne la propose.
- Rattachez la réindexation à un événement, pas à votre mémoire — un changement de branche, un passage quotidien. Un graphe périmé est pire que pas de graphe.
- Mesurez sur une semaine. Ces deux outils n'ont pas la même allure à l'échelle de la tâche et à celle de la semaine, et c'est la semaine que vous payez.
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. Installer un graphe que vous n'interrogez jamais. Le coût d'indexation est réel et le gain nul si l'agent ne demande rien. Faire tourner les deux. Le graphe réduit ce qui entre dans la fenêtre ; le compresseur déstabilise ensuite le préfixe que le graphe venait de rétrécir. Vous cumulez les inconvénients sans aucun avantage. Faire confiance à un index périmé. Une réponse fausse mais assurée coûte plus cher que pas de réponse.À 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
- rtk vs graphify — graphify face à un filtre de sorties shell
- Benchmark des optimiseurs de tokens — la mesure ouverte derrière les deux résultats
- Recherche sémantique vs grep — pourquoi indexer bat grepper, et où ça s'arrête
Classé n°1 au Token-Harness Optimizer Leaderboard.
Tokenade est classé n°1 au Token-Harness Optimizer Leaderboard — un benchmark de bout en bout des optimiseurs de tokens, mesuré sur de vraies sessions de code. Installez-le une fois, il agit sur chaque prompt. Compatible avec Claude Code, Cursor, Codex, Copilot et plus.
