Qu’est-ce que Headroom ?
Headroom compresse ce que lit un agent d'IA avant que cela n'atteigne le modèle : résultats d'outils, journaux, résultats de recherche, fragments RAG, fichiers et historique. Un routeur détecte le type de contenu et confie le JSON à un compresseur statistique, le code source à un compresseur qui comprend l'AST et la prose à Kompress-v2-base, un petit modèle que l'équipe a entraîné sur des traces d'agents. Les originaux sont mis en cache en local pour que le modèle puisse redemander le texte complet.
Il se présente comme une bibliothèque Python et TypeScript (`headroom-ai`), un proxy sur le port 8787, un enrobage en une commande pour Claude Code, Codex, Copilot, Aider et une quinzaine d'autres agents, et un serveur MCP. Parmi les extras figurent une mémoire partagée entre agents, `headroom learn`, qui fouille les sessions ratées pour écrire des corrections dans `CLAUDE.md`, et un réducteur de sortie optionnel. Headroom Labs vend une édition entreprise à côté du code sous Apache 2.0.
Headroom vaut-il le coup ?
Le projet publie des chiffres reproductibles plutôt qu'un seul chiffre d'accroche. Sur quatre scénarios à graine fixe, construits à partir de vrais formats de sortie MCP, il a réduit les tokens d'entrée de 21 % pour la recherche de code, 42 % pour l'exploration d'une base de code, 30 % pour le tri d'issues et 57 % pour le débogage d'incidents, et les tableaux JSON et lignes de journal répétés dépassent 90 %. La prose ne rétrécit guère. La compression prend 0,21 ms en médiane sur un résultat JSON de 10 000 tokens, sans effet visible sur la latence, et sur de petites batteries de précision (100 questions chacune) les scores sont restés dans la marge d'erreur.
L'usage indépendant raconte la même histoire, avec un éclairage moins flatteur. Le blog russ.cloud l'a utilisé quelques jours en programmation interactive mixte et a vu 20,7 % de tokens en moins sur 1,9 million, mais les économies en dollars du tableau de bord venaient surtout de la remise de cache de prompts du fournisseur lui-même (47,36 $) plutôt que de la compression (9,23 $), avec 304 ms de surcoût du proxy par requête ; son auteur a trouvé `headroom learn` plus utile que le compresseur. Une deuxième critique a confirmé que les comptes de tokens correspondent aux relevés du fournisseur, mais doutait que la facture baisse toujours.
L'adoption est réelle et pas seulement virale : 466 346 téléchargements PyPI le mois dernier et 125 494 sur npm, pour 79 667 étoiles et 3 730 commits. Les versions sont fréquentes ; v0.44.0 est sortie le 10 novembre 2026.
Le hic : une balise de télémétrie anonyme est activée par défaut (taux de compression, identifiants de fournisseur et de modèle, système ; ni prompts ni code), et le proxy se trouve sur le chemin de chaque clé d'API et de chaque requête. Deux avis ont été publiés, un détournement de WebSocket intersite de gravité élevée en août et une lecture arbitraire de fichiers dans l'outil de lecture du serveur MCP le 9 novembre 2026, tous deux corrigés.
Notre avis : sur un agent qui lit de gros volumes JSON, des journaux ou des résultats de recherche, il se rentabilise ; pour la programmation ordinaire en mode conversation, les filtres de commandes de RTK font une bonne partie du même travail avec moins de mécanique.
Là où il fait la différence
Une équipe SRE qui débogue des incidents avec Claude Code
Empêcher les vidages de journaux et le JSON de métriques de remplir la fenêtre de contexte
`headroom wrap claude` lance un proxy local pour la session ; le scénario d'incident du projet est passé de 55 957 à 24 340 tokens. Le modèle peut toujours récupérer les lignes d'origine via l'outil de récupération quand il en a besoin.
Un développeur backend qui exploite une API RAG en Python
Réduire le coût d'entrée sur de longues listes de fragments récupérés et de lignes de base de données
Appelez `compress(messages, model=...)` avant l'appel au fournisseur ; il tourne dans le processus, sans clé ni réseau. Lancez d'abord `headroom evals` sur votre propre trafic, comme le conseillent les critiques, pour vérifier que les réponses ne changent pas.
Une ingénieure qui corrige sans cesse les mêmes erreurs de l'agent
Transformer les échecs répétés en consignes permanentes
`headroom learn` lit les sessions passées et écrit des corrections dans `CLAUDE.local.md` ou `AGENTS.md` ; un testeur indépendant y a vu la partie la plus utile. Cela ne coûte rien de plus que l'exécution.
Avant de vous engager
- Mise en route
- `uv tool install --python 3.13 "headroom-ai[all]"`, puis `headroom wrap claude` (ou codex, copilot, aider et d'autres) ; `headroom doctor` vérifie le routage. Bibliothèques : `pip install headroom-ai` ou `npm install headroom-ai`.
- Intégrations
- Claude Code, Codex, Copilot CLI et VS Code, Cursor (manuel), Aider, OpenCode, Cline, Continue, Goose, OpenHands et d'autres ; enrobages pour les SDK d'Anthropic, d'OpenAI et de Vercel AI ; LiteLLM, LangChain, Agno et Strands ; serveur MCP.
- Données et confidentialité
- La compression tourne en local et les originaux sont mis en cache sur votre machine. Une balise anonyme envoie par défaut taux, compteurs, identifiants de fournisseur et de modèle, système et architecture ; `HEADROOM_TELEMETRY=off` ou `DO_NOT_TRACK=1` l'arrête.
- Coût à grande échelle
- Aucun coût de licence. Le gain croît avec la répétition : 90 % ou plus sur du JSON et des journaux répétés, environ 20 % sur des sessions de programmation mixtes dans un test indépendant ; le cache de prompts couvre peut-être déjà une bonne part de l'économie en dollars.
- Limites
- La prose et les prompts courts se compressent à peine ; la CLI exige Python ; les fournisseurs tiers compatibles OpenAI demandent une URL amont explicite, sinon la clé part chez OpenAI ; 302 issues ouvertes.
Les points forts
- Tests reproductibles avec des chiffres honnêtes par scénario
- Compression locale et réversible à la demande
- Bibliothèque, proxy, enrobage d'agents et serveur MCP dans un seul paquet
- Usage réel important : 466 346 téléchargements PyPI en un mois
Les points faibles
- Peu de gain sur la prose et la programmation interactive
- Balise de télémétrie activée par défaut
- Le proxy voit chaque clé et chaque requête ; deux avis depuis août
- Fonctionnalités qui débordent largement de la compression
Idéal pour
Équipes dont les agents ou chaînes RAG envoient au modèle beaucoup de JSON, de journaux ou de résultats de recherche et paient au token d'entrée.
Alternatives à Headroom
Headroom : questions fréquentes
- Headroom vaut-il le coup ?
- Headroom est le plus rigoureux des modules d'économie de tokens, et ses propres chiffres montrent que le gain dépend presque entièrement de la répétitivité des sorties de vos outils. Nous lui donnons 3.9 sur 5.
- Combien coûte Headroom ?
- Gratuit et open source (Apache 2.0). Headroom Enterprise pour les équipes est vendu à part ; tarifs non publiés.
- Quels sont les inconvénients de Headroom ?
- Peu de gain sur la prose et la programmation interactive; balise de télémétrie activée par défaut; le proxy voit chaque clé et chaque requête ; deux avis depuis août; fonctionnalités qui débordent largement de la compression.
- À qui s’adresse Headroom ?
- Équipes dont les agents ou chaînes RAG envoient au modèle beaucoup de JSON, de journaux ou de résultats de recherche et paient au token d'entrée.
- Combien coûte Headroom pour une équipe ou en production ?
- Aucun coût de licence. Le gain croît avec la répétition : 90 % ou plus sur du JSON et des journaux répétés, environ 20 % sur des sessions de programmation mixtes dans un test indépendant ; le cache de prompts couvre peut-être déjà une bonne part de l'économie en dollars.
- Headroom est-il sûr pour les données de l’entreprise ?
- La compression tourne en local et les originaux sont mis en cache sur votre machine. Une balise anonyme envoie par défaut taux, compteurs, identifiants de fournisseur et de modèle, système et architecture ; `HEADROOM_TELEMETRY=off` ou `DO_NOT_TRACK=1` l'arrête.
- Quelles sont les meilleures alternatives à Headroom ?
- Les alternatives les plus proches que nous avons testées sont rtk (Rust Token Killer), Caveman et OmniRoute.
Réponses vérifiées le 14 nov. 2026.