Qu'est-ce que Headroom ?

Headroom est une couche de compression de tokens LLM open source. Elle est conçue pour compresser intelligemment tout ce que l'agent IA lit — résultats d'outils, logs, résultats de RAG, fichiers et historique de conversation — avant de l'envoyer au LLM.

La promesse : les mêmes réponses, avec seulement 5 à 40 % des tokens. Pour les développeurs qui utilisent quotidiennement des assistants de codage IA (Claude Code, Cursor, Codex, etc.), cela signifie une réduction directe de 60 à 95 % des coûts d'API.

Pourquoi Headroom est-il nécessaire ?

Voici à quoi ressemble généralement le flux de travail d'un assistant de codage IA moderne :

Question utilisateur → Agent explore la base de code → Renvoie 100+ extraits de fichiers →
Agent organise tout le contexte → Envoie au LLM → LLM répond

Le problème : une grande partie du contexte envoyé par l'Agent est redondante. Par exemple :

  • Les résultats de recherche renvoient 100 extraits de code, mais seuls 5 à 10 sont vraiment pertinents
  • Les fichiers journaux contiennent beaucoup d'horodatages superflus et d'informations de débogage
  • Les blocs de documents issus du RAG contiennent de nombreux préfixes répétés

Headroom résout ce problème avec une architecture en trois couches :

  1. ContentRouter — détecte le type de contenu (JSON, code, texte brut) et choisit automatiquement le meilleur compresseur
  2. Compresseurs intelligents — SmartCrusher (JSON), CodeCompressor (conscient de l'AST), Kompress-base (modèle HF)
  3. CCR (Compression réversible) — les données brutes sont stockées localement, le LLM peut les récupérer à la demande

Headroom vs les autres solutions

Fonctionnalité Headroom Compression native du Provider Réduction manuelle du prompt
Économie de tokens 60-95 % 20-40 % Dépend de l'humain
Mémoire partagée inter-agents ✅ ❌ ❌
Compression réversible (CCR) ✅ ❌ N/A
Intégration zéro code (Proxy) ✅ ❌ N/A
Exécution locale ✅ ❌ (cloud) ✅
Multilingue Python + TS SDK uniquement N/A

Installer Headroom

Headroom supporte Python et Node.js. L'installation via pip est recommandée pour la version complète.

Installation Python

BASH 
# Installe la version complète (proxy, MCP, ML et toutes les fonctionnalités)
pip install "headroom-ai[all]"

# Ou installez des sous-modules selon vos besoins
pip install "headroom-ai[proxy]"   # Mode proxy uniquement
pip install "headroom-ai[mcp]"     # Serveur MCP uniquement
pip install "headroom-ai[ml]"      # Modèles de compression ML

Prérequis : Python 3.10+

Installation Node.js / TypeScript

BASH 
npm install headroom-ai

Vérifier l'installation

BASH 
# Vérifier la version et les fonctionnalités
headroom --version

# Lancer un test de performance pour voir l'efficacité de compression
headroom perf

Prise en main rapide : trois modes d'utilisation

Headroom propose trois façons de l'utiliser, de la plus simple à la plus avancée :

Mode 1 : Wrap (le plus simple, zéro configuration)

Si vous utilisez déjà un assistant de codage IA, une seule commande suffit pour activer Headroom :

BASH 
# Envelopper Claude Code
headroom wrap claude

# Envelopper Codex
headroom wrap codex

# Envelopper Cursor
headroom wrap cursor

# Envelopper Aider
headroom wrap aider

# Envelopper GitHub Copilot CLI
headroom wrap copilot

Une fois exécuté, Headroom va automatiquement : 1. Démarrer un service proxy local (port 8787 par défaut) 2. Modifier la configuration de l'agent concerné pour router les requêtes vers le proxy 3. Afficher les instructions de configuration pour vérifier que tout fonctionne

Exemple : envelopper Claude Code

BASH 
$ headroom wrap claude

✅ Headroom proxy started on port 8787
✅ Claude Code config updated

To verify, run:
  claude "What is 2+2?"

You should see compression stats in the output.

Ensuite, chaque fois que vous utilisez la commande claude, la requête passe d'abord par Headroom pour être compressée avant d'être envoyée à l'API Anthropic.

Mode 2 : Proxy (zéro modification de code, idéal pour tout langage)

Si vous ne voulez pas modifier votre code existant, ou si vous utilisez un outil qui ne supporte pas le mode wrap, vous pouvez démarrer le service proxy indépendamment :

BASH 
# Démarrer le proxy sur le port 8787
headroom proxy --port 8787

Ensuite, modifiez la configuration de votre application ou agent pour pointer vers http://localhost:8787 au lieu de l'endpoint Anthropic/OpenAI d'origine.

Exemple : client compatible OpenAI

PYTHON 
from openai import OpenAI

# Configuration d'origine
# client = OpenAI(api_key="sk-...")

# Via le proxy Headroom
client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:8787/v1"  # Pointe vers le proxy Headroom
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explique ce code"}]
)

