Headroom : compresser le contexte des agents IA avant l appel au LLM

Headroom est une couche de compression de contexte placee entre un agent IA et son fournisseur de modele. Le projet propose plusieurs modes d integration, de la librairie Python au proxy transparent, et cherche a reduire les tokens envoyes au LLM sans supprimer les informations importantes (README, Architecture).

Overview

Headroom se presente comme une couche de context compression pour agents IA. L idee est simple : au lieu d envoyer tel quel au modele les sorties d outils, les logs, les morceaux de RAG, les lectures de fichiers ou l historique de conversation, on intercale une etape qui compresse ces donnees avant l appel au LLM (README).

Le depot met en avant trois portes d entree principales : une librairie avec compress(messages), un proxy lance avec headroom proxy --port 8787, et des integrations ou wrappers pour des outils comme Claude Code, Codex, Cursor, Aider, Copilot CLI ou OpenCode (README, site du projet).

Le projet publie aussi une documentation web complete, un index llms.txt pour consommation par agents, un package Python sur PyPI et un modele Hugging Face pour la compression de texte. Cela montre que Headroom ne se limite pas a un README de presentation : il y a un outillage documentaire pense a la fois pour les humains et pour les agents (PyPI, llms.txt, Hugging Face).

Objectif

Le probleme vise par Headroom est tres concret : un agent de code ou un assistant outille passe une partie importante de son budget a relire du bruit. Les sorties de recherche, les tableaux JSON, les logs de build, les resultats de grep, les reponses HTTP ou les contextes RAG gonflent vite la fenetre de contexte et la facture. Le README resume cela en disant que Headroom compresse everything your AI agent reads avant que ces donnees n arrivent au LLM (README).

L angle interessant est que le projet ne propose pas une seule technique. La documentation d architecture decrit une chaine avec stabilisation du prefixe pour le cache fournisseur, routage par type de contenu, compression specialisee, puis gestion du contexte restant si la fenetre est encore trop grosse (Architecture).

Autrement dit, Headroom ne cherche pas uniquement a resumer du texte. Il cherche a optimiser un workflow agentique complet : sorties d outils, appels MCP, memoire partagee, wrappers CLI, compatibilite proxy et integrations framework (README, MCP).

Liens utiles

• Depot principal
• README du projet
• Releases GitHub
• Documentation officielle
• Quickstart
• Installation
• Architecture
• Benchmarks
• Site vitrine du projet
• Package PyPI
• Index llms.txt
• Modele Kompress v2 base
• Introduction au Model Context Protocol

Installation

Le chemin le plus direct, documente a la fois dans le README et dans la page d installation, consiste a installer le package Python puis a choisir un mode d execution. Le projet demande Python 3.10+ cote Python, et Node.js 18+ pour le SDK TypeScript (Installation, PyPI).

pip install "headroom-ai[all]"

Si on veut seulement le coeur Python, la documentation propose aussi :

pip install headroom-ai

Pour le SDK TypeScript :

npm install headroom-ai

La doc d installation precise un point important : le SDK TypeScript parle a un proxy Headroom lance localement. Autrement dit, npm install headroom-ai ne suffit pas a lui seul si on veut compresser depuis Node.js ; il faut aussi demarrer le proxy Python (Installation, Quickstart).

pip install "headroom-ai[proxy]"
headroom proxy --port 8787

Le projet documente egalement un mode Docker preconstruit :

docker pull ghcr.io/chopratejas/headroom:latest
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest

Enfin, si l on veut verifier l installation ou suivre le rythme des releases, la doc mentionne python -c "import headroom; print(headroom.__version__)" et la commande headroom update, tandis que la release v0.27.0 ajoute justement ce workflow d update et un sous-outil headroom doctor pour le diagnostic d environnement (Installation, Releases).

Notions et concepts

Pour comprendre Headroom rapidement, il faut retenir quatre modes d usage, puis les briques internes qui se trouvent derriere.

Mode	A quoi il sert	Changement de code
Librairie Python	Appeler compress(messages) dans une appli	Minimal
Proxy	Intercepter les appels LLM via une base URL locale	Quasi nul
Wrap CLI	Brancher un agent existant comme Claude Code ou Codex	Nul cote application
MCP	Exposer compression, retrieval et stats comme outils MCP	Dependant du client

Cette vue est directement coherente avec le README et la page d architecture : tous ces points d entree convergent vers le meme pipeline interne (README, Architecture).

1. CacheAligner

La premiere etape stabilise les prefixes de prompt pour favoriser le cache cote fournisseur. La doc parle explicitement de prefixes rendus plus stables pour que les mecanismes de cache d Anthropic, OpenAI ou Google puissent mieux frapper sur les appels repetes (Architecture).

2. ContentRouter et compresseurs specialises

La deuxieme etape detecte le type de contenu et route vers le bon compresseur. Le README et le site listent notamment SmartCrusher pour le JSON, CodeCompressor pour le code, Kompress-base pour le texte, ainsi que d autres compresseurs pour logs, diffs, HTML ou resultats de recherche (README, site du projet, Benchmarks).

Le modele kompress-v2-base sur Hugging Face donne un peu plus de matiere sur cette brique texte : il s agit d un compresseur extractif base sur ModernBERT, avec etiquetage keep/drop par token, un adaptateur LoRA, et un apprentissage sur plus de 126000 exemples etiquetes sur 17 domaines (Hugging Face).

3. IntelligentContext

Si le contexte compresse reste trop gros, Headroom applique une logique de fenetre glissante ou un scoring d importance pour garder les messages les plus utiles. La doc d architecture detaille cette partie sous les noms Rolling Window et Intelligent Context (Architecture).

