/compact dans Claude Code : ce que ça coûte, ce qui survit

Le même /compact peut vous coûter quelques centimes ou deux dollars, et ce n'est pas la taille du contexte qui décide. C'est le cache. La documentation d'Anthropic sur le prompt caching dans Claude Code le dit sans détour : pour écrire le résumé, Claude Code envoie une requête séparée qui porte tout votre historique, et « tant que le cache est chaud, cette requête lit votre préfixe depuis le cache, si bien qu'un /compact en milieu de session coûte une fraction de ce que suggère la taille du contexte ». Après une pause plus longue que la durée de vie du cache, la même requête « retraite tout l'historique comme une entrée non cachée ». C'est pour ça que /compact coûte le plus cher juste après la reprise d'une vieille session.

La plupart des guides sur la compaction de Claude Code s'arrêtent à « ça résume votre conversation » et à une règle empirique sur le bon moment. Celui-ci met la mécanique des coûts à côté des règles de survie, et nomme les alternatives, pour que vous sachiez quel geste est bon marché au moment où vous allez le faire.

TL;DR

• /compact envoie une requête supplémentaire qui contient toute votre conversation plus une consigne de résumé. Tant que le prompt cache est chaud, elle lit cet historique au prix du cache ; une fois le cache expiré, elle paie le prix d'entrée plein.
• Le tour qui suit la compaction est bon marché : il ne reconstruit le cache que pour le résumé, qui est court.
• CLAUDE.md, la mémoire automatique, le plan et un git status frais reviennent depuis le disque. Les règles limitées à des chemins, les CLAUDE.md imbriqués et tout ce qu'un hook a injecté plus tôt sont absorbés dans le résumé.
• L'auto-compact se déclenche près de la limite du modèle : vers 967K tokens sur les modèles à fenêtre de 1M, à 200K sur les configurations à 200K. /autocompact déplace ce seuil.
• /clear ne coûte rien, /rewind réutilise un cache qui existe déjà, et /recap résume sans toucher au cache. Choisissez /compact quand vous avez besoin de continuité et que le cache est encore chaud.

Ce que fait vraiment /compact

La compaction remplace votre historique de messages par un résumé écrit par le modèle. L'article d'Anthropic sur la gestion des sessions (Thariq Shihipar, 15 avril 2026) la décrit comme « avec perte, mais vous n'avez rien eu à écrire vous-même », et vous pouvez l'orienter avec des consignes comme /compact focus on the auth refactor, drop the test debugging.

Mécaniquement, la page sur le prompt caching décrit quatre étapes :

1. Claude Code envoie une requête séparée avec le même prompt système, les mêmes outils et le même historique que votre conversation, la consigne de résumé étant ajoutée comme dernier message utilisateur.
2. Le modèle écrit le résumé. Depuis la v2.1.198, cette requête hérite du réglage d'extended thinking de votre session, d'après la page sur la fenêtre de contexte.
3. Claude Code remplace l'historique par le résumé et recharge le contexte projet (CLAUDE.md, mémoire) depuis le disque.
4. Votre tour suivant construit une nouvelle entrée de cache pour l'historique raccourci.

Deux conséquences en découlent. D'abord, la compaction invalide par construction la couche « conversation » du cache, puisque le nouvel historique ne partage aucun préfixe avec l'ancien. La couche du prompt système, elle, survit. Ensuite, comme CLAUDE.md est rechargé depuis le disque, toute modification que vous y avez faite en cours de session prend effet à ce moment-là : la doc précise que CLAUDE.md est « lu une fois au démarrage de la session » et qu'une nouvelle version « se charge au prochain /clear, /compact ou redémarrage ». Si vous avez modifié CLAUDE.md depuis le début de la session, ce rechargement est aussi un cache miss sur la couche du contexte projet.

Dans une session neuve, /compact ne sert à rien. La page sur les coûts indique qu'il affiche Not enough messages to compact. quand il n'y a pas d'historique à résumer.

Pour la vue d'ensemble, c'est-à-dire pourquoi chaque tour renvoie toute la conversation, notre explication sur la façon dont la fenêtre de contexte pilote votre facture de tokens couvre le mécanisme de base sur lequel s'appuie cette section.

Ce que coûte la compaction : cache chaud ou cache froid

Le chiffre qui compte n'est pas la taille de votre contexte. C'est de savoir si le préfixe en cache est encore vivant quand la requête de résumé part.