Toutes les requêtes passant par le proxy sont automatiquement compressées, sans aucune modification de la logique métier.

Mode 3 : Bibliothèque (le plus flexible, intégration dans votre application)

Si vous développez votre propre application IA, vous pouvez appeler directement les fonctions de compression de Headroom :

Exemple Python

PYTHON 
from headroom import compress

messages = [
    {"role": "user", "content": "Analyse ce fichier de log"},
    {"role": "assistant", "content": "Donne-moi le contenu du log"},
    {"role": "user", "content": "[... 10 000 lignes de log ...]"}
]

# Compression des messages
compressed = compress(messages, model="claude-3-sonnet")

print(f"Tokens originaux : {compressed.original_tokens}")
print(f"Tokens compressés : {compressed.compressed_tokens}")
print(f"Économie : {compressed.savings_percent}%")

# Envoi au LLM
response = anthropic_client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1024,
    messages=compressed.messages  # Utilise les messages compressés
)

Exemple TypeScript

TYPESCRIPT 
import { compress } from 'headroom-ai';

const messages = [
  { role: 'user', content: 'Analyze this codebase' },
  { role: 'assistant', content: 'Please provide the files' },
  { role: 'user', content: '[... 50 files ...]' }
];

const compressed = await compress(messages, { model: 'gpt-4' });

console.log(`Saved ${compressed.savingsPercent}% tokens`);

Fonctionnalités principales détaillées

1. Algorithmes de compression intelligents

Headroom intègre plusieurs algorithmes de compression, sélectionnés automatiquement selon le type de contenu :

SmartCrusher — Compression JSON

Conçu spécialement pour les données structurées (réponses API, fichiers de configuration, résultats de bases de données) :

PYTHON 
from headroom import SmartCrusher

data = {
    "users": [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-01-02"},
        # ... 1000+ enregistrements
    ]
}

crusher = SmartCrusher()
compressed = crusher.compress(data)

# Conserve les champs clés, supprime les métadonnées redondantes
# Original : 50 000 tokens → compressé : 5 000 tokens (90 % d'économie)

CodeCompressor — Compression de code consciente de l'AST

Il comprend l'arbre syntaxique du code et ne conserve que les structures essentielles :

PYTHON 
from headroom import CodeCompressor

code = """
def calculate_total(items):
    '''Calculate total price with tax'''
    total = 0
    for item in items:
        if item.active:
            total += item.price * item.quantity
    tax = total * 0.08
    return total + tax
"""

compressor = CodeCompressor(language="python")
compressed = compressor.compress(code)

# Conserve la signature de fonction, le flux de contrôle, les variables clés
# Supprime les commentaires, les espaces, les détails d'implémentation non essentiels

Langages supportés : Python, JavaScript, Go, Rust, Java, C++

Kompress-base — Compression de texte générique

Basé sur un modèle spécialisé entraîné avec HuggingFace, il traite le langage naturel, les documents, les logs, etc. :

BASH 
# Le modèle est téléchargé automatiquement lors de la première utilisation (environ 500 Mo)
headroom proxy

# Emplacement du cache : ~/.cache/headroom/kompress-base

2. CCR — Compression réversible

CCR (Compress-Cache-Retrieve) est l'innovation phare de Headroom : les données compressées sont envoyées au LLM, mais les données brutes restent stockées localement. Si le LLM a besoin de voir le contenu complet, il peut appeler l'outil headroom_retrieve pour les récupérer.

Flux de travail :

1. Headroom compresse le contenu → l'envoie au LLM
2. Le LLM a besoin de plus de détails → appelle headroom_retrieve(chunk_id)
3. Headroom renvoie les données brutes depuis le cache local
4. Le LLM obtient les informations complètes et continue son raisonnement

