Headroom : compression de contexte locale d'abord pour les agents IA
Compressez les sorties de l'outil, les journaux, les fichiers et les morceaux RAG avant qu'ils n'atteignent le LLM. 20 % de jetons en moins pour les agents de codage, 60 à 95 % de jetons en moins pour JSON, mêmes réponses. Bibliothèque, proxy, serveur MCP.
En bref
- De quoi s’agit-il ?
- Une bibliothèque Python et TypeScript, un proxy et un serveur MCP qui compressent les sorties d'outils, les journaux, les morceaux RAG et l'historique de conversation avant qu'ils n'atteignent le LLM.
- À qui s’adresse-t-il ?
- Headroom est une couche de compression locale d'abord avec un pipeline documenté, plusieurs modes d'intégration et des chiffres d'économie auto-déclarés. Le dépôt ne fournit pas de vérification indépendante de ces chiffres, ni ne décrit d'audits de sécurité ou de conditions de garantie au-delà de la licence Apache 2.0.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Compression avant que le modèle ne le voie
Headroom est une bibliothèque Python et TypeScript, un proxy et un serveur MCP qui compresse le matériel lu par un agent IA : sorties d'outils, journaux, morceaux RAG, fichiers et historique de conversation. Le README le positionne comme une couche locale d'abord : le proxy s'exécute sur votre machine et les originaux sont mis en cache localement pour une récupération à la demande via CCR, donc la compression est réversible. Le dépôt affirme des réductions de tokens de 60 à 95 pour cent pour les données JSON et de 15 à 20 pour cent pour les agents de codage, avec les mêmes réponses. Ces chiffres apparaissent dans la bannière d'ouverture et dans les tableaux de preuve du README ; la source ne les vérifie pas indépendamment.
Le pipeline de routage et de compression
Le README décrit un pipeline avec des étapes distinctes. ContentRouter détecte le type de contenu et sélectionne un compresseur : SmartCrusher pour JSON, CodeCompressor pour les AST de plusieurs langages, et Kompress-v2-base, un modèle HuggingFace entraîné sur des traces d'agents, pour la prose. CacheAligner inspecte les invites pour détecter les contenus volatils qui pourraient invalider les préfixes de cache KV du fournisseur et avertit sans réécrire. CCR stocke les originaux localement afin que le LLM puisse appeler headroom_retrieve lorsqu'il a besoin du texte complet. La compression de zone vive ne compresse que les nouveaux octets, laissant le préfixe figé identique octet par octet pour préserver le cache du fournisseur. Le README énumère également un cycle de vie de Setup à Response Received, avec des transformations et des hooks d'extension.
Chemins d'installation et frontière CLI
L'installation est proposée via plusieurs canaux. uv tool install --python 3.13 "headroom-ai[all]" installe la CLI dans un environnement isolé ; pip install "headroom-ai[all]" inclut la commande headroom ; npm install headroom-ai fournit uniquement le SDK TypeScript, sans CLI. Les images Docker sont disponibles via ghcr.io/chopratejas/headroom. Python 3.10 ou plus récent est requis. Le README mentionne des extras granulaires tels que [proxy], [mcp], [ml], [code], [memory], [vector] et autres, et avertit que [all] exclut les adaptateurs de frameworks comme LangChain et Agno. La CLI est distribuée uniquement via le paquet PyPI ; le paquet npm est un import de bibliothèque.
Économies signalées et chiffres de référence
La section preuve rapporte des économies de tokens sur quatre charges de travail : recherche de code (92 %), débogage d'incident SRE (92 %), triage de problèmes GitHub (73 %) et exploration de codebase (47 %). Les benchmarks montrent une précision GSM8K inchangée à 0,870, TruthfulQA passant de 0,530 à 0,560, et SQuAD v2 et BFCL tous deux à 97 % avec respectivement 19 % et 32 % de compression. Le README fournit une commande de reproduction : python -m headroom.evals suite --tier 1. Ce sont des chiffres auto-déclarés ; la vérification indépendante n'est pas décrite dans le dépôt.
Façonnement des tokens de sortie
Au-delà de la compression d'entrée, Headroom peut réduire les tokens de sortie en ajoutant une note de concision à la fin du prompt système et en réduisant l'effort de réflexion sur les tours de routine. Cela est désactivé par défaut, activé avec HEADROOM_OUTPUT_SHAPER=1. Le proxy lit le réglage en direct sur chaque requête, et headroom wrap synchronise à chaud les réglages actuels via un endpoint de bouclage. headroom learn --verbosity peut déduire la concision souhaitée des sessions passées. Les économies de sortie sont rapportées comme une estimation avec un intervalle de confiance, ou comme mesurées si un groupe de retenue est configuré avec HEADROOM_OUTPUT_HOLDOUT=0.1. Le README dit que l'estimation est honnête et jamais un nombre inventé.
Wrappers d'agents et matrice d'intégration
La matrice de compatibilité des agents liste les wrappers pour Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Cortex Code, Kimi CLI et ZCode. La plupart supportent headroom wrap ; Cursor et ZCode impriment les URL de base pour la configuration manuelle ; Cortex Code est uniquement bibliothèque. Le wrapper peut installer Serena pour la navigation sémantique dans le code. Unwrap est supporté pour plusieurs outils. Une section séparée couvre le mode abonnement GitHub Copilot CLI, qui échange un jeton OAuth et route via le proxy. Pour VS Code Copilot, headroom wrap vscode remplace le endpoint du proxy API sans patcher VS Code. Claude Code dans VS Code utilise headroom wrap vscode-claude. Le README note que certains chemins de découverte d'authentification sous Windows et Linux nécessitent encore une validation.
Offre équipe, licence et ce que la source ne dit pas
Le README déclare que Headroom OSS est construit pour les développeurs individuels, tandis qu'une offre gérée est disponible pour les organisations. Tout dans le dépôt reste sous Apache 2.0. L'extrait de licence accorde une licence de droit d'auteur perpétuelle, mondiale, non exclusive, gratuite et irrévocable pour reproduire, préparer des œuvres dérivées et distribuer, plus une licence de brevet soumise à résiliation en cas de litige de brevet. Le texte de licence ne dit rien sur le support, la garantie ou la posture de sécurité ; le README ne décrit pas non plus d'audits de sécurité indépendants ou de garanties de performance au-delà des benchmarks rapportés. Pour les équipes, le README pointe vers un contact par e-mail plutôt que de détailler les prix ou les niveaux de service.
Ce que le dépôt permet de vérifier · headroomlabs ai headroom
La vérification doit suivre les commandes et fichiers propres à AI Headroom, puis mesurer séparément la consommation du contexte et le résultat produit par chaque intégration listée. Commencez par l'installation décrite dans le README, lancez l'exemple minimal, et consignez la version des dépendances ainsi que les variables de configuration utilisées. Comparez ensuite une requête courte et une requête proche de la limite annoncée, en observant les journaux, les erreurs et la sortie persistée. Les capacités présentées par le dépôt ne constituent pas une promesse de qualité générale : le README ne remplace ni une mesure de coût ni un audit des permissions. La décision dépendra du fournisseur de modèle, du mode d'exécution et du niveau de contrôle attendu sur les données. Il faut aussi vérifier les tests du dépôt et les workflows avant d'accorder une place à AI Headroom dans un service automatisé.
Conclusion éditoriale
Headroom est une couche de compression locale d'abord avec un pipeline documenté, plusieurs modes d'intégration et des chiffres d'économie auto-déclarés. Le dépôt ne fournit pas de vérification indépendante de ces chiffres, ni ne décrit d'audits de sécurité ou de conditions de garantie au-delà de la licence Apache 2.0. Les équipes envisageant une utilisation en production devraient traiter les chiffres de référence comme des affirmations à reproduire plutôt que comme des résultats garantis.
Notes de la communauté