La durée de vie du cache dépend de votre façon de payer. Le tableau des TTL dans la doc de Claude Code répartit les requêtes en deux groupes :

La compaction se range dans le second groupe, mais la doc précise que l'appel de résumé utilise la même approche de partage de préfixe que les subagents : il lit donc le cache construit par votre conversation principale. Ce qui décide de l'existence de ce cache, c'est la durée de votre inactivité : moins d'une heure sur un abonnement, moins de cinq minutes sur une clé API.

Voici ce que ça donne en dollars, avec les tarifs publiés du prompt caching pour Claude Opus 5.5 au 1er octobre 2026 : 4 $ par million de tokens d'entrée, 0,20 $ par million pour les lectures de cache, 5 $ et 8 $ par million pour les écritures de cache à 5 minutes et à 1 heure. C'est de l'arithmétique sur les prix catalogue, pas une facture mesurée, et elle laisse de côté les tokens de sortie du résumé lui-même.

• 400K tokens d'historique, cache chaud : 400 000 × 0,20 $ / 1M = 0,08 $ d'entrée pour la requête de résumé.
• 400K tokens d'historique, cache froid : 400 000 × 4 $ / 1M = 1,60 $ d'entrée, vingt fois plus pour la même commande.

Sur Sonnet 5.5 (2 $ en entrée, 0,20 $ la lecture de cache par million, sur la même page), la même compaction à froid coûte 0,80 $ d'entrée et celle à chaud reste à 0,08 $. L'écart entre chaud et froid est le rapport entre le prix d'entrée et le prix de lecture du cache : il se creuse donc sur les modèles les plus chers.

Sur un plan Pro ou Max, vous ne voyez pas de dollars, mais les mêmes tokens comptent dans vos limites. La page sur les coûts range la compaction parmi les raisons pour lesquelles l'usage grimpe dans une longue session : « /compact lit la conversation qu'il résume, donc compacter un gros contexte est en soi une grosse requête. » Pour le côté plan, voir comment fonctionnent les limites d'usage de Claude.

La règle pratique qui en découle : compactez pendant que vous travaillez encore, pas après le déjeuner. Si vous revenez sur une grosse session après expiration du cache, Claude Code sur Pro ou Max propose de reprendre à partir d'un résumé, ce qui revient au même arbitrage, fait au moment le moins cher.

Ce qui survit à la compaction, et ce qui disparaît sans bruit

La documentation sur la fenêtre de contexte donne un tableau mécanisme par mécanisme. En condensé :

Trois détails de ce tableau expliquent la plupart des signalements du type « Claude a oublié X après la compaction ».

Les fichiers de plus de 5 000 tokens reviennent sous forme de simple chemin. Claude Code relit jusqu'à cinq fichiers, les plus récemment modifiés d'abord, mais un gros fichier revient comme Referenced file sans son contenu. Si le modèle a besoin de ce fichier, il le relit, et vous payez la lecture une deuxième fois. Notre guide sur la compression en squelette des lectures de fichiers couvre les façons de rendre ces relectures plus légères.

Les skills sont tronqués par la fin. La troncature garde le début de SKILL.md, et les skills invoqués les plus anciens tombent en premier une fois le budget de 25 000 tokens dépassé. La doc conseille de mettre les consignes les plus importantes en haut du fichier. Plus de détails sur ce que les skills coûtent en contexte dans Les skills de Claude Code : ce qu'ils sont, ce qu'ils coûtent.

Les règles limitées à des chemins disparaissent jusqu'au prochain déclenchement. Une règle avec un frontmatter paths: entre dans l'historique quand son fichier déclencheur est lu, donc la compaction l'absorbe dans le résumé. Si une règle doit tenir toute la session, la doc recommande de retirer le frontmatter paths: ou de la déplacer dans le CLAUDE.md à la racine du projet. Ses tokens passent alors dans chaque tour : c'est un arbitrage qui ne vaut que pour les règles qui comptent. Comment un CLAUDE.md trop gros gonfle votre facture montre ce que coûte cet arbitrage.

Quand l'auto-compact se déclenche

L'auto-compact est la même passe que /compact, déclenchée pour vous. La page de configuration des modèles liste les valeurs par défaut :