Avantages : - Le LLM reçoit d'abord une version compressée → économie de tokens - Le contenu complet n'est récupéré qu'en cas de nécessité, évitant l'envoi massif de données - Les données brutes ne sont jamais perdues

3. Mémoire partagée inter-agents

Si vous utilisez plusieurs assistants IA (par exemple Claude Code + Codex + Cursor), Headroom leur permet de partager le contexte compressé :

BASH 
# Activer la mémoire partagée
headroom wrap claude --memory
headroom wrap codex --memory

Ainsi, l'index de la base de code traitée par Claude Code est mis en cache et Codex peut le réutiliser directement, sans avoir à rescanner l'ensemble du projet. C'est particulièrement utile pour les grands projets.

4. Intégration avec le serveur MCP

Headroom peut fonctionner comme un serveur MCP (Model Context Protocol). Tout client compatible MCP peut l'appeler :

BASH 
# Installer le serveur MCP
headroom mcp install

# Outils MCP disponibles :
# - headroom_compress : compresser n'importe quel contenu
# - headroom_retrieve : récupérer les données brutes
# - headroom_stats : consulter les statistiques de compression

Exemple : utilisation dans Claude Desktop

JSON 
// claude_desktop_config.json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}

Cas pratiques

Cas n°1 : Optimisation de la recherche dans la base de code

Scénario : Demander à un assistant IA de trouver l'implémentation d'une fonctionnalité dans un projet de 100 000 lignes.

Sans Headroom :

Agent recherche → renvoie 100 fichiers pertinents → tous envoyés au LLM →
Utilisation : 17 765 tokens → coût élevé, réponse lente

Avec Headroom :

BASH 
headroom wrap claude
claude "Trouve l'implémentation du module d'authentification utilisateur"

Agent recherche → Headroom compresse 100 fichiers →
Utilisation : 1 408 tokens → économie de 92 %

Données de test réelles :

Charge de travail Avant compression Après compression Économie
Recherche de code (100 résultats) 17 765 1 408 92 %
Débogage d'incident SRE 65 694 5 118 92 %
Classification d'issues GitHub 54 174 14 761 73 %
Exploration de base de code 78 502 41 254 47 %

Cas n°2 : Collaboration multi-agents

Scénario : Utiliser Claude Code pour la revue de code, Codex pour générer des tests unitaires et Cursor pour le refactoring.

Méthode traditionnelle : Chaque agent doit scanner la base de code indépendamment, ce qui consomme des tokens en double.

Avec la mémoire partagée Headroom :

BASH 
# Étape 1 : Claude Code scanne et met en cache
headroom wrap claude --memory
claude "Revue la qualité du code dans src/auth/"

# Étape 2 : Codex réutilise le cache
headroom wrap codex --memory
codex "Génère des tests unitaires pour src/auth/"
# Codex utilise directement l'index mis en cache par Claude, pas de nouveau scan

# Étape 3 : Cursor continue de réutiliser
headroom wrap cursor --memory
cursor "Refactore la gestion des erreurs dans src/auth/"

Gains : Les agents suivants économisent 40 à 60 % des tokens de scan initial.

Cas n°3 : Analyse de fichiers journaux

Scénario : Lors du débogage d'un problème en production, il faut faire analyser un fichier de log de 10 000 lignes par l'IA.

PYTHON 
from headroom import compress
import anthropic

# Lecture du log
with open("production.log") as f:
    logs = f.read()

messages = [
    {"role": "user", "content": f"Analyse ce fichier de log et trouve la cause de l'erreur :\n{logs}"}
]

# Compression
compressed = compress(messages, model="claude-3-sonnet")

print(f"Original : {compressed.original_tokens} tokens")
print(f"Compressé : {compressed.compressed_tokens} tokens")
print(f"Économie : {compressed.savings_percent}%")

# Envoi
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=2048,
    messages=compressed.messages
)

print(response.content[0].text)

