×4 d'usage Claude Code : guide budget Headroom MCP (2026-06-04)
Les indie hackers qui font tourner Claude Code sur de vrais dépôts connaissent la douleur : chaque grep, log de test et dump MCP revient dans le contexte—et Anthropic facture les tokens entrée + sortie. Headroom (Apache 2.0, 10k+ étoiles GitHub mi-2026) compresse localement sorties d'outils, logs, fichiers et chunks RAG avant le modèle, avec des workloads publiés à 60–95 % de tokens en moins et une démo README 10 144 → 1 260 tokens pour un FATAL dans les logs.
Guide facturation réelle + installation pour headroom wrap claude et le serveur MCP—pas du hype pour remplacer Claude, mais arrêter de payer le plein tarif pour des mégaoctets de stderr déjà vus.
Pourquoi Claude Code brûle le budget sur les dépôts d'ingénierie
La force de Claude Code—lire le repo comme un ingénieur—est aussi son compteur :
- Inflation des sorties d'outils —
bash, recherche et MCP peuvent atteindre 10k–80k tokens par tour sur de gros monorepos. - Contexte renvoyé — les blobs d'outils restent dans le fil ; les coûts se cumulent sur une session refactor de 45 minutes.
- Prolifération MCP — chaque serveur ajoute du JSON ; trois outils verbeux peuvent doubler les tokens d'entrée d'un tour.
Si vous choisissez encore un harness, voir Codex CLI vs Claude Code et comparatif agents 2026—cet article suppose Claude Code déjà choisi pour récupérer de la marge.
Architecture — où se place Headroom
Claude Code (or Cursor / Codex via wrap)
│ tool calls · logs · file reads
▼
┌──────────────────────────────────────┐
│ Headroom (local — Python 3.10+) │
│ CacheAligner → ContentRouter → CCR │
│ SmartCrusher (JSON) │
│ CodeCompressor (AST) │
│ Kompress-base (text) │
│ MCP: compress · retrieve · stats │
└──────────────────────────────────────┘
│ compressed context + retrieve tool
▼
Anthropic API (Claude)
- CCR (réversible) — originaux stockés localement ; le modèle peut appeler
headroom_retrievepour le texte verbatim. - Mode MCP — expose
headroom_compress,headroom_retrieve,headroom_statsà tout client MCP. - Mode proxy —
headroom proxy --port 8787pour clients compatibles OpenAI sans changer le code.
Docs officielles : headroom-docs.vercel.app · Source : github.com/chopratejas/headroom.
Matrice de facturation — workloads publiés vs « Claude Code brut »
Utilisez le tableau avant/après publié de Headroom comme chiffres de planification—pas une garantie pour votre repo. Multipliez par votre $/MTok.
| Workload (docs) | Avant | Après | Économie | Pour indies |
|---|---|---|---|---|
| Recherche code (100) | 17,765 | 1,408 | 92% | Jours rg lourds : d'une session à ~20 $ au prix d'un café |
| Debug incident SRE | 65,694 | 5,118 | 92% | Triage logs sans couper --verbose |
| Triage issues GitHub | 54,174 | 14,761 | 73% | Bots d'issues viables sur Max |
| Exploration codebase | 78,502 | 41,254 | 47% | Toujours utile ; lectures larges moins compressibles |
Calcul mensuel illustratif (hypothétique)
Supposez ~3 $/MTok en entrée type Sonnet (vérifiez la page Anthropic actuelle) :
| Scénario | Tokens bruts/mois | Effectifs ~75 % | $ entrée brut | $ avec Headroom |
|---|---|---|---|---|
| Solo indie (50M in) | 50M | 12.5M | $150 | ~$38 |
| Small team (200M in) | 200M | 50M | $600 | ~$150 |
| "Log hell" week (+30M logs) | 30M | 3M (90% on logs) | $90 | ~$9 |
×4 d'usage dans le titre : budget dollar constant, ~75 % d'économie moyenne ≈ ~×4 de tours pour la même dépense—pas d'usage illimité magique.
Scénario A — headroom wrap claude (voie la plus rapide)
Pour : Claude Code quotidien en Terminal (Mac/Linux).
# Python 3.10+ required
pip install "headroom-ai[all]"
# One-command wrap (starts compression + optional memory)
headroom wrap claude
# After a session, inspect savings
headroom perf
Headroom intercepte sorties d'outils et contexte avant l'API.
Si X, alors Y : obra sur Mac loué → Headroom sur le même hôte — install obra.
Scénario B — serveur MCP
Équipes qui curatent les MCP.
pip install "headroom-ai[mcp]"
# Install MCP config for supported clients
headroom mcp install
Config MCP Claude Code :
{
"mcpServers": {
"headroom": {
"command": "headroom",
"args": ["mcp", "serve"]
}
}
}
Outils MCP :
| Outil | Rôle |
|---|---|
headroom_compress | Réduire un blob avant le chat |
headroom_retrieve | Texte original (CCR) |
headroom_stats | Télémétrie d'économie |
Gros JSON MCP → Headroom avant Claude.
Scénario C — proxy
headroom proxy --port 8787
# Point OpenAI-compatible clients at http://127.0.0.1:8787
Une couche de compression pour Codex, Aider, scripts.
Runbook — première heure productive
- Installer —
pip install "headroom-ai[all]". - Baseline — tâche sans Headroom ; tokens d'entrée Anthropic.
- Wrap —
headroom wrap claude; même tâche. - Comparer —
headroom perf. - MCP —
headroom mcp install. - Attentes — ~47 %.
- CCR —
headroom_retrieve. - Ignorer si — proxy sur Mac loué.
Dépannage
wrap ne démarre pas Claude Code
Installer CLI.
Économies ~0 %
Tester sur gros repo rg.
Détail manqué
headroom_retrieve (CCR).
MCP rouge
headroom mcp serve manuellement.
Chemins recommandés
| Votre cas | À faire |
|---|---|
| Solo, Terminal seulement | headroom wrap claude + headroom perf hebdo |
| MCP lourds (5+) | MCP install + serveur au plus gros payload |
| Équipe agents mixtes | headroom proxy sur Mac mini partagé |
| Budget Max serré | Prioriser logs/recherche (jusqu'à 92 %) |
| Dev Chine continentale | Miroir pip ; Mac loué HK/SG |