headroom vs token-optimizer : deux paris multicouches

Fait partie du pilier réduire l'usage des tokens dans Claude Code. Cette page oppose les deux outils les plus denses en fonctionnalités de la catégorie.

headroom ou token-optimizer : lequel choisir ?

token-optimizer, pour la plupart des gens — et si vous êtes une entreprise, lisez sa licence avant tout le reste. Les deux empilent plusieurs techniques plutôt que d'en parier une seule. La différence qui compte est l'endroit où ils interviennent : headroom réécrit le tableau de messages avant chaque appel API ; token-optimizer travaille surtout en amont, en remplaçant les gros fichiers par des cartes de structure AST et en surveillant la qualité du contexte pendant la session. Sur mon benchmark ouvert de sessions longues, headroom termine 53 % plus cher que sans aucun outil, dernier sur douze. token-optimizer n'y est pas passé. Je maintiens ce benchmark et je vends un outil concurrent : ce qui suit est un mécanisme, pas un classement.

Que fait token-optimizer exactement ?

Quatre couches, réellement différentes les unes des autres :

Les cartes de structure AST. Un fichier de 180K tokens devient environ 250 tokens de structure — signatures, symboles, forme. Soit 95–99 % de compression sur exactement la charge qui fait le plus mal, et ça marche parce que l'agent a en général besoin de savoir ce qu'il y a dans un fichier, pas de le lire.
La compaction intelligente à checkpoints progressifs. L'état de session est condensé à mesure qu'il grossit, au lieu d'être jeté et redémarré.
Un score de qualité à 7 signaux. Il guette la dégradation du contexte en cours de session — cette dérive lente où les réponses de l'agent empirent parce que sa fenêtre s'est remplie de bruit. Presque rien d'autre dans la catégorie ne modélise cela.
Un tableau de bord. Coûts par tour, mix de modèles, analyse du cache, répartition par sous-agent, adoption des skills, détection de dérive. En HTML complet, pas un tableau CLI.

Il fonctionne sur Claude Code, OpenCode, OpenClaw et Codex. Sa licence est PolyForm Noncommercial. Gratuit pour un usage personnel ou en petite équipe ; l'usage commercial exige une licence payante. Ce n'est pas une note de bas de page : c'est la première chose à vérifier si vous l'installez en entreprise, et c'est la plus grosse différence pratique entre les deux outils. headroom est en Apache 2.0, sans cette condition. Les autres coûts : une installation plus lourde sur les plateformes autres que Claude Code, une forte dépendance Python sur les environnements locaux, et aucune API transparente pour des intégrations tierces.

Que fait headroom exactement ?

Il compresse toute la fenêtre de conversation avant chaque appel API. 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 chaque contenu vers un compresseur spécifique à son 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. L'empreinte est lourde : Python 3.10+, un modèle ModernBERT de 150M de paramètres, détection Magika, 16 à 50 ms par appel.

Pourquoi le point d'intervention pèse-t-il autant ?

Parce que l'un des deux dépense le cache de prompts et l'autre non. 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, c'est-à-dire à chaque tour d'une boucle d'agent. Le cache rate, et vous repayez plein tarif un contexte déjà acheté. CacheAligner existe précisément pour combattre cela ; sur une longue boucle interactive, ça ne suffit pas. Une carte de structure AST n'a pas de problème équivalent. Elle remplace un fichier par une représentation plus petite avant que ce contenu n'entre dans la fenêtre : ce que le fournisseur met en cache reste stable. L'économie est encaissée une fois, et elle reste encaissée. C'est la même raison pour laquelle headroom a un second chemin d'échec que token-optimizer n'a pas : quand une charge compressée se révèle insuffisante, le modèle appelle headroom_retrieve et rapatrie l'original, donc vous avez payé la copie compressée, l'original, et l'aller-retour.

Que vaut le score de qualité ?

Plus que sa place dans la liste de fonctionnalités ne le laisse croire. Tous les autres outils d'ici optimisent le coût et vous laissent découvrir vous-même le coût en qualité. Un score de dégradation à 7 signaux est une tentative de rendre l'arbitrage visible pendant la session, au lieu d'après une mauvaise réponse. Sa justesse, je ne peux pas la vérifier de l'extérieur, et vous non plus sans le faire tourner. Mais c'est le seul outil de cette comparaison qui traite « la compression a-t-elle dégradé l'agent » comme une question mesurable plutôt que comme un risque accepté. Ce cadrage est le bon, même si la mise en œuvre s'avère imparfaite.

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

Les sorties de commandes en limite d'outil. headroom les compresse dans la fenêtre, après qu'elles ont été produites et payées une fois. La compaction de token-optimizer est une opération au niveau session, pas un filtre par commande.
Les manifestes MCP. Chaque serveur connecté envoie ses définitions d'outils avant votre premier message, utilisées ou non. Aucun ne les diffère.
La recherche sémantique de code. Aucun ne remplace une recherche par une réponse ciblée.
Les relectures. Même fichier, quatre fois, quatre facturations.

Lequel choisir ?

Prenez token-optimizer si vous êtes un individu ou une petite équipe, que vous travaillez dans Claude Code, et que vos tokens partent dans les gros fichiers. La carte de structure AST est le mécanisme unique le plus fort de cette comparaison, et le tableau de bord vous permet de voir si ça a marché. Vérifiez d'abord la licence si vous êtes une entreprise. PolyForm Noncommercial implique une licence payante pour l'usage commercial. Décider après le déploiement est l'ordre coûteux. 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.

Comment appliquer ça aujourd'hui

Vérifiez votre exposition en matière de licence avant d'installer quoi que ce soit. Deux minutes, et c'est irréversible si vous vous trompez à l'échelle.
Regardez votre taux de hit de cache avant d'installer un réécriveur de fenêtre. S'il est élevé, c'est l'actif que vous dépenseriez.
Trouvez vos plus grosses lectures de fichiers. Si une poignée de gros fichiers domine, une carte de structure est le changement unique le plus rentable à votre portée.
Mesurez sur une semaine, pas sur une tâche. Les effets de compression et de cache divergent à ces échelles.

Ce qui tourne mal (anti-patterns)

Déployer en entreprise un outil sous licence non commerciale. L'erreur la plus coûteuse de cette page, et elle n'a rien à voir avec les tokens. 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. Empiler les deux. La carte de structure rend la fenêtre petite ; le réécriveur déstabilise ensuite le préfixe qui venait de rétrécir. Supposer qu'un outil non mesuré est sans risque. L'absence de token-optimizer du benchmark est une preuve manquante, pas un certificat de bonne santé.

À lire aussi :