• Les modèles qui tournent avec une fenêtre native de 1M compactent « vers 967K tokens par défaut ». Sur l'API Anthropic, cela couvre Sonnet 5, les modèles Fable et Opus 4.7 et suivants.
• Sonnet 4.6 et Opus 4.6 sans contexte étendu compactent à la limite des 200K, tout comme Opus 4.8 et suivants quand ils tournent avec une fenêtre de 200K sur Bedrock, Google Cloud ou Foundry.
• CLAUDE_CODE_DISABLE_1M_CONTEXT=1 limite les modèles 1M à 200K, et ils compactent à ce niveau.
• Un identifiant de modèle inconnu, comme un alias de gateway, compacte à la fenêtre que Claude Code lui suppose.

Vous pouvez déplacer le seuil avec /autocompact 500k (enregistré dans vos réglages utilisateur sous autoCompactWindow), avec le flag --autocompact pour un seul lancement, ou avec la variable d'environnement CLAUDE_CODE_AUTO_COMPACT_WINDOW, qui prime sur les deux. La commande et le flag acceptent de 100K à 1M tokens.

Attendre la valeur par défaut a un coût en qualité en plus du coût en tokens. L'article d'Anthropic sur la gestion des sessions le formule ainsi : « à cause du context rot, le modèle est au plus bas de son intelligence au moment de compacter. » Il explique aussi les mauvaises compactions : elles arrivent « quand le modèle ne peut pas prévoir la direction que prend votre travail », par exemple quand une longue session de débogage est résumée et que votre message suivant porte sur un avertissement que le résumé a écarté. Notre entrée de glossaire sur le context rot couvre l'effet sous-jacent.

Il y a aussi un coût de timing. L'auto-compact se déclenche en pleine tâche, là où tombe le seuil. La page sur le prompt caching recommande de lancer /compact « à une pause naturelle de votre travail, par exemple entre deux tâches, plutôt que d'attendre que l'auto-compaction se déclenche en pleine tâche », pour choisir le moment où le surcoût tombe.

/compact, /clear, /rewind, /recap : lequel, quand

Quatre commandes réduisent ou remodèlent ce que voit le modèle. Elles diffèrent par leur coût et par ce qu'elles gardent.

