Headroom : compression de contexte LLM pour agents de code

Headroom compression de contexte LLM : Apache-2.0, installation d’après le README, tableau de bord et mesure des tokens avec OpenTelemetry.
Headroom : compression de contexte LLM pour agents de code

Headroom, compression de contexte LLM pour agents de code : le projet se présente comme une couche qui compresse tout ce que lit un agent (sorties d’outils, journaux, extraits RAG, fichiers, historique) avant que cela n’atteigne le modèle. Le dépôt headroomlabs-ai/headroom affiche environ 77 500 étoiles à la fin octobre 2026, sous licence Apache-2.0.

Moins de tokens en entrée, c’est moins de coût et moins de compactions, mais seulement si la compression ne détruit pas l’information utile. Cet article résume ce que fait le projet d’après son README, montre son tableau de bord, détaille l’installation, puis explique comment mesurer vous-même les économies avec ses métriques Prometheus et OpenTelemetry. Précision d’honnêteté : span.observer n’a pas installé Headroom ; les commandes viennent du README et de la documentation du projet, et les captures viennent du dépôt.

Headroom : compression de contexte LLM, ce que dit le dépôt

  • Qui : l’organisation headroomlabs-ai ; la documentation est hébergée sur docs.headroomlabs.ai.
  • Licence : Apache-2.0 (fichier LICENSE du dépôt).
  • Chiffres relus le 22 octobre 2026 : environ 77 500 étoiles, environ 6 000 forks, 3 324 commits ; le pyproject.toml de la branche principale indique la version 0.41.0 du paquet headroom-ai, qui demande Python 3.10 ou plus récent.
  • Quatre usages d’après le README : une bibliothèque (compress(messages) en Python ou TypeScript), un proxy (headroom proxy --port 8787), l’enveloppe d’agent (headroom wrap claude, codex, cursor, aider, opencode…) et un serveur MCP.

Le mécanisme décrit : un routeur de contenu détecte le type de données et choisit un compresseur (JSON, code par arbre syntaxique, texte avec un modèle publié sur Hugging Face). Les originaux sont gardés en local (« CCR ») et le modèle peut les redemander via l’outil headroom_retrieve. Le projet affirme que la compression se fait sur votre machine, sans envoyer le contenu ailleurs pour le compresser. Cette idée est voisine de celle de context-mode, qui garde la sortie brute hors du contexte avec une autre mécanique et une autre licence.

Visite du tableau de bord

La commande headroom dashboard ouvre, proxy lancé, un tableau de bord. La capture ci-dessous vient du dépôt : elle montre l’état de santé, les requêtes terminées, échouées ou limitées, les tokens économisés, le coût, la surcharge ajoutée par le proxy (en millisecondes), l’usage par type de contenu supprimé (« JSON Bloat », « Repetition ») et l’impact sur le cache de préfixe du fournisseur.

Tableau de bord Headroom du dépôt : requêtes terminées, tokens économisés 143,0k soit 36,9 %, surcharge de 14 ms, usage de tokens avant et après compression, impact sur le cache de préfixe et requêtes récentes
Source : github.com

Ce sont des valeurs d’exemple du projet, pas des mesures de span.observer. Le tableau de bord prévoit aussi une sortie de tokens économisés estimée lorsque la mise en forme de la sortie est activée (HEADROOM_OUTPUT_SHAPER=1, désactivée par défaut).

La deuxième image du dépôt montre un compteur « Community savings » agrégé. Le README ne détaille pas, dans le passage consulté, comment ce chiffre est collecté : prenez-le comme une donnée du projet, non vérifiée, et lisez la section Limites sur la balise de télémétrie.

Image du dépôt Headroom : compteur Community savings de 59,0 milliards de tokens économisés, quatre tuiles (coût économisé, requêtes optimisées, instances actives, jours actifs) et courbe des tokens économisés sur 48 heures
Source : github.com

Installation pas à pas

Étape 1 — Installer la CLI

Le README donne, au choix :

uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
npm install headroom-ai     # SDK TypeScript seulement, sans CLI

Une image Docker est aussi indiquée (ghcr.io/headroomlabs-ai/headroom:latest). Pour limiter la surface, le README liste des extras granulaires ([proxy], [mcp], [ml], [otel]…).

Étape 2 — Choisir un mode

headroom wrap claude          # enveloppe un agent de code
headroom proxy --port 8787    # proxy sans changer le code
headroom mcp install          # serveur MCP (headroom_compress, headroom_retrieve, headroom_stats)

Le README précise que headroom wrap démarre un proxy local, installe le serveur Serena pour la navigation de code et lance l’agent configuré pour passer par Headroom ; headroom unwrap annule. Lisez cette partie avant de l’utiliser : elle modifie la configuration de votre agent.

Étape 3 — Vérifier

headroom doctor      # contrôle de santé
headroom perf        # performances
headroom dashboard   # économies en direct (proxy lancé)