4. CCR : compression reversible

Un point cle est le mecanisme CCR pour Compress-Cache-Retrieve. Le contenu original est stocke localement, puis le modele peut demander la version complete si besoin. Le README explique cette reversibilite, et la doc MCP aide a comprendre pourquoi cette approche colle bien a un outillage de type agent : le modele peut utiliser un outil plutot que tout relire a chaque tour (README, MCP).

5. Quelques chiffres a garder en tete

Le README affiche des reductions de 47% a 92% selon le type de workload, avec maintien des scores sur plusieurs benchmarks publies. La page Benchmarks donne plus de detail, par exemple 87.6% de reduction sur un lot de logs de production sans perdre la detection de l erreur critique, et une telemetrie agregee sur plus de 50000 sessions proxy entre mars et avril 2026 (README, Benchmarks).

Il faut lire ces chiffres comme des chiffres publies par le projet, pas comme une verification faite ici. En revanche, ils sont utiles pour comprendre la cible : JSON lourds, logs, resultats d outils et contextes multi-agents semblent etre les cas prioritaires (Benchmarks).

6. Ce qui evolue en ce moment

La release v0.27.0 met en avant des ajouts recents comme headroom doctor, headroom update, la reduction des tokens de sortie, la compression tabulaire et spreadsheet, ainsi que le support de Cortex Code. Cela donne une bonne idee de la trajectoire actuelle du projet : plus de wrappers, plus d observabilite et plus de surfaces d optimisation autour des agents (Releases).

Commandes

Voici un jeu de commandes directement tire du README et de la documentation.

# Installation Python complete
pip install "headroom-ai[all]"

# Installation TypeScript
npm install headroom-ai

# Lancer le proxy local
headroom proxy --port 8787

# Brancher Claude Code sur le proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# Brancher un client OpenAI compatible
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

# Wrapper un agent de code
headroom wrap claude

# Voir les gains
headroom perf
headroom dashboard

# Installer les outils MCP
headroom mcp install

# Mettre a jour l installation
headroom update
headroom update --check

Pour un premier essai oriente Python, la doc Quickstart montre aussi une sequence plus applicative : on compresse messages, puis on envoie result.messages au client OpenAI ou equivalent. Cette distinction est importante : Headroom ne remplace pas le fournisseur de modele, il prepare le contexte avant l appel (Quickstart).

Demo

L interet du projet apparait surtout dans un premier workflow complet. Voici un scenario realiste pour prendre Headroom en main sans reecrire toute son application.

Preparation du run

On choisit d abord le mode d usage. Si l objectif est de tester vite sur un agent existant, le mode proxy ou le mode wrap est le plus simple. Si l objectif est d integrer la compression dans une application Python deja existante, le mode compress(messages) est plus approprie (README, Architecture).

pip install "headroom-ai[proxy]"
headroom proxy --port 8787

Lancement du proxy et branchement d un client

Une fois le proxy actif, on pointe son client ou son agent dessus. Pour Claude Code, le README et le quickstart proposent de definir ANTHROPIC_BASE_URL=http://localhost:8787. Pour un client OpenAI compatible, on bascule plutot OPENAI_BASE_URL=http://localhost:8787/v1 (Quickstart, README).

Le resultat attendu est que les appels continuent a fonctionner comme avant, mais que les sorties verbeuses d outils passent par le pipeline Headroom avant l envoi au modele. C est exactement le genre de cas vise par le projet : logs de build, gros JSON, recherche, lecture de fichiers ou historiques d agent (README).

Suivi des gains

Une fois quelques tours executes, on peut regarder les gains. Le README mentionne headroom perf et headroom dashboard, tandis que le quickstart montre aussi un endpoint HTTP curl http://localhost:8787/stats pour recuperer des compteurs comme tokens_saved_total (README, Quickstart).

Dans la documentation Benchmarks, on voit bien pourquoi ce suivi est utile : selon le type de charge, le benefice peut etre massif sur des tableaux JSON ou des logs, mais nul sur du code Python deja compact. Le projet documente donc aussi les cas ou il ne compresse pas, ce qui est un bon signal de prudence technique (Benchmarks).

Sortie et reutilisation

Si l on veut aller plus loin, il y a ensuite trois directions naturelles. La premiere consiste a remplacer le test proxy par une integration SDK ou framework, par exemple LangChain, Agno, Strands, Vercel AI SDK ou LiteLLM. La deuxieme consiste a activer MCP avec headroom mcp install, ce qui expose headroom_compress, headroom_retrieve et headroom_stats a un client compatible. La troisieme consiste a suivre les nouveautes de release, notamment autour de headroom doctor, du hot-reload d environnement, de la reduction des tokens de sortie et de la compression tabulaire (site du projet, llms.txt, Releases).

Conclusion

Headroom est un projet a regarder si l on cherche a reduire le cout et la taille du contexte dans des workflows d agents IA sans commencer par reecrire l application. Le coeur de la proposition tient dans trois idees lisibles dans la doc : brancher facilement la couche, choisir automatiquement le bon compresseur selon le contenu, et garder une voie de retour vers l original avec CCR (README, Architecture).

Pour un lecteur technique, la bonne strategie est probablement de commencer par le proxy local ou headroom wrap claude, puis de verifier concretement les gains sur ses propres sorties d outils. Les chiffres publies par le projet sont utiles pour cadrer les attentes, mais le vrai verdict se joue sur vos logs, vos JSON, votre RAG et vos habitudes agentiques (Benchmarks, Releases).