← Tous les articles

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

2026-07-16 · mis à jour le 2026-08-01 · 6 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. Alors on a lu le code que Claude Code livre vraiment et on a trouvé le réglage qui marche. Le voici, avec les réserves honnêtes.

Tout ce qui suit a été vérifié sur Claude Code v2.1.211 en lisant le binaire livré, pas en citant d’autres articles de blog, puis revérifié sur v2.1.220 le 1er août 2026. La version compte : revérifie après les grosses mises à jour.

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. À 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.211, la chaîne autoCompactThreshold n’apparaît que comme champ de télémétrie interne : 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é.

Ce qui est officiellement documenté

La doc officielle des réglages te donne exactement deux interrupteurs, tous les deux en marche/arrêt :

• autoCompactEnabled dans settings.json. Booléen, true par défaut. Mets-le à false et l’auto-compact ne se déclenche jamais.
• La variable d’environnement DISABLE_AUTO_COMPACT=1. Même effet.

Pas de seuil. Officiellement, l’auto-compact, c’est tout ou rien.

Le réglage qui existe vraiment (c’est une paire maintenant)

Le binaire lit deux variables d’environnement que la doc des réglages ne mentionne jamais :

CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000   # la vraie fenêtre de contexte de ton modèle
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40        # déclenche à 40 % de cette fenêtre

La règle : le seuil d’auto-compact devient window × percentage / 100 tokens. Avec un modèle à fenêtre de 1M et 40, l’auto-compact se déclenche vers 400 000 tokens, au lieu de presque tout en haut.

Quand on a publié cet article, la surcharge de pourcentage seule suffisait sur la version qu’on avait lue (2.1.211). Sur les versions actuelles, non : la surcharge ne s’applique que quand la compaction tourne en mode proactif, et une session locale normale n’est proactive que si CLAUDE_CODE_AUTO_COMPACT_WINDOW est défini aussi. Définis le pourcentage seul et il est lu, puis ignoré. C’est le même échec silencieux que celui qu’on dénonçait plus haut, et c’est exactement pour ça que cette mise à jour existe.

Deux pièges dans la valeur de la fenêtre :

• Elle doit correspondre à la vraie fenêtre de contexte de ton modèle. Mets-la plus haut et le seuil calculé tombe au-delà du vrai plafond : la compaction proactive ne se déclenche jamais et tu reviens à compacter contre le mur. En août 2026 : 1 000 000 pour la génération actuelle Opus / Sonnet / Fable, 200 000 pour Haiku 4.5.
• Elle est statique. Claude Code ne l’adapte pas au modèle que tu fais vraiment tourner : pas de valeur « auto » ni de forme par modèle. Si tu mélanges des modèles à 1M et à 200K, définis-la par projet dans le .claude/settings.json du projet plutôt qu’une fois en global.

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"
  }
}

Ou exporte-les dans le profil de ton shell. Dans les deux cas, elles s’appliquent aux nouvelles sessions, pas à celle en cours.

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. 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.

Le pourcentage de la ligne de statut et ces niveaux sont cohérents entre eux, donc ce que tu vois, c’est ce sur quoi le moteur agit. Baisser la surcharge descend toute l’échelle : tu es prévenu plus tôt et compacté plus tôt, loin de la zone blocked où les résumés sont au plus mauvais.

Les réserves honnêtes

• Ce n’est pas documenté. Dans le binaire, la variable de pourcentage est nommée comme une surcharge de test. Elle peut changer ou disparaître à n’importe quelle version, sans préavis. Elle a déjà changé une fois entre 2.1.211 et 2.1.220, c’est tout le sujet de cette mise à jour. 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. 40 à 70, c’est une plage raisonnable. On tourne à 40. Note aussi que le pourcentage est plafonné vers 83 : il peut avancer le déclencheur par rapport au défaut, jamais le retarder.
• Il ne bouge que le déclencheur automatique. Malgré son nom, CLAUDE_CODE_AUTO_COMPACT_WINDOW n’agrandit pas ta fenêtre de contexte : il dit au moteur de compaction quelle est la fenêtre. La paire 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 surcharge 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 surcharge existe pour les sessions où tu oublies.

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

FAQ