/clear démarre une nouvelle conversation. La page sur les coûts est directe : « Quand vous voulez repartir de zéro plutôt que garder la continuité, /clear ne coûte rien. » Le prix, c'est l'effort : vous écrivez le brief vous-même (« on refactore le middleware d'auth, la contrainte est X, les fichiers qui comptent sont A et B »), et le modèle repart de ce que vous avez jugé pertinent. La règle empirique d'Anthropic : une nouvelle tâche mérite une nouvelle session.

/rewind (double Échap) tronque jusqu'à un tour antérieur. Comme « l'historique restant est le même contenu que celui à partir duquel le cache a été construit à ce moment-là », la requête suivante tombe sur l'entrée de cache antérieure. Utilisez-le quand Claude est parti sur une mauvaise piste : gardez les lectures de fichiers utiles, jetez la tentative ratée, relancez avec ce que vous avez appris. /rewind propose aussi « Summarize from here » et « Summarize up to here » pour compacter une partie de la conversation.

/recap génère un résumé affiché dans votre terminal. Contrairement à /compact, il ajoute le résumé comme sortie de commande au lieu de remplacer votre historique, donc le préfixe en cache reste intact. Il vous remet dans le contexte ; il ne libère aucune place.

/compact garde la continuité sans que vous ayez à écrire quoi que ce soit. C'est le bon choix en pleine tâche quand la session est pleine d'explorations périmées dont vous n'aurez plus besoin, et que le cache est encore chaud.

Une cinquième option évite le problème : envoyer le travail qui produit beaucoup de sortie jetable à un subagent, pour que les lectures de fichiers restent dans sa fenêtre de contexte et que seul le résultat revienne. Le test d'Anthropic : « aurai-je encore besoin de cette sortie d'outil, ou seulement de la conclusion ? » Les subagents ont leur propre coût de démarrage ; mesurer l'usage de tokens d'un agent IA explique comment vérifier si la délégation a été rentable dans votre session.

Orienter ce que garde le résumé

Vous disposez de trois leviers sur le contenu du résumé, tous documentés.

Des consignes sur la ligne de commande. /compact Focus on code samples and API usage dit à Claude quoi préserver. La page sur les coûts utilise exactement cet exemple.

Une section permanente dans CLAUDE.md. La même page montre un titre # Compact instructions dans le CLAUDE.md à la racine du projet, par exemple « When you are using compact, please focus on test output and code changes ». Comme le CLAUDE.md racine est réinjecté après chaque compaction, ces consignes restent disponibles pour chaque résumé.

Un hook SessionStart sur la source compact. Le guide des hooks montre un hook SessionStart avec "matcher": "compact" dont la sortie standard est ajoutée au contexte compacté :

Le guide propose git log --oneline -5 comme remplacement dynamique d'un echo statique. Tout ce que ce hook affiche, vous le payez à chaque tour jusqu'à la compaction suivante : gardez-le court. Les hooks PreCompact et PostCompact existent aussi, avec les matchers manual et auto, si vous voulez journaliser chaque compaction ou y réagir. Les hooks font partie des leviers listés dans notre guide pour réduire l'usage de tokens de Claude Code.

Mesurer ce que la compaction a fait à votre session

Claude Code rend compte directement du comportement du cache. Depuis la v2.1.251, /usage ajoute une ligne Prompt cache (main) avec le nombre de requêtes, la part de l'entrée servie depuis le cache, les misses et les « expected rebuilds », que la page sur les coûts définit comme les misses causés par Claude Code lui-même quand il réécrit la conversation « par compaction ou en effaçant d'anciens résultats d'outils ». La ligne d'exemple de la doc affiche 1 expected rebuild (compaction or tool-result clearing).

Sur un plan Pro, Max, Team ou Enterprise, le détail de /usage signale aussi des comportements comme le contexte long ou les cache misses quand l'un d'eux représente 10 % ou plus de l'usage récent. Si la compaction y revient sans cesse, la correction est en général une question de timing (compacter plus tôt, à chaud) ou de périmètre (faire un /clear entre deux tâches).

/context donne en direct la répartition de ce qui remplit la fenêtre par catégorie, y compris les fichiers CLAUDE.md et de mémoire chargés, selon la page sur la fenêtre de contexte. Lancez-le avant et après une compaction pour voir ce qui est revenu. Pour compter les tokens d'une session à l'autre indépendamment de l'outil, voir comment mesurer l'usage de tokens d'un agent IA et nos statistiques d'usage de tokens de Claude Code.

Erreurs fréquentes

• Compacter juste après avoir repris une vieille session. Le cache a expiré, donc la requête de résumé paie l'entrée pleine sur tout l'historique. Utilisez l'option « reprendre à partir d'un résumé » sur Pro ou Max, ou un /clear avec un brief court.
• Utiliser /compact pour changer de tâche. Vous payez le résumé d'un travail dont vous n'avez plus besoin, et le résumé le transporte dans la nouvelle tâche. /clear est gratuit et plus propre.
• Corriger une tentative ratée au lieu de revenir en arrière. « Ça n'a pas marché, essaie X » garde la tentative ratée dans le contexte. /rewind la retire et tombe sur un cache qui existe déjà.
• Compter sur des règles limitées à des chemins pendant une longue session. Elles disparaissent à la compaction jusqu'à ce qu'un fichier correspondant soit relu. Déplacez les règles critiques dans le CLAUDE.md racine.
• Enfouir les consignes clés en bas d'un skill. Les skills réinjectés sont tronqués par la fin au-delà de 5 000 tokens.
• Laisser l'auto-compact choisir le moment. Il se déclenche en pleine tâche, quand le context rot est au pire, et résume sans savoir où vous allez ensuite.

À faire cette semaine

1. Ajoutez une section # Compact instructions au CLAUDE.md racine de votre projet. Deux lignes qui nomment ce que le résumé doit garder dans ce dépôt (sorties de tests, fichiers en cours de modification). Résultat attendu : moins de moments « il a oublié X » après l'auto-compact, pour quelques dizaines de tokens par tour.
2. Abaissez votre seuil d'auto-compact si vous travaillez sur un modèle 1M. /autocompact 500k est l'exemple de la doc. Résultat attendu : la compaction tourne plus tôt, sur un contexte plus petit et moins dégradé, donc la requête de résumé est moins chère et meilleure.
3. Lancez /usage à la fin d'une longue session. Regardez la ligne Prompt cache (main) : misses contre expected rebuilds. Si les misses dominent, le cache expire entre vos tours ; compactez avant les pauses, pas après.
4. Faites de /clear votre réflexe entre deux tâches. Gardez /compact pour le nettoyage en pleine tâche quand le cache est chaud, et /rewind pour les impasses.

FAQ

Que fait /compact dans Claude Code ? Il remplace votre historique de conversation par un résumé écrit par le modèle. Claude Code envoie une requête séparée avec tout votre historique et une consigne de résumé, remplace l'historique par le résultat, puis recharge CLAUDE.md, la mémoire automatique, le plan et un git status frais depuis le disque. Jusqu'à cinq fichiers récemment modifiés sont relus, et les skills invoqués sont réinjectés dans un budget de 5 000 tokens par skill et 25 000 au total, d'après la doc sur la fenêtre de contexte.

Est-ce que /compact consomme des tokens ? Oui. La requête de résumé porte toute votre conversation. Tant que le cache est chaud, elle lit cet historique au prix d'une lecture de cache, soit 0,20 $ par million de tokens sur Opus 5.5 contre 4 $ pour l'entrée non cachée (tarifs au 1er octobre 2026). Une fois le cache expiré, elle paie le prix d'entrée plein sur tout l'historique. Les tokens de sortie du résumé s'ajoutent.

Est-ce que /clear coûte moins cher que /compact ? Oui. La page sur les coûts indique que /clear ne coûte rien. La contrepartie, c'est la continuité : vous écrivez vous-même le brief de la session suivante, alors que /compact l'écrit pour vous. Pour un travail sans rapport, /clear est le meilleur choix, en coût comme en qualité.

Quand l'auto-compact se déclenche-t-il ? Sur les modèles à fenêtre native de 1M, vers 967K tokens par défaut. Sur les configurations à 200K, à la limite des 200K. Un identifiant de modèle inconnu compacte à la fenêtre que Claude Code lui suppose. Vous pouvez changer ce seuil avec /autocompact, le flag --autocompact ou CLAUDE_CODE_AUTO_COMPACT_WINDOW, entre 100K et 1M tokens (doc de configuration des modèles).

Pourquoi Claude a-t-il oublié quelque chose après la compaction ? Soit le résumé l'a écarté, soit l'information venait d'un mécanisme qui ne survit pas : règles limitées à des chemins, CLAUDE.md imbriqués, contexte injecté par des hooks, ou contenu d'un fichier de plus de 5 000 tokens. Anthropic note que les mauvaises compactions arrivent quand le modèle ne peut pas prévoir où va le travail : passer des consignes à /compact aide.

Modifier CLAUDE.md en cours de session prend-il effet après /compact ? Oui. Les fichiers CLAUDE.md racine et utilisateur sont lus une fois au démarrage et gardés en mémoire ; une nouvelle version se charge au prochain /clear, /compact ou redémarrage, d'après la doc sur le prompt caching.

Peut-on garder un contexte important d'une compaction à l'autre ? Mettez-le dans le CLAUDE.md racine (relu depuis le disque à chaque fois), dans une section # Compact instructions, ou dans un hook SessionStart avec le matcher compact, dont la sortie est ajoutée après chaque compaction. Chacune de ces options ajoute des tokens à chaque tour : restez court.

Quelle différence entre /compact et /recap ? /compact remplace votre historique par un résumé et libère du contexte. /recap affiche un résumé dans votre terminal et l'ajoute comme sortie de commande, sans toucher à l'historique ni au préfixe en cache. Utilisez /recap pour vous resituer, /compact pour faire de la place.

À lire aussi

• Réduire les tokens sur les longues sessions d'agent : les habitudes de session dont la compaction fait partie.
• Prompt caching : comment réduire votre facture d'entrée : d'où vient l'écart entre cache chaud et cache froid.
• Limites de Claude Code : comment rester en dessous : la place de la compaction quand vous approchez d'une limite de plan.
• CLAUDE.md : comment un fichier trop gros gonfle votre facture : le coût de déplacer des règles dans le fichier qui survit à la compaction.
• Comment réduire l'usage de tokens de Claude Code : la liste complète des leviers au-delà de la compaction.
• Context rot : pourquoi une compaction tardive produit un moins bon résumé.
• Économies du prompt caching : les vrais chiffres : des taux de lecture de cache mesurés, à comparer à votre ligne /usage.