Headroom — Guide de Configuration Complet
juin 2026 · 5 min de lecture
Compresse tes tokens avant qu'ils atteignent le LLM. 60–95% de réduction. Mêmes réponses.
1. Installation
# Python (recommandé — tout inclus)
pip install "headroom-ai[all]"
# Node / TypeScript
npm install headroom-ai
# Docker
docker pull ghcr.io/chopratejas/headroom:latest
Prérequis : Python 3.10+
Si tu utilises pipx :
pipx install --python python3.13 "headroom-ai[all]"
Extras disponibles si tu veux installer à la carte :
[proxy] [mcp] [ml] [agno] [langchain] [evals]
2. Mode Proxy — Zéro ligne de code à modifier
Le mode le plus simple. Tu changes rien dans ton app existante.
# Lance le proxy local
headroom proxy --port 8787
Ensuite, pointe ton app sur le proxy au lieu de l'API Anthropic :
# Variable d'environnement à changer
ANTHROPIC_BASE_URL=http://localhost:8787
C'est tout. Headroom intercepte chaque requête, compresse le contexte, transmet au LLM.
Fonctionne avec n'importe quel langage, n'importe quel framework, n'importe quel LLM compatible OpenAI.
3. Mode Wrap — Pour les agents IA
Lance directement Headroom autour de ton agent existant.
# Claude Code
headroom wrap claude
# Codex
headroom wrap codex
# Cursor
headroom wrap cursor
# (affiche la config à coller — paste une fois)
# Aider
headroom wrap aider
# Copilot CLI
headroom wrap copilot
# OpenClaw
headroom wrap openclaw
# (s'installe comme plugin ContextEngine dans OpenClaw)
Headroom tourne en fond. Tu utilises ton agent normalement. La compression est automatique.
4. Mode Library — Intégration dans ton code
Python
from headroom import compress
# Compresse tes messages avant de les envoyer
compressed = compress(messages, model="claude-opus-4-6")
response = client.messages.create(messages=compressed, ...)
TypeScript / Node
import { compress } from "headroom-ai";
const compressed = await compress(messages, { model: "claude-opus-4-6" });
const response = await client.messages.create({ messages: compressed });
Avec le SDK Anthropic directement
from headroom import withHeadroom
import anthropic
client = withHeadroom(anthropic.Anthropic())
# Utilise ton client normalement — Headroom compresse en transparent
5. Intégrations frameworks
| Ton setup | Commande |
|---|---|
| Anthropic SDK | withHeadroom(new Anthropic()) |
| OpenAI SDK | withHeadroom(new OpenAI()) |
| Vercel AI SDK | wrapLanguageModel({ model, middleware: headroomMiddleware() }) |
| LiteLLM | litellm.callbacks = [HeadroomCallback()] |
| LangChain | HeadroomChatModel(your_llm) |
| Agno | HeadroomAgnoModel(your_model) |
| ASGI / FastAPI | app.add_middleware(CompressionMiddleware) |
| Multi-agent | SharedContext().put / .get |
6. Mode MCP Server — Pour Claude Desktop / clients MCP
# Installe Headroom comme serveur MCP
headroom mcp install
Outils disponibles dans ton client MCP :
headroom_compress— compresse un contexteheadroom_retrieve— récupère les originaux (compression réversible)headroom_stats— voir les économies en temps réel
7. headroom learn — Ton agent apprend de ses erreurs
headroom learn
Mine automatiquement tes sessions ratées et écrit les corrections dans :
CLAUDE.md(pour Claude Code)AGENTS.md(pour Codex)GEMINI.md(pour Gemini)
Ton agent ne refera plus les mêmes erreurs. Automatiquement.
8. Voir tes économies
# Stats dans le terminal
headroom stats
Dashboard live en ligne : headroomlabs.ai/dashboard
Tu vois :
- Tokens économisés au total
- Coût avant / après
- Compression par type de contenu
- Ton classement sur le leaderboard communautaire (60B+ tokens économisés)
9. Ce que Headroom compresse
| Type de contenu | Compresseur utilisé | Réduction typique |
|---|---|---|
| JSON / tool outputs | SmartCrusher | 70–92% |
| Code (Python, JS, Go, Rust, Java, C++) | CodeCompressor (AST) | 47–80% |
| Texte / logs / prose | Kompress-base (HuggingFace) | 60–90% |
| Images | ML router | 40–90% |
La compression est réversible — les originaux sont toujours stockés localement. Le LLM peut les récupérer via headroom_retrieve si nécessaire.
10. Benchmarks réels
| Workload | Avant | Après | Économie |
|---|---|---|---|
| Code search (100 résultats) | 17 765 tokens | 1 408 tokens | 92% |
| SRE incident debugging | 65 694 tokens | 5 118 tokens | 92% |
| GitHub issue triage | 54 174 tokens | 14 761 tokens | 73% |
| Exploration codebase | 78 502 tokens | 41 254 tokens | 47% |
Précision préservée sur les benchmarks standard (GSM8K, TruthfulQA, SQuAD v2, BFCL).
11. Quand l'utiliser / quand ne pas l'utiliser
Parfait si tu :
- Utilises des agents IA au quotidien et veux réduire tes coûts
- Travailles avec plusieurs agents (Claude + Codex + Gemini) et veux une mémoire partagée
- As besoin de compression réversible
Pas adapté si tu :
- Utilises uniquement la compaction native d'un seul provider et n'as pas besoin de cross-agent
- Travailles dans un environnement sandboxé où les processus locaux ne peuvent pas tourner
Ressources
- Docs complètes : headroom-docs.vercel.app/docs
- GitHub : github.com/chopratejas/headroom
- Discord : discord.gg/yRmaUNpsPJ
- Dashboard live : headroomlabs.ai/dashboard
- PyPI : pypi.org/project/headroom-ai
- npm : npmjs.com/package/headroom-ai
- Modèle HuggingFace : huggingface.co/chopratejas/kompress-base
- Licence : Apache 2.0 — open source, gratuit