← Tous les articles

Auto-compact de Claude Code : le réglage de seuil qui existe vraiment.

2026-07-16 · mis à jour le 2026-11-02 · 9 min de lecture · par Nabil BA-MOH

Si tu as cherché un moyen de faire compacter Claude Code plus tôt, tu es sans doute tombé sur la même astuce que nous : ajouter "autoCompactThreshold": 80 à ton settings.json. On l’a testée. Elle ne fait rien. Le réglage qui marche aujourd’hui, c’est /autocompact. Voici ce qu’il fait vraiment, avec les réserves honnêtes.

Tout ce qui suit a été revérifié sur Claude Code v2.1.316 le 2 novembre 2026, à partir du binaire livré et de la doc officielle, pas d’autres articles de blog. La version compte : revérifie après les grosses mises à jour.

Chaque chiffre dit d’où il vient. Documenté : la doc officielle le dit. Déduit : on l’a calculé à partir du code livré, sans l’exécuter. Mesuré : on l’a vu dans une vraie session. À notre avis : c’est notre opinion, rien ne le mesure.

L’auto-compact en une minute

Claude Code travaille dans une fenêtre de contexte fixe. Plus une session grandit, plus la fenêtre se remplit. Quand elle approche du plein, l’auto-compact se déclenche : la conversation est résumée, le résumé remplace l’historique, et la session continue avec de l’air.

Le hic, c’est le moment. Par défaut, la compaction se déclenche près du plafond : vers 967K tokens sur un modèle à fenêtre native de 1M (documenté). À ce stade, le résumeur travaille sous pression, avec une fenêtre presque pleine, et le résumé perd plus de nuances qu’un résumé plus précoce et voulu. Si tu as déjà vu Claude Code revenir d’un compact un peu moins malin sur ta tâche, voilà pourquoi.

Donc la question est légitime : comment avancer le déclencheur ?

L’astuce qui ne marche pas

Une astuce très partagée dit de mettre ceci dans settings.json :

{ "autoCompactThreshold": 80 }

Cette clé n’existe pas comme réglage. Dans le binaire 2.1.316, la chaîne autoCompactThreshold n’apparaît que comme champ interne de remontée : un nom que l’appli utilise pour remonter des métriques, pas un réglage qu’elle lit. Rien dans le chargeur de réglages ne la cherche.

Le piège, c’est qu’elle échoue en silence. settings.json accepte les clés inconnues sans broncher, donc tu ajoutes la ligne, rien ne casse, et tu supposes que ça a marché. Ce n’est pas le cas. Ton seuil n’a jamais bougé.

Le réglage qui existe vraiment : /autocompact

Depuis la v2.1.221, Claude Code a une vraie commande pour ça (documenté) :

/autocompact 433k   # compacte vers 400K sur ce modèle
/autocompact auto   # retour à la fenêtre réglée pour ton modèle

Elle enregistre la valeur dans tes réglages utilisateur, sous le modèle courant, et l’applique à la session en cours (documenté). La valeur va de 100K à 1M tokens (documenté).

Pourquoi 433k pour 400K ? Parce que la valeur est une fenêtre, pas le déclencheur. L’auto-compact se déclenche 33 000 tokens sous la fenêtre : 20 000 réservés à la sortie du modèle, puis une marge de 13 000 (déduit). Donc /autocompact 433k compacte à 400K, et /autocompact 400k compacte à 367K (les deux déduits).

La même fenêtre se règle aussi ailleurs (documenté) :

• Tous les modèles : "autoCompactWindow": 433000 dans un fichier de réglages.
• Un seul modèle : modelSettings.<model>.autoCompactWindow. C’est là qu’écrit /autocompact depuis la v2.1.288.
• Un seul lancement : claude --autocompact 433k.
• Un seul sous-agent : autoCompactWindow dans sa définition.
• Scripts et cloud : la variable d’environnement CLAUDE_CODE_AUTO_COMPACT_WINDOW. Elle passe devant /autocompact, le flag et les deux réglages, et /autocompact signale alors la surcharge sans rien enregistrer.

Quelle que soit la méthode, Claude Code plafonne la valeur à la fenêtre de contexte du modèle (documenté). Une valeur trop haute ne désactive plus rien, et tu n’as plus à la caler sur ton modèle. Deux choses qu’on disait inexistantes existent désormais : une valeur auto et une forme par modèle.

Fenêtre native de 1M aujourd’hui : les modèles Fable, Sonnet 5 et suivants, Haiku 5.5, Opus 4.7 et suivants. Sonnet 4.6 et Opus 4.6 sans contexte étendu restent à la limite de 200K (documenté).

Les interrupteurs marche/arrêt sont toujours là : autoCompactEnabled dans settings.json et DISABLE_AUTO_COMPACT=1. La variable passe devant le réglage (documenté).

La paire de variables marche toujours, avec une autre formule

La paire que cet article mettait en avant existe toujours, et les deux variables figurent maintenant sur la page officielle des variables d’environnement (documenté) :

CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000   # la fenêtre
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40        # un pourcentage de la fenêtre effective

On écrivait la règle window × percentage / 100. C’était trop simple. La règle livrée est la suivante (déduit) :

effective = min(window, model window) - min(max output, 20000)
threshold = min(effective × percentage / 100, effective - 13000)

