headroom vs ccusage : mesurer d'abord, compresser ensuite

Fait partie du pilier réduire l'usage des tokens dans Claude Code. Cette page est le face-à-face, et la comparaison est moins déséquilibrée que les catégories ne le laissent croire.

headroom ou ccusage : de quoi ai-je besoin ?

ccusage d'abord, puis on décide pour headroom — parce que ccusage est ce qui vous dira si headroom vous aide ou vous coûte. Ce ne sont pas des concurrents. ccusage mesure et ne change rien ; headroom compresse votre tableau de messages et change beaucoup de choses. La raison de les mettre sur la même page, c'est que headroom est l'outil de la catégorie le plus susceptible de produire un résultat que vous ne remarqueriez jamais sans compteur. Sur mon benchmark ouvert de sessions longues, headroom termine 53 % plus cher que sans aucun outil — dernier des douze outils testés. Ce n'est pas une affirmation à me croire sur parole. C'est une affirmation que vous devez pouvoir vérifier sur votre propre machine, et ccusage est ce qui vous le permet. Je maintiens ce benchmark et je vends un outil concurrent. Lisez ceci comme un plaidoyer pour la mesure, pas comme un tableau de scores.

Que fait ccusage exactement ?

Il lit les transcriptions JSONL locales de votre agent et rapporte ce que vous avez dépensé. Environ 15k étoiles, 15 sources d'agents supportées, zéro installation — bunx ccusage ou npx ccusage@latest. Rapports quotidiens, hebdomadaires, mensuels et par session, répartition par modèle, suivi des tokens de cache, et une sortie JSON qui se compose avec d'autres tableaux de bord. La fonctionnalité qui compte le plus pour les abonnés Claude Pro et Max est la vue par bloc de facturation de 5 heures. Les limites d'Anthropic se réinitialisent sur une fenêtre glissante de cinq heures, et ccusage est l'outil qui vous montre où vous en êtes dedans plutôt qu'après. Ses limites sont honnêtes et annoncées : il est en lecture seule et ne réduit rien. Il ne peut pas non plus vous dire ce que vous auriez dépensé sans tel outil — il rapporte la dépense observée, pas un contrefactuel. Et le schéma JSONL qu'il lit est implicite plutôt que spécifié : il suit ce que les agents écrivent, tel qu'ils l'écrivent.

Que fait headroom exactement ?

Il compresse l'ensemble du tableau de messages avant chaque appel API. SDK Python, proxy CLI et serveur MCP, Apache 2.0, environ 18,7k étoiles. CacheAligner stabilise le préfixe statique du prompt en déplaçant timestamps et UUID en queue non cachée ; ContentRouter envoie 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 et le modèle peut appeler un outil headroom_retrieve injecté, avec sous-recherche BM25 optionnelle. Les chiffres par charge sont forts — 92 % sur les résultats de recherche de code et les logs d'incidents SRE, 73 % sur le triage d'issues. L'empreinte est réelle : Python 3.10+, un modèle ModernBERT de 150M de paramètres, Magika pour la détection de contenu, et 16 à 50 ms de surcoût par appel.

Pourquoi un compresseur peut-il rendre une session plus chère ?

Parce que le cache de prompts ne paie que si le préfixe est stable, et qu'un réécriveur de fenêtre le déstabilise. L'entrée en cache est facturée une fraction de l'entrée fraîche chez tous les grands fournisseurs. Quand les décisions de compression changent d'un tour à l'autre — et elles changent, puisque le contenu change — le préfixe change, le cache rate, et vous repayez plein tarif un contexte déjà acheté. CacheAligner existe précisément pour combattre cela, ce qui montre que le projet a identifié le risque. Sur une longue boucle d'agent, ça ne suffit pas. Il existe un second chemin vers le même résultat. 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 entre les deux. Rare sur une tâche courte ; cumulatif sur une session. C'est exactement le mode de défaillance qu'un compteur attrape et que l'intuition rate. Chaque compression individuelle ressemble à un gain. La perte apparaît sur la facture, et la facture est ce que lit ccusage.

Que vous dit le compteur que le compresseur ne peut pas dire ?

Quatre choses, et chacune correspond à une décision :

Votre répartition entrée/sortie. Si l'entrant domine le sortant d'un facteur dix — c'est généralement le cas — les outils côté sortie sont le mauvais premier geste.
Votre taux de hit de cache. C'est le chiffre à regarder avant d'installer quoi que ce soit qui réécrit la fenêtre. Un taux élevé est un actif qu'un compresseur va dépenser.
Votre distribution par modèle. Si un modèle se vide bien plus vite que les autres, c'est une question de routage avant d'être une question d'optimisation.
Où vous en êtes dans le bloc de cinq heures. Utile en soi, indépendamment de tout optimiseur.

Rien de tout cela ne réduit un seul token. Tout cela décide quelle réduction vaut la peine d'être tentée.

Où le compteur s'arrête-t-il ?

Il rapporte ce qui s'est passé, pas ce qui l'a causé. ccusage vous dira qu'une session a coûté plus que d'habitude. Il ne vous dira pas que onze de vos vingt derniers appels d'outils ont relu les quatre mêmes fichiers, ni qu'une charge compressée a été rapatriée en entier. Il n'a pas non plus de base de référence. Aucune vue « ce que j'aurais dépensé sans l'outil X », donc l'A/B, c'est à vous de le faire : une semaine avec, une semaine sans, du travail comparable. C'est plus de discipline que la plupart des gens n'en appliquent, et c'est le seul moyen que l'effet d'un outil sur votre dépôt devienne un fait plutôt qu'une promesse d'éditeur.

Lequel choisir ?

Installez ccusage dans tous les cas. Gratuit, sans installation, en lecture seule, et c'est l'instrument dont dépend toute autre décision de cette page. Il n'existe aucun scénario où vous êtes perdant à connaître le chiffre. Installez 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. N'installez pas headroom sur une boucle d'agent interactive sans mesurer avant et après. Le benchmark dit qu'il peut vous coûter ; ce sont vos propres chiffres qui trancheront pour votre dépôt.

Comment appliquer ça aujourd'hui

Lancez npx ccusage@latest maintenant. Quelques secondes, rien à installer, et il lit des transcriptions que vous avez déjà.
Notez trois chiffres : ratio entrée/sortie, taux de hit de cache, répartition par modèle. C'est votre base de référence, et elle vaut plus que n'importe quelle comparaison d'outils.
Changez une chose à la fois. Deux outils installés la même semaine produisent un résultat ininterprétable.
Relisez le compteur après une semaine, pas après une tâche. Les effets de compression et de cache divergent à ces deux échelles, et c'est la semaine que vous payez.

Ce qui tourne mal (anti-patterns)

Installer un optimiseur avant un compteur. Vous ne saurez jamais s'il a marché, et l'un des outils de cette page est mesurablement capable d'aggraver les choses. Se fier aux taux de compression par charge. 92 % sur un blob et 53 % plus cher sur une session sont tous deux vrais de headroom, et ne se contredisent pas. Prendre ccusage pour un optimiseur. Il n'économise rien. Sa valeur est entièrement dans ce que vous faites du chiffre. Changer deux choses à la fois. La façon la plus courante de transformer une semaine de mesure en aucune conclusion utilisable.

À lire aussi :