Limites et points ouverts

  • Les chiffres sont ceux du projet : le README publie un tableau de quatre scénarios (de 21 % à 57 % d’économie) mesurés avec le tokenizer du fournisseur, reproductibles avec benchmarks/index_proof_table.py --seed 20260902. Il précise lui-même que les gains dépendent de la répétitivité des données et que la prose ou les sorties déjà denses se compressent très peu.
  • Précision : les tests d’exactitude du README montrent, à N=100, un delta de ±0,03 qu’il juge dans l’intervalle de confiance. Rien ne remplace un essai sur vos tâches.
  • Balise de télémétrie : la page « Limitations » de la documentation explique que HEADROOM_BEACON est activée par défaut (désactivable) et envoie un résumé anonyme (compteurs, ratios, identifiants de fournisseur et de modèle, système et architecture), jamais les prompts ni le code. Elle se coupe avec HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off ou DO_NOT_TRACK=1. Documentez ce point dans votre revue de sécurité.
  • Un proxy sur le chemin des requêtes : il voit vos clés de fournisseur et vos prompts. Gardez-le en boucle locale et traitez-le comme un composant critique, comme un serveur MCP (voir sécuriser un serveur MCP).

Comment mesurer les économies et superviser le proxy

Headroom expose plusieurs sources, d’après sa page « Metrics & Monitoring » : le point d’accès /stats (JSON), l’historique /stats-history (avec export CSV), les métriques Prometheus sur /metrics (par exemple headroom_tokens_saved_total, headroom_requests_failed_total) et un export OpenTelemetry. La documentation avertit que headroom_requests_total ne compte que les requêtes terminées, et qu’il n’existe pas de buckets d’histogramme : on calcule des moyennes avec les paires _sum et _count.

Pour l’export OTLP, installez l’extra [proxy,otel] puis positionnez ces variables, tirées de la documentation :

Extrait de la documentation de Headroom : variables HEADROOM_OTEL_METRICS_ENABLED, HEADROOM_OTEL_METRICS_ENDPOINT, HEADROOM_OTEL_SERVICE_NAME et HEADROOM_OTEL_RESOURCE_ATTRIBUTES, puis commande curl sur /stats avec jq .otel
Source : github.com

La documentation cite les compteurs headroom.proxy.requests, headroom.proxy.tokens.input, headroom.proxy.tokens.output et headroom.proxy.tokens.saved, et précise que l’endpoint doit être l’URL complète, sans ajout automatique de /v1/metrics. Pour Dynatrace SaaS, la page de Headroom indique un jeton avec le scope metrics.ingest et la variable OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA : la documentation OpenTelemetry de Dynatrace confirme que le backend n’ingère que des valeurs en temporalité delta. Le pas-à-pas OTLP est dans superviser un agent de code en entreprise. Sur Dynatrace Managed, vérifiez d’abord que l’ingestion OTLP est disponible sur votre version.

Pour un chiffre indépendant, comparez les tokens facturés côté agent avec et sans Headroom, comme dans le coût d’un agent IA en tokens avec OpenTelemetry, en additionnant tous les types de tokens, cache compris.

Comment vérifier que ça fonctionne

  1. headroom doctor confirme que le routage fonctionne.
  2. curl http://localhost:8787/health répond (commande de la page de dépannage de la documentation).
  3. curl -s http://localhost:8787/stats | jq .otel confirme que l’exporteur OTLP est actif.

Bonnes pratiques

  • Essayez sur une tâche de référence riche en sorties volumineuses, trois à cinq fois avec et sans proxy.
  • Vérifiez la qualité des réponses, pas seulement les tokens : une compression trop agressive peut masquer une ligne utile.
  • Fixez la version et relisez les variables de télémétrie à chaque mise à jour.
  • Conservez l’accès local au proxy ; n’exposez pas son port.

Questions fréquentes

Headroom est-il open source ?

Oui, le dépôt est sous licence Apache-2.0. Vérifiez cependant les extras et modèles que vous installez, chacun ayant sa propre licence.

Headroom envoie-t-il mes prompts quelque part ?

D’après le README, la compression s’exécute localement. Le proxy transmet bien sûr la requête compressée à votre fournisseur de LLM, et la balise de télémétrie anonyme, active par défaut, est décrite dans la page « Limitations ».

Quelle économie attendre ?

Le projet publie de 21 % à 57 % sur quatre scénarios et prévient que les contenus répétitifs gagnent le plus. Mesurez sur vos propres charges de travail.

Conclusion

Headroom applique la compression de contexte LLM au plus près du proxy et fournit de quoi la mesurer, avec Prometheus et OpenTelemetry. Ses chiffres sont ceux de ses auteurs : à vous de les confirmer sur vos tâches. Sources : dépôt headroomlabs-ai/headroom et documentation de Headroom.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Orca : pilotage d'une flotte d'agents de code, MIT et coûts

Orca : pilotage d’une flotte d’agents de code, MIT et coûts

Next Post
Ponytail skill agent : moins de code, gains à vérifier

Ponytail skill agent : moins de code, gains à vérifier

Related Posts