Résultat typique : 65 694 tokens → 5 118 tokens (92 % d'économie), sans perte des informations d'erreur critiques.

Tests de performance

Headroom maintient sa précision sur les benchmarks standards :

Benchmark Catégorie Échantillons Précision de base Précision Headroom Écart
GSM8K Mathématiques 100 0,870 0,870 ±0,000
TruthfulQA Factualité 100 0,530 0,560 +0,030
SQuAD v2 QA 100 — 97 % Taux de compression 19 %
BFCL Appels d'outils 100 — 97 % Taux de compression 32 %

Conclusion : Headroom maintient la précision tout en réalisant des économies de tokens significatives.

Pour reproduire les benchmarks :

BASH 
python -m headroom.evals suite --tier 1

Configuration avancée

CacheAligner — Améliorer le taux de hit du cache KV

CacheAligner stabilise le préfixe du prompt afin que le cache KV d'Anthropic/OpenAI soit utilisé, réduisant encore les coûts :

PYTHON 
from headroom import CompressionMiddleware

# Ajouter le middleware dans une application ASGI
app.add_middleware(CompressionMiddleware)

headroom learn — Apprendre de ses erreurs

Headroom peut analyser les sessions échouées et écrire automatiquement les corrections dans CLAUDE.md ou AGENTS.md :

BASH 
# Activer le mode apprentissage
headroom wrap claude --learn

# Quand Claude Code donne une réponse erronée, Headroom :
# 1. Analyse la cause de l'échec
# 2. Génère des indications correctives
# 3. Les écrit dans le fichier CLAUDE.md du projet
# 4. Les applique automatiquement à la session suivante

Stratégies de compression personnalisées

Vous pouvez étendre le comportement de compression via le Pipeline :

PYTHON 
from headroom import PipelineExtension

class MyCustomCompressor(PipelineExtension):
    def on_input_received(self, event):
        # Logique personnalisée à la réception des données
        print(f"Reçu {len(event.content)} octets")

    def on_input_compressed(self, event):
        # Logique après compression
        print(f"Compressé à {event.compressed_size} octets")

# Enregistrer l'extension
pipeline.register(MyCustomCompressor())

Questions fréquentes

Q1 : Headroom affecte-t-il la qualité des réponses ?

R : Non. Les benchmarks montrent que la précision reste inchangée (GSM8K : 0,870 → 0,870). La compression réversible CCR garantit que le LLM peut à tout moment récupérer le contenu complet si nécessaire.

Q2 : Qu'en est-il de la sécurité des données ?

R : Headroom fonctionne entièrement en local. Toute la compression, la mise en cache et le stockage se font sur votre machine. Les données brutes ne sont jamais envoyées à un serveur externe.

Q3 : Quels fournisseurs de LLM sont supportés ?

R : En théorie, tous les fournisseurs sont supportés puisque Headroom agit au niveau du prompt. Les fournisseurs suivants ont été testés et validés : - Anthropic (Claude) - OpenAI (GPT-4, GPT-3.5) - AWS Bedrock - Google Gemini - Toute API compatible OpenAI

Q4 : La compression ajoute-t-elle de la latence ?

R : La compression locale prend généralement entre 10 et 50 ms, ce qui est négligeable comparé à la latence réseau (plusieurs centaines de ms à plusieurs secondes). De plus, comme moins de tokens sont envoyés, le temps de réponse global est généralement plus rapide.

Q5 : Headroom est-il adapté aux développeurs individuels ou aux équipes ?

R : Les deux. - Développeurs individuels : utilisateurs quotidiens d'assistants IA, réduction des coûts d'API - Équipes : mémoire partagée inter-agents pour éviter les scans redondants de la base de code ; stratégie de compression unifiée pour un meilleur contrôle des coûts

Résumé

Headroom est un outil open source de qualité qui résout un problème concret. Pour les développeurs qui utilisent intensivement les assistants de codage IA, il permet de :

✅ Réduire les coûts de tokens de 60 à 95 % — des économies directes
✅ Intégration zéro code — une seule commande : headroom wrap claude
✅ Mémoire partagée inter-agents — cache commun à Claude, Codex, Cursor
✅ Compression réversible (CCR) — les données brutes sont conservées, le LLM peut les récupérer à la demande
✅ Exécution locale — données sécurisées, pas de risque de fuite

Si votre équipe dépense plus de 100 $ par mois en API LLM, Headroom vous permettra presque certainement de réaliser des économies substantielles.

Commencez dès maintenant :

BASH 
pip install "headroom-ai[all]"
headroom wrap claude  # ou tout autre agent que vous utilisez
headroom perf         # visualisez les économies réalisées

Lien du projet : https://github.com/chopratejas/headroom
Documentation : https://headroom-docs.vercel.app/docs