Claude Code : réduire le contexte et les coûts

Comment éviter qu’une longue session Claude Code ralentisse et devienne coûteuse

Une longue session Claude Code ralentit et devient coûteuse, car chaque tour renvoie l’intégralité du contexte, qui ne cesse de s’allonger. La solution consiste à appliquer une hygiène stricte, dans un ordre précis. Exécutez /context pour voir ce qui remplit la fenêtre de contexte, supprimez les éléments facturés à chaque requête, puis utilisez /clear entre deux tâches sans rapport et /compact avec une instruction au sein d’une même tâche longue. Travaillez par séquences continues, car un cache de prompt froid transforme une lecture peu coûteuse en une réécriture complète de tout ce que vous avez indiqué.

La raison pour laquelle le compteur avance est expliquée dans le compteur de tokens utilisé par une session d’agent.

Lisez le contexte avant toute modification

Ne devinez pas ce qui remplit la fenêtre. Claude Code vous l’indiquera.

/context [all] affiche l’utilisation actuelle du contexte sous forme de grille colorée, avec des suggestions d’optimisation pour les outils gourmands en contexte et la croissance excessive de la mémoire ; all développe la ventilation par élément en mode plein écran. Interprétez le résultat comme cinq compartiments.

• L’invite système. Les instructions du propre harness de Claude Code. Elles restent fixes pendant la session.
• Les définitions des outils. Le schéma de chaque outil que l’agent peut appeler, y compris celui de chaque serveur MCP (Model Context Protocol) connecté.
• Les fichiers mémoire. CLAUDE.md et la mémoire automatique, chargés au début de la session.
• Les fichiers et les résultats des outils. Chaque fichier lu et tout ce que vos commandes renvoient.
• L’historique des messages. Vos tours et ses réponses.

Les trois premiers représentent un coût fixe, payé à chaque requête pendant toute la durée de la session. Les deux derniers augmentent. Réduisez le coût fixe une fois, au début, puis gérez en continu la partie croissante.

Deux chaînes indiquent que la fenêtre est pleine :

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

La première correspond à une limite stricte : la requête est refusée et l’erreur de l’API (application programming interface) correspondante est Prompt is too long. La seconde correspond à une fenêtre de compaction, qui peut être inférieure à la fenêtre de contexte réelle sur un modèle de 1 million de tokens. Les requêtes continuent donc de fonctionner au-delà de cette limite ; il s’agit d’un avertissement, pas d’un refus.

Avec un forfait payant, /usage ajoute l’autre moitié en signalant des comportements comme un contexte long ou des cache misses, et en attribuant l’utilisation récente aux skills, subagents et serveurs MCP concernés. S’il indique que le quota est déjà épuisé, la fenêtre de limites que vous attendez détermine si la réduction du contexte vous aidera maintenant ou si vous devez emprunter une autre voie pour reprendre le travail.

CLAUDE.md est un coût permanent : gardez-le concis

Votre CLAUDE.md est chargé au début de la session et y reste. S’il contient une procédure de déploiement détaillée, ces tokens sont présents lorsque vous corrigez une faute dans un fichier de test. Les recommandations d’Anthropic consistent à n’y inclure que l’essentiel et à limiter le fichier à 200 lignes.

Déplacez les procédures dans des skills. Un skill est chargé uniquement lorsqu’il est invoqué ; un workflow exécuté deux fois par semaine ne coûte donc rien les autres jours. Après une compaction, les skills disposent de leur propre budget : leur contenu est réinjecté, avec une limite de 5,000 tokens par skill et de 25,000 au total ; les plus anciens sont supprimés en premier. La troncature conserve le début du fichier : placez donc les instructions les plus importantes près du début de SKILL.md.

Ce qui survit à une compaction détermine l’emplacement d’une instruction.