Donc 40 sur une fenêtre de 1M donne 392 000, pas 400 000 (déduit). Sans pourcentage, le seuil est à 967 000 (déduit), ce qui colle avec les « about 967K » de la doc (documenté). La doc ajoute qu’augmenter CLAUDE_CODE_MAX_OUTPUT_TOKENS réduit la fenêtre effective (documenté) ; dans le code livré, cette réserve s’arrête à 20 000 (déduit).

On fait tourner cette paire. Sans la paire, sur une longue session, l’auto-compact s’est déclenché 19 fois entre 967K et 973K, de la v2.1.306 à la v2.1.312, et une fois à 1 047K en v2.1.316, ce qu’on ne sait pas expliquer. Avec la paire, il s’est déclenché à 406 218 puis à 394 480 tokens (le tout mesuré, et seulement deux compactions avec la paire pour l’instant). Une compaction atterrit au-delà du seuil parce que le contrôle a lieu avant chaque requête au modèle : le dernier tour peut le faire dépasser (déduit).

Le pourcentage a-t-il encore besoin d’une fenêtre ? Pas toujours, d’après ce qu’on lit, mais ce point-là, on ne l’a pas mesuré. Dans le code, il n’est ignoré que tant que la source de la fenêtre est auto. Un modèle à fenêtre native de 1M reçoit une source par défaut à la place, donc le pourcentage seul devrait s’y appliquer (déduit). La doc va dans le même sens : il ne s’applique que dans les sessions qui compactent avant la limite de contexte du modèle (documenté). Sur un modèle qui compacte à sa limite, il est lu, puis ignoré. Définis une fenêtre avec lui et la question disparaît.

Pour rendre la paire permanente, mets les deux dans le bloc env de ~/.claude/settings.json :

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "40"
  }
}

On disait que ça ne touchait que les nouvelles sessions. En v2.1.316, ça n’attend pas : on a ajouté la paire au .claude/settings.local.json d’un projet en pleine session, et la commande shell suivante de cette session a vu les deux variables, sans redémarrage (mesuré). Les 406 218 et 394 480 ci-dessus, c’est cette même session. On a testé ce seul fichier, pas ~/.claude/settings.json lui-même. Un export dans le shell demande toujours une nouvelle session.

Tu passes de la paire à /autocompact ? Retire d’abord les deux variables, puis ouvre une nouvelle session : retirer une variable d’un fichier de réglages ne l’enlève pas d’une session en cours (documenté). La variable de la fenêtre empêche /autocompact d’enregistrer (documenté), et un pourcentage oublié s’applique par-dessus n’importe quelle fenêtre (déduit) : 40 par-dessus /autocompact 433k compacte vers 165K, pas 400K.

Comment le moteur décide : warn, compact, blocked

Sous le capot, Claude Code calcule un niveau à partir du nombre de tokens actuel. Trois niveaux comptent :

• warn : tu es à moins de 20 000 tokens du seuil (déduit). La ligne de statut commence à te prévenir.
• compact : le seuil est atteint. L’auto-compact se déclenche (s’il est activé).
• blocked : tu es près du plafond dur de la fenêtre. Plus de place.

Une fenêtre plus petite descend warn et compact avec elle, loin de la zone blocked où les résumés sont au plus mauvais. Blocked, lui, reste au vrai plafond du modèle (déduit).

Un piège : le used_percentage de la ligne de statut se mesure sur toute la fenêtre de contexte du modèle. Tant que la variable est définie, ce pourcentage ne dit pas quand la compaction aura lieu (documenté). On écrivait que les deux étaient cohérents. Avec la variable, ils ne le sont pas.

Les réserves honnêtes

• Le pourcentage reste un réglage de test à l’intérieur. Il est documenté maintenant, mais le binaire nomme toujours sa valeur comme une surcharge de test, et il a déjà changé une fois, entre 2.1.211 et 2.1.220. Préfère la fenêtre. Revérifie après chaque mise à jour.
• Plus bas n’est pas mieux. Chaque compact coûte une passe de résumé et perd des nuances. Mets-le trop bas et tu compactes sans arrêt, en payant ce prix encore et encore. À notre avis, 40 % à 70 % de la fenêtre, c’est une plage raisonnable. On tourne à 40. Et tu peux seulement avancer le déclencheur, jamais le retarder (documenté) : le seuil s’arrête à la fenêtre moins 33 000, soit 83,5 % d’une fenêtre de 200K et 96,7 % d’une fenêtre de 1M (déduit). Le « vers 83 » qu’on citait ne valait que pour 200K.
• Il ne bouge que le déclencheur automatique. Malgré son nom, la fenêtre d’auto-compact n’agrandit pas ta fenêtre de contexte : elle dit au moteur de compaction quand agir. Elle ne rend pas non plus les résumés meilleurs. Elle leur donne juste de la place.

La meilleure habitude : /compact quand tu le décides

La fenêtre est un filet de sécurité, pas une stratégie. La meilleure compaction, c’est celle que tu lances toi-même : tape /compact à un point d’arrêt naturel (une tâche finie, des résultats écrits dans un fichier, un état sauvegardé). Un compact voulu avec tout sauvegardé bat n’importe quel compact automatique qui tombe en pleine tâche, quel que soit le seuil.

Le schéma qui marche : finir un bloc de travail, sauvegarder ce qui compte sur le disque, puis compacter. La fenêtre existe pour les sessions où tu oublies.

Tu débutes complètement avec Claude Code ? Commence par notre guide pour non-développeurs.

FAQ