Réduire les tokens de Claude Code : Context Mode et Headroom

Pour réduire la consommation de tokens de Claude Code, repérez ce qui remplit le contexte, puis évitez d’y faire entrer les sorties d’outils inutiles. Commencez par les fonctions natives de Claude Code ; essayez Context Mode pour traiter les données de manière sélective et reprendre le travail après un compactage, ou Headroom pour compresser les sorties à travers un proxy local. Si le raisonnement et les tentatives infructueuses répétées représentent l’essentiel de votre consommation, précisez le périmètre des tâches et revoyez le choix du modèle avant d’ajouter l’un de ces outils.

Au 2026-10-21, la version actuelle de Claude Code est la 2.1.306. L’installation de Headroom ci-dessous fixe la version à 0.41.0.

Où partent les tokens de Claude Code ?

Utilisez /context pour comprendre l’occupation du contexte et /usage pour consulter la consommation et le coût estimé. Ces commandes répondent à des questions différentes.

Question	Où regarder	Ce que vous apprenez
Pourquoi cette conversation remplit-elle le contexte ?	`/context`	La place occupée par les instructions, les messages, les outils et les autres éléments du contexte
Qu’a consommé cette session ?	`/usage`	Les catégories de tokens et le coût estimé de la session
Suis-je proche du quota de mon abonnement ?	Les informations sur le forfait dans `/usage`	La consommation du forfait, distincte de la facturation API
Quel montant a réellement été facturé ?	Les relevés d’utilisation de votre fournisseur	Les frais calculés selon ses tarifs et ses règles de facturation

Dans la version actuelle de Claude Code, /cost est un alias de /usage. Le montant en dollars est une estimation : il ne signifie pas que chaque requête incluse dans Pro ou Max entraîne cette dépense supplémentaire. La documentation de Claude Code sur les coûts explique cette distinction.

Des logs volumineux, des instantanés de navigateur, des fichiers de dépendances et des résultats d’outils répétés peuvent occuper une grande partie du contexte. Les messages précédents participent aussi aux requêtes suivantes, mais la mise en cache des prompts peut rendre les entrées réutilisées moins chères que de nouvelles entrées. Réduire le contenu visible de 50% ne diminue donc pas automatiquement la facture de 50%.

Utilisez les fonctions natives avant d’ajouter une compression

Adaptez le réglage à la source du gaspillage : une recherche plus ciblée pour les sorties trop volumineuses, une nouvelle conversation pour un travail sans rapport avec le précédent, et un compactage pour poursuivre une tâche longue.

Donnez à Claude les chemins exacts des fichiers, les noms des tests qui échouent et une commande précise de vérification. Lui demander d’examiner un module défaillant entraîne généralement moins de travail inutile que lui demander de comprendre tout le dépôt avant une petite modification.

Utilisez /clear entre des tâches indépendantes, après avoir relevé les chiffres de consommation dont vous avez besoin. Pour continuer la même tâche, donnez une consigne ciblée à /compact, par exemple :

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

Ces pratiques de gestion du contexte sont documentées, mais le compactage produit un résumé, pas une archive exacte de la conversation. Conservez les critères d’acceptation essentiels dans les instructions durables du projet ou dans vos notes de tâche.

Évitez de compacter après chaque échange. Le compactage déclenche une requête de synthèse et remplace l’historique des messages ; la requête suivante doit donc établir un préfixe de cache plus court. Un compactage trop fréquent peut ajouter du travail et obliger à reconstruire le cache en échange de l’espace gagné.

Pour les tâches simples, sur les modèles qui prennent en charge le réglage de l’effort, essayez /effort low. Un effort plus faible peut réduire le travail de raisonnement ; il ne raccourcit pas un log déjà renvoyé par un outil. Les changements saisis restent enregistrés pour le modèle sélectionné : rétablissez votre réglage habituel après la comparaison. La documentation de configuration des modèles détaille les commandes disponibles et les alias de modèles.

Les sous-agents permettent aussi de séparer le travail : ils disposent de leur propre contexte et renvoient un résumé. Cela préserve la conversation principale, mais leurs requêtes consomment tout de même des tokens.

Context Mode ou Headroom : lequel essayer ?

Choisissez Context Mode si vous pouvez réduire les données avant de les renvoyer à Claude. Choisissez Headroom si vous souhaitez faire passer les appels d’outils existants par une couche de compression.

Votre difficulté	À essayer en premier	Ce qui change
De gros fichiers ou logs que vous pouvez interroger ou traiter localement	Context Mode	Claude utilise des outils d’exécution et de recherche pour recevoir une sélection de résultats
La perte de certains éléments de la tâche après un compactage	Context Mode	Des hooks de cycle de vie enregistrent les événements et restaurent les informations nécessaires à la reprise
Les sorties trop détaillées des outils que vous utilisez déjà	Headroom	Un proxy local compresse les contenus d’outils éligibles avant de transmettre les requêtes
Des tâches courtes dominées par le raisonnement ou les nouvelles tentatives	Les réglages natifs du périmètre, de l’effort et du modèle	Vous réduisez le travail à effectuer avant d’introduire un composant supplémentaire

Essayez un seul outil à la fois pour pouvoir lui attribuer les résultats observés.

Les pourcentages publiés ne sont pas directement comparables. Les mesures de Context Mode portent sur les octets de sortie de certains exemples. Les chiffres de 21%–57% annoncés par Headroom proviennent de charges de travail hors ligne sur des sorties d’outils, générées avec une graine aléatoire fixe. Aucun de ces résultats n’établit la baisse de votre facture Claude Code complète, ni ne dispense de vérifier que la tâche aboutit toujours correctement.

Context Mode : renvoyer le résultat plutôt que le fichier entier

Context Mode est utile lorsqu’un traitement local peut fournir la réponse sans placer toutes ses données d’entrée dans la conversation de Claude. Son plugin enregistre également certains événements de session dans SQLite et utilise des hooks pour restaurer les informations nécessaires à la reprise après un compactage.

Le paquet actuel exige Node.js 22.5.0 ou une version ultérieure. Vérifiez votre installation dans Bash :

claude --version
node --version

Dans Claude Code, suivez l’installation depuis la marketplace documentée par le projet :

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Redémarrez Claude Code, puis exécutez :

/context-mode:ctx-doctor

La commande de diagnostic vérifie notamment la prise en charge de l’environnement d’exécution, l’enregistrement du plugin, les hooks et la recherche SQLite. Corrigez les échecs pertinents avant de considérer le plugin comme actif. Installer uniquement son serveur MCP ne fournit pas la même intégration avec les hooks du cycle de vie.

Pour une vérification concrète, ouvrez un projet npm possédant déjà un package-lock.json de version 2 ou 3. Demandez à Claude d’appeler ctx_execute_file avec path: "package-lock.json", language: "javascript" et le code suivant :

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

L’outil fournit le contenu du fichier via FILE_CONTENT. Le résultat attendu est un petit objet JSON contenant les trois champs demandés, plutôt que l’intégralité du fichier de verrouillage. Les nombres dépendent de votre projet : ils comptent les entrées du fichier, pas les noms de paquets uniques.

Exécutez ensuite :

/context-mode:ctx-stats

La commande de statistiques devrait indiquer une activité de Context Mode. Si elle ne signale aucun appel, vous n’avez pas démontré que le traitement demandé a emprunté ce chemin. Ses chiffres de réduction des sorties ne constituent pas un calcul de facture.

Appliquez le même principe aux logs : calculez les totaux localement, sélectionnez les erreurs pertinentes et renvoyez des extraits exacts avec leur emplacement dans la source. Conservez la lecture directe pour les petits fichiers source dont Claude doit connaître précisément le code.

Context Mode utilise Elastic License 2.0. Son isolation d’exécution n’est pas non plus un bac à sable de sécurité complet au niveau du système d’exploitation : les outils d’exécution peuvent hériter des accès au système de fichiers. Conservez les permissions et les contrôles d’isolation que vous appliquez habituellement aux commandes exécutées par les agents.

Headroom : faire passer les sorties éligibles par un proxy local

Headroom convient lorsque vous souhaitez continuer à utiliser les outils habituels de Claude Code pendant qu’un proxy réduit les sorties éligibles. Son comportement par défaut, prévu pour le développement, tient aussi compte de la stabilité du cache ; il ne garantit pas de compresser chaque fichier source ou chaque requête.

Cet exemple utilise une clé API d’Anthropic Console et entraîne donc une facturation API distincte de l’abonnement Claude. Il suppose que uv et Claude Code sont installés, qu’aucun proxy Headroom ne fonctionne déjà et qu’aucune configuration de passerelle personnalisée ou de fournisseur cloud n’entre en conflit. Les passerelles déjà utilisées dans une organisation nécessitent leur propre procédure d’intégration.

Dans Bash, installez le paquet proxy à la version indiquée, conformément au guide d’installation de Headroom :

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

La vérification doit afficher la version 0.41.0. Saisissez votre clé sans l’afficher à l’écran, appuyez sur Entrée, puis lancez le wrapper :

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Autorisez l’utilisation de la clé API personnalisée si Claude le demande, puis consultez /status pour confirmer le moyen d’authentification et le modèle actifs. Si vous avez précédemment refusé la clé, la documentation d’authentification de Claude décrit le réglage « Use custom API key » dans /config.

Le wrapper démarre ou réutilise un proxy local, lance Claude en passant par ce proxy et enregistre le serveur MCP de récupération de Headroom dans la configuration de Claude Code. L’option --code-memory none ignore l’intégration supplémentaire de Serena tout en conservant la récupération de Headroom. N’ajoutez pas --no-mcp à cette procédure : cette option supprime le mécanisme de récupération associé aux marqueurs de contenu compressé. Ces options sont définies dans l’implémentation du wrapper en version 0.41.0.

Les variables d’environnement activent la collecte locale de télémétrie et désactivent son mécanisme facultatif d’envoi. Les requêtes continuent d’être transmises au fournisseur de modèle configuré.

Notez l’adresse du proxy affichée au démarrage. Le port habituel est 8787, mais le wrapper peut choisir un autre port disponible. Dans un second terminal Bash, remplacez le port par celui effectivement utilisé si nécessaire :

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

Confiez maintenant au Claude lancé via le wrapper une tâche délimitée sur un fichier test.log existant et volumineux : lister les tests qui échouent, sans doublons, et citer pour chacun le premier message d’erreur exact, sans modifier de fichiers. Une fois la tâche terminée, interrogez à nouveau /stats.

Un contrôle de santé réussi confirme que le proxy fonctionne. Une hausse de requests.total indique que des requêtes terminées ont été comptabilisées ; examinez séparément requests.failed et requests.rate_limited. La documentation des métriques explique ces champs. Une économie nulle sur un contenu court ou protégé ne prouve pas un problème de routage.

En cas d’échec d’authentification, recherchez les conflits avec ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL et les paramètres du fournisseur avant de réessayer. Si aucune requête n’apparaît, vérifiez le port affiché et le chemin emprunté par la session lancée.

Le mécanisme de compression, mise en cache et récupération de Headroom peut récupérer les originaux conservés lorsque Claude a besoin de détails omis. Cette récupération ajoute du travail et la conservation est limitée dans le temps ; si l’original n’est plus disponible, revenez au fichier source ou relancez la commande.

Après avoir quitté le Claude lancé via le wrapper, nettoyez la configuration de cet essai depuis le terminal d’origine, dans le même projet et avec le port effectivement utilisé :

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

La commande de retrait supprime la configuration gérée par Headroom et tente d’arrêter le proxy correspondant. La suppression de la variable retire de l’environnement la clé API exportée pour cet essai ; vérifiez /status avant de reprendre votre mode d’authentification habituel.

Réservez les modèles moins chers aux sous-tâches bien délimitées

Utilisez un modèle moins cher pour les tâches dont vous pouvez vérifier le résultat à peu de frais, par exemple extraire les échecs d’un log fourni. Cela change le prix du travail effectué, sans garantir une baisse du nombre de tokens.

Pour établir une référence avec les fonctions natives, créez .claude/agents/log-summary.md :

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

Redémarrez Claude Code après avoir créé le répertoire des agents, puis appelez le sous-agent sur un log existant :

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

Consultez /tasks pendant son exécution pour voir le modèle réellement utilisé, puis comparez l’extrait renvoyé au log source. maxTurns limite le nombre de tours, pas les dollars ni les tokens ; atteindre cette limite peut laisser un résultat partiel. Ces champs et les détails du cycle de vie figurent dans la référence des sous-agents.

haiku est un alias : la configuration du fournisseur détermine le modèle concret. Confiez les décisions de conception difficiles ou le débogage ambigu au modèle qui les résout de façon fiable. Un sous-agent bon marché qui nécessite des corrections répétées peut coûter davantage au total.

Si vous utilisez BetterToken pour accéder aux modèles avec une facturation à l’usage, suivez sa configuration pour Claude Code : l’URL de base compatible avec Anthropic est https://bettertoken.ai, sans /v1. Vérifiez ANTHROPIC_DEFAULT_HAIKU_MODEL et les autres correspondances d’alias. Si tous les alias désignent le même identifiant de modèle, choisir haiku ne sélectionne pas un modèle différent et moins cher. Choisissez délibérément des identifiants pris en charge, comparez les tarifs actuels des modèles et du cache, puis vérifiez le modèle et le montant enregistrés. La facturation API de BetterToken est distincte de l’abonnement Claude ; traitez cette configuration de fournisseur séparément de l’essai Headroom avec accès direct à Anthropic décrit plus haut.

Décidez d’après le coût total de la tâche et la justesse du résultat

Ne conservez un outil de compression que s’il améliore le bilan de la tâche terminée, après prise en compte du cache, des sous-agents, des récupérations et des nouvelles tentatives.

Comparez les essais avec le même état du dépôt, le même prompt, le même modèle concret, le même réglage d’effort et la même commande de vérification. Notez si chacun démarre avec un cache déjà alimenté ou un cache froid : mélanger ces conditions peut fausser la comparaison. Vérifiez aussi bien le correctif ou la réponse finale que les éléments précis cités à l’appui.

Dans la comptabilisation de l’API Anthropic, input_tokens, cache_creation_input_tokens et cache_read_input_tokens sont des catégories distinctes ; input_tokens ne représente pas à lui seul toutes les entrées. Incluez aussi les tokens de sortie. Pour des tarifs exprimés par million de tokens, calculez sum(token_count × category_rate / 1,000,000) sur l’ensemble des requêtes, en séparant les écritures de cache selon leur durée lorsque les tarifs diffèrent. Ajoutez les éventuels frais obligatoires qui ne dépendent pas des tokens.

L’affichage du cache de la conversation principale dans Claude Code nécessite la version 2.1.251 ou une version ultérieure et ne couvre pas les sous-agents. Les compteurs d’économies du proxy sont utiles au diagnostic, mais utilisez les relevés de facturation de votre fournisseur pour comparer les dépenses.

Si une erreur omise vous oblige à reprendre l’enquête, si un sous-agent a régulièrement besoin d’aide ou si la récupération reconstitue le volume de contexte initial, réduisez la compression ou revoyez le périmètre de la tâche. L’objectif est un résultat correct avec moins de travail facturé au total.