• Le system prompt et le style de sortie restent inchangés, car ils ne font pas partie de l’historique des messages.
• Le CLAUDE.md à la racine du projet, les règles non limitées à un périmètre et la mémoire automatique sont réinjectés depuis le disque.
• Une règle avec un frontmatter paths: est perdue jusqu’à la relecture d’un fichier correspondant.
• Un CLAUDE.md imbriqué dans un sous-répertoire est perdu jusqu’à la lecture d’un fichier situé dans ce sous-répertoire.
• Les hooks ne sont pas affectés, car un hook s’exécute comme du code et n’entre jamais dans le contexte.

Une règle dont vous dépendez doit donc se trouver dans le CLAUDE.md à la racine du projet : Claude Code efface d’abord les sorties d’outils les plus anciennes, puis les résume ; les instructions du début de la conversation peuvent donc être perdues. Modifiez la mémoire avec /memory. Claude Code conserve la copie chargée au début de la session ; une réduction en cours de session conserve donc le prompt cache et ne s’applique qu’au prochain /clear, /compact ou redémarrage. La perte de contexte n’est qu’une des raisons pour lesquelles une règle cesse d’être respectée. Lorsque la règle est manifestement toujours présente dans la fenêtre de contexte mais reste ignorée, examinez les autres causes avant de la réécrire.

/clear entre les tâches, /compact dans une même tâche

Ces deux commandes semblent interchangeables, mais leur coût est très différent.

/clear [name] démarre une nouvelle conversation avec un contexte vide. Elle n’envoie aucune requête et ne coûte donc rien. Fournissez un nom pour étiqueter la conversation précédente dans le sélecteur /resume ; /reset et /new sont des alias. Utilisez-la dès que vous passez à une tâche sans rapport, car l’ancienne tâche serait sinon renvoyée et facturée à nouveau à chaque message de la nouvelle tâche.

/compact [instructions] libère de l’espace dans le contexte tout en poursuivant la même conversation : la commande résume l’historique jusque-là, puis le remplace par ce résumé. Utilisez-la au cours d’une tâche longue, lorsque vous devez conserver la continuité.

Donnez toujours une instruction à /compact. Un /compact seul résume le contenu selon un prompt par défaut qui ne sait pas quelle partie du travail vous devez encore conserver. Une commande avec instruction conserve les éléments demandés :

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Si vous utilisez la compaction pour la même raison à chaque fois, ajoutez une instruction persistante dans le CLAUDE.md de votre projet, sous un titre # Compact instructions. Dans une nouvelle session, /compact affiche Not enough messages to compact., ce qui signifie seulement qu’il n’existe encore aucun historique.

Deux coûts sont souvent confondus ici. La requête de résumé partage votre préfixe. Elle lit donc le cache existant au lieu de retraiter l’historique, et l’essentiel de son temps est consacré à la génération du résumé. Compacter un contexte volumineux reste une requête volumineuse, car la conversation résumée constitue son entrée. Le tour suivant la compaction n’est pas la partie lente : il reconstruit le cache pour un prompt beaucoup plus court.

Deux commandes moins coûteuses existent. /rewind [description] restaure le code et la conversation jusqu’à un point de contrôle. Pour un chemin que vous voulez abandonner complètement, cette commande est préférable à la compaction, car elle tronque la conversation jusqu’à un préfixe déjà mis en cache. /recap ajoute un résumé comme sortie de commande au lieu de remplacer l’historique. Le préfixe mis en cache reste donc intact.

Lorsqu’une compaction automatique se déclenche plusieurs fois de suite, le message suivant s’affiche :

Autocompact is thrashing: the context refilled to the limit...

La compaction a réussi, mais un fichier ou une sortie d’outil a de nouveau rempli la fenêtre plusieurs fois de suite. Claude Code a donc cessé de réessayer. Pour récupérer, lisez le fichier volumineux par plages de lignes, exécutez /compact avec un focus qui exclut la sortie volumineuse, déplacez ce travail vers un sous-agent ou utilisez /clear si la conversation précédente est terminée.

Les serveurs MCP représentent une surcharge fixe

Chaque serveur MCP auquel vous vous connectez augmente la taille de chaque requête pendant toute la session. Vous en payez le coût, que vous l’appeliez ou non.

Claude Code atténue ce problème. Par défaut, les définitions des outils MCP sont différées. Seuls les noms des outils sont donc ajoutés au contexte, jusqu’à ce que Claude utilise un outil précis. Exécutez /context pour voir le coût réel de vos serveurs, puis /mcp disable <name> pour supprimer celui que vous n’utiliserez pas aujourd’hui. Si vous exécutez vos propres serveurs MCP sur un VPS, le même calcul limite le nombre d’outils qu’un serveur devrait exposer.

Faites-le au début d’une session. Tant que les définitions restent différées, la connexion ou la déconnexion d’un serveur ajoute seulement des éléments à la conversation, et le cache est conservé. En revanche, si les définitions sont chargées dans le préfixe parce que la recherche d’outils est désactivée ou qu’un serveur n’est pas concerné par le report, la même modification oblige la requête suivante à tout relire.

Filtrez la sortie verbeuse des outils avant son ajout au contexte

Le résultat d’un outil devient une entrée, puis est renvoyé à chaque tour suivant. Une exécution de test qui produit 20,000 tokens de sortie ne représente pas un coût ponctuel : vous le payez à nouveau à chaque tour jusqu’à ce que cette sortie quitte la fenêtre de contexte.

Filtrez à la source. Un hook qui réduit une exécution de test à ses échecs avant que Claude ne la reçoive transforme cette sortie interminable en quelques centaines de tokens, lors de ce tour et à chaque renvoi :

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Les hooks n’entrent jamais eux-mêmes dans le contexte, car ils s’exécutent sous forme de code. Appliquez cette méthode à tout outil dont la sortie dépasse un écran. La même logique s’applique à un fichier de 3,000 lignes : demandez la plage de lignes nécessaire, car une fois le fichier reçu, il reste entièrement dans la fenêtre de contexte.

Cadrer ce que l’agent lit et déléguer les tâches verbeuses

Un prompt qui nomme le fichier et le symptôme lit ce fichier. Une demande ouverte visant à nettoyer le projet lit tous les éléments que l’agent juge pertinents, et chacune de ces lectures reste dans le contexte.

Déléguez les tâches verbeuses à un sous-agent. Les exécutions de tests et le traitement des journaux consomment tous deux une part réelle du contexte ; un sous-agent conserve cette sortie dans sa propre fenêtre et ne renvoie qu’un résumé. En contrepartie, un sous-agent construit son propre cache, sans aucun hit lors du premier appel, et utilise la durée de vie du cache de cinq minutes, même avec un abonnement. La délégation protège efficacement votre contexte principal. Elle ne réduit pas toujours le nombre total de tokens.

L’horloge du cache : travaillez par sessions continues

Le prompt caching rend le renvoi abordable : 0.1x le tarif d’entrée de base pour lire le préfixe, contre 1.25x pour l’écrire, ou 2x avec une durée de vie d’une heure. Chaque utilisation actualise l’entrée sans coût supplémentaire : l’horloge repart donc de la dernière utilisation. Ces multiplicateurs indiquent la structure de la facture, mais pas son montant. Associez-les à ce que coûtent réellement un million de tokens pour convertir une fenêtre de contexte complète en montant.

La durée de vie dépend du mode d’authentification. C’est pourquoi l’affirmation générale « votre cache expire après cinq minutes » est incorrecte.

• Avec un abonnement Claude, Claude Code demande automatiquement une durée de vie d’une heure.
• Une fois la limite de votre forfait dépassée et les crédits d’utilisation utilisés, cette utilisation vous est facturée et la durée repasse à cinq minutes.
• Avec une clé API ou un fournisseur cloud, la durée reste de cinq minutes. ENABLE_PROMPT_CACHING_1H=1 active la durée d’une heure, tandis que FORCE_PROMPT_CACHING_5M=1 la ramène à cinq minutes.

Le conseil reste le même dans tous les cas : travaillez par sessions continues. Une période d’inactivité qui dépasse la durée de vie oblige la requête suivante à réécrire tout le préfixe accumulé. Une session Claude Code détachée dans tmux ne coûte rien pendant son inactivité, mais le cache chaud est perdu pendant cette période.

Certaines actions suppriment le cache alors que vous travaillez encore : changer de modèle, modifier le niveau d’effort, activer le fast mode, connecter ou déconnecter un serveur MCP, activer ou désactiver un plugin, refuser un outil entier, effectuer une compactation ou mettre à niveau Claude Code. /model est la cause de surprise la plus fréquente : chaque modèle possède son propre cache. La requête suivante relit donc tout l’historique sans utiliser le cache, même si le contenu est identique. Cette relecture est facturée selon les tarifs du modèle cible. Ainsi, un changement de modèle vers Fable en cours de session facture tout l’historique accumulé au tarif d’entrée publié de Fable 5.

Modifier des fichiers, modifier CLAUDE.md, invoquer des skills et des commandes, exécuter /recap, revenir en arrière et lancer un subagent préservent le cache. Le cache est limité à une machine et à un répertoire. Deux sessions situées dans des répertoires différents ne peuvent donc pas utiliser le cache de l’autre. Cette portée dépend du CLI et non de votre compte. Rien ne se transfère donc vers l’application de bureau Claude, qui est sous Linux une installation bêta distincte du CLI.

Pour vérifier que la mise en cache fonctionne, consultez current_usage. cache_creation_input_tokens a été écrit au tarif d’écriture du cache ; cache_read_input_tokens a été servi à environ un dixième du tarif d’entrée standard. Un ratio élevé entre les lectures et les créations est normal. Si le coût de création reste élevé à chaque tour, c’est qu’un élément de votre préfixe continue de changer.

Une fenêtre de contexte plus grande résout-elle le problème ?

Partiellement. Plusieurs modèles actuels prennent en charge une fenêtre de contexte de 1 million de tokens, et la compaction fonctionne de la même manière avec cette limite plus élevée. Le modèle économique ne change pas, car l’intégralité du prompt est toujours renvoyée et facturée à chaque tour. Une fenêtre plus grande détermine le moment où vous êtes obligé d’intervenir ; l’hygiène détermine le coût. Si le problème est la facture plutôt que la limite, quel forfait Claude correspond à votre façon de travailler détermine si vous dépensez des dollars ou votre quota de forfait.

La modification et la condensation du contexte dans l’API sont deux mécanismes différents

Si vous développez votre propre agent avec l’API Messages, aucune commande slash n’existe et vous devez l’implémenter vous-même. Prévoyez ce travail dès le départ, car l’API ne propose pas de niveau gratuit au-delà d’un petit crédit d’inscription : chaque tour d’historique non tronqué est facturé intégralement. Le fournisseur choisi détermine ce calcul avant toute troncature. Si le choix n’est pas encore arrêté, calculez le coût de la même charge sur les deux API au lieu de comparer uniquement les tarifs affichés par token. Deux fonctionnalités côté serveur permettent de gérer ce problème. Elles ne sont pas équivalentes.

La modification du contexte efface sélectivement certains contenus de l’historique de la conversation au fur et à mesure qu’il s’allonge. Chaque élément effacé est remplacé par un texte d’espace réservé afin que Claude sache qu’un contenu a été supprimé. Cette fonctionnalité est en bêta : envoyez anthropic-beta: context-management-2025-06-27 et configurez les stratégies sous context_management.edits. clear_tool_uses_20250919 efface les résultats des outils, tandis que clear_thinking_20251015 gère les blocs de réflexion. Sa valeur trigger est par défaut de 100,000 tokens d’entrée, keep de conserver les 3 dernières utilisations d’outils et clear_tool_inputs de false. Les entrées sont donc conservées et seuls les résultats sont supprimés.

La condensation génère un résumé et remplace l’historique complet de la conversation par ce résumé. Cette fonctionnalité est également en bêta : envoyez anthropic-beta: compact-2026-01-12 et utilisez le type de modification compact_20260112. Le déclenchement par défaut est {"type": "input_tokens", "value": 150000}, et la valeur doit être d’au moins 50,000.

La condensation applique une règle de transmission qui casse discrètement certains agents. La réponse commence par un bloc de contenu compaction contenant le résumé, suivi du bloc de texte habituel. Vous devez retransmettre ce bloc dans les requêtes suivantes. L’API supprime alors tous les blocs de contenu qui le précèdent. En pratique, ajoutez l’intégralité de response.content, et pas seulement le texte.

La documentation d’Anthropic présente la condensation côté serveur comme la stratégie principale pour gérer le contexte dans les conversations longues. Elle présente la modification du contexte comme l’option offrant un contrôle plus précis sur les éléments supprimés. Vérifiez d’abord la compatibilité des modèles. Les modèles Opus, Sonnet et Fable actuels prennent en charge la condensation. claude-haiku-4-5 ne la prend pas en charge, et la page consacrée à la condensation contient la liste à jour. Aucune des deux fonctionnalités bêta ne pilote le propre /compact de Claude Code, que sa documentation décrit comme une demande de résumé ponctuelle envoyée par le client.

FAQ

Pourquoi ma session Claude Code devient-elle plus lente et plus coûteuse au fil du temps ?

Parce que l’ensemble de la conversation est renvoyé à chaque tour. Ainsi, une question d’une ligne dans une session ouverte toute la journée inclut tout l’historique de la journée. Le prompt caching maintient ce coût à un niveau faible tant que le cache est disponible : une lecture est facturée à 0.1x du tarif d’entrée de base. Dès qu’un tour ne trouve pas son contenu dans le cache, le même préfixe est réécrit à 1.25x. Exécutez /context pour voir ce qui occupe la fenêtre de contexte, puis consultez ce que vous facture une session Claude Code pour comprendre le mécanisme.

Quelle est la différence entre /clear et /compact dans Claude Code ?

/clear démarre une nouvelle conversation avec un contexte vide. Il n’envoie aucune requête, donc il ne coûte rien. C’est le bon choix entre deux tâches sans rapport. /compact conserve la même conversation et remplace l’historique par un résumé. C’est donc le bon choix au cours d’une même tâche longue. Indiquez-lui un objectif, comme dans /compact keep only the plan and the diff, car cette instruction détermine ce qui est conservé.

Comment voir ce qui occupe ma fenêtre de contexte Claude Code ?

Exécutez /context, ou /context all pour obtenir le détail complet par élément. La commande affiche l’invite système, les définitions des outils, les serveurs MCP, les fichiers de mémoire et l’historique sous forme de grille colorée. Elle propose aussi des suggestions concernant les outils qui consomment beaucoup de contexte et la mémoire excessive. Avec un forfait payant, /usage attribue également l’utilisation récente aux skills, aux sous-agents et aux serveurs MCP concernés.

Dois-je utiliser une fenêtre de contexte de 1 million de tokens plutôt que compacter le contexte ?

Une fenêtre plus grande retarde le problème, mais ne le résout pas. Plusieurs modèles actuels utilisent une fenêtre de contexte de 1 million de tokens, notamment Opus 4.8 et Sonnet 5, et la compaction fonctionne de la même manière avec ces modèles. Chaque tour renvoie toujours l’intégralité du prompt et est toujours facturé en conséquence. Une conversation de 400,000 tokens coûte donc cher, qu’elle tienne ou non dans la fenêtre.

Quelle est la différence entre la modification du contexte et la compaction dans l’API Claude ?

La modification du contexte efface sélectivement l’ancien contenu, principalement les résultats des outils, et laisse à la place de chacun un texte indicatif afin que Claude sache qu’il a été supprimé. La compaction génère un résumé et remplace l’historique complet par celui-ci. La documentation d’Anthropic présente la compaction comme la stratégie principale pour les conversations longues et la modification du contexte comme l’option plus fine. Les deux fonctionnalités sont en version bêta, utilisent leurs propres headers et sont distinctes de /compact de Claude Code.