Buffer de contexte Claude Code

Tu atteins 167K tokens. Claude compacte. Le contexte s'évapore. À. Chaque. Fois.

La partie énervante : une tranche de ta fenêtre de contexte reste hors limites, réservée par Claude Code lui-même. Cette tranche était de 45 000 tokens (22,5% de 200K). Début 2026, le buffer est passé à environ 33 000 tokens (16,5%), libérant environ 12K tokens supplémentaires pour le vrai travail.

Aucune annonce n'a couvert ce changement dans le changelog officiel de Claude Code. L'indice le plus proche est la v2.1.21 : "Fixed auto-compact triggering too early on models with large output token limits", qui a probablement recalibré le calcul du buffer. Les posts en ligne et les docs citent encore les 45K, mais /context affiche maintenant 33K sur les versions actuelles.

Le buffer existe pour de bonnes raisons. Comprendre exactement comment il fonctionne sépare ceux qui se battent contre le système de ceux qui travaillent avec.

Lis cette page quand le buffer lui-même est la question : quand la compaction se déclenche, pourquoi l'espace réservé existe, et quelles variables d'environnement changent vraiment quelque chose. Si tu veux l'impact plus large sur le workflow de la grande fenêtre, lis 1M Context Window in Claude Code. Si tu veux des règles pratiques pour savoir quand rester dans une session ou la réinitialiser, lis Context Management.

Comment l'auto-compaction fonctionne vraiment

L'utilisation du contexte est surveillée en continu par Claude Code. À environ 83,5% de la fenêtre totale (contre ~77-78% avant), l'auto-compaction se déclenche.

Voilà la séquence :

1. Claude résume l'historique de ta conversation
2. Les anciens messages sont remplacés par un résumé condensé
3. Tu perds les détails granulaires du début de session
4. La session continue avec un contexte réduit

Sur une fenêtre de 200K, la compaction arrive autour de 167K tokens d'utilisation réelle. Ces 33K de buffer ne sont pas inactifs. Claude les dépense pour la résumisation elle-même.

La commande /context

Lance /context pour voir exactement où vont tes tokens :

claude-opus-4-5-20251101 · 76k/200k tokens (38%)

System prompt: 2.7k tokens (1.3%)
System tools: 16.8k tokens (8.4%)
Custom agents: 1.3k tokens (0.7%)
Memory files: 7.4k tokens (3.7%)
Skills: 1.0k tokens (0.5%)
Messages: 9.6k tokens (4.8%)
Free space: 118k (58.9%)
Autocompact buffer: 33.0k tokens (16.5%)

La ligne Messages, c'est l'historique de ta conversation. Regarde-la monter. Quand l'espace libre atteint zéro (buffer inclus), la compaction se déclenche.

Pourquoi le buffer existe

Trois rôles tombent sur ces ~33K :

1. Espace de travail pour la compaction. Le processus de résumisation lui-même a besoin de tokens pour fonctionner
2. Buffer de complétion. Permet aux tâches en cours de se terminer avant que la compaction se déclenche
3. Espace de génération de réponse. Claude a besoin de mémoire de travail pour raisonner et construire des réponses

Le buffer est intégré dans l'architecture de Claude Code. Les demandes pour le rendre configurable ont été fermées comme doublons. La GitHub Issue #15435 demandait ça. La réponse a été non.

L'idée fausse sur les tokens de sortie

Beaucoup de développeurs pensent que CLAUDE_CODE_MAX_OUTPUT_TOKENS gouverne le buffer de compaction.

Ce n'est pas le cas.

Deux mécanismes différents, zéro chevauchement :

• Tokens de sortie. Plafonne la durée d'une seule réponse de Claude
• Buffer de compaction. Espace de contexte réservé qui déclenche l'auto-compaction

Mets CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000 et tu réduiras la longueur max de réponse de Claude. Le contexte avant compaction ne bougera pas. Le buffer de 33K est fixe.

# This limits response length, NOT context buffer
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

Raisons de baisser les tokens de sortie :

• Réponses plus rapides (moins à générer)
• Coûts inférieurs par réponse
• Forcer la concision

Le contexte utilisable avant compaction ? Toujours ~167K.

Un caveat qui vaut la peine d'être mentionné : bien que CLAUDE_CODE_MAX_OUTPUT_TOKENS ne touche pas au buffer de compaction, le pousser très haut peut réduire ta fenêtre de contexte effective. Les tokens de sortie sont taillés dans le même pool de contexte, donc une réservation de sortie plus grande prend de la place à l'historique et au contexte système. Le défaut de 32K équilibre bien pour la plupart des workflows.

L'impact en situation réelle

Imagine une session lourde typique :

Avec un buffer de 33K, la compaction arrive à 167K. C'est ton plafond de travail, 12K plus haut que l'ancien de 155K.

Où va l'information ? Dans le résumé. Les noms de variables exacts, les messages d'erreur précis, les choix subtils du début de session se retrouvent tous compressés dans un récap qui capture l'essentiel et perd le détail.

Ce que tu peux vraiment contrôler

1. Remplacer le pourcentage de déclenchement de compaction

Une seule variable d'environnement change vraiment quand l'auto-compaction se déclenche : CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.

# Trigger compaction at 90% instead of the default ~83.5%
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90
 
# Trigger earlier at 70% for more aggressive compaction
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

Les valeurs de 1 à 100 sont acceptées. Le nombre définit directement le pourcentage auquel l'auto-compaction se déclenche. Un réglage plus haut donne plus de contexte utilisable avant compaction et laisse moins d'espace pour le travail de résumé. Un réglage plus bas déclenche la compaction plus tôt, garde plus d'espace de travail, et te donne moins de marge avant le premier hit.

C'est ce qui ressemble le plus à un buffer configurable. Ça ne change pas la taille du buffer. Ça déplace le moment où la compaction se déclenche par rapport à la fenêtre totale.

2. Utiliser des modèles à contexte étendu

Plutôt que de te battre contre le plafond de 200K, utilise la fenêtre de contexte de 1M tokens.

Depuis mars 2026, la fenêtre de contexte 1M est généralement disponible pour Opus 4.6 et Sonnet 4.6, sans premium de prix. Une requête de 900K tokens coûte le même prix par token qu'une de 9K. Voir notre guide fenêtre de contexte 1M pour le détail complet de ce qui a changé et ce que ça signifie pour ton workflow.

/model sonnet[1m]

À 1M tokens, le seuil de compaction s'éloigne considérablement. Même avec un buffer proportionnel, la marge avant la compaction grandit substantiellement. Voir le guide de sélection de modèle pour la référence complète des alias de modèles.

3. Désactiver l'auto-compaction (risqué)

// ~/.claude/settings.json
{
  "autoCompact": false
}

Attention. La GitHub Issue #18264 signale que ce réglage peut être ignoré dans certains cas. Même quand il tient, tu risques de cogner les limites dures de contexte et de faire crasher les sessions.

Ne bascule ça que si tu es prêt à :

• Surveiller le contexte manuellement avec /context
• Lancer /compact avant d'atteindre 100%
• Accepter des crashs de session occasionnels

4. Compaction manuelle à des moments stratégiques

Désactive l'auto-compact, puis compacte quand tu décides :

/compact   # Compact when you decide
/clear     # Full reset when starting new major task

Bons moments pour compacter intentionnellement :

• Après avoir terminé une fonctionnalité majeure
• Avant de commencer un nouveau composant
• Quand le contexte de débogage semble périmé

Avantage : tu choisis ce qui est résumé et quand, ce qui garde les détails fins autour du travail actif.

5. Travailler dans la limite des 167K

Accepte que les sessions lourdes vont compacter. Configure-toi pour ça :

• Garde CLAUDE.md et les skills légers
• Utilise des fichiers de session pour persister l'état
• Découpe les tâches complexes en plusieurs sessions

6. Stratégie de sauvegarde proactive

Le mouvement le plus efficace : sauvegarder avant que la compaction arrive.

Une idée qui prend de l'ampleur dans la communauté Claude Code : un clear proactif à 50% plus une récupération structurée bat l'auto-compaction avec perte.

L'auto-compaction condense ta conversation et abandonne le détail fin. Mais fais plutôt ça :

1. Enregistre ta session en continu dans une sauvegarde structurée
2. Efface le contexte manuellement à un seuil (comme 50%)
3. Recharge depuis la sauvegarde structurée plutôt que depuis le résumé avec perte

La fidélité du contexte monte. La sauvegarde tient les détails exacts que la résumisation jette.

Comment choisir ton mode de fonctionnement

La plupart des gens n'ont pas besoin d'un réglage magique. Ils ont besoin du bon mode pour le type de travail qu'ils font.

La bonne question n'est pas "comment battre le buffer ?" C'est "combien coûte un compact avec perte pour cette session ?"

Trois exemples concrets

Exemple 1 : Build de feature classique

Tu construis une fonctionnalité, tu touches quelques fichiers, et la session ne devrait pas dépasser 100K tokens.

Meilleur choix :

• utilise les défauts
• vérifie /context une ou deux fois
• ne sur-ingénierise pas

Le buffer n'est pas ton problème ici.

Exemple 2 : Session de débogage avec beaucoup d'impasses

Tu passes 40 minutes à inspecter logs, traces et hypothèses ratées. Tu sais déjà que la prochaine phase sera l'implémentation.

Meilleur choix :

• ne pas attendre l'autocompact
• lance /compact focus on the confirmed root cause, affected files, and fix plan
• continue vers l'implémentation

Ça garde le diagnostic utile tout en supprimant le bruit.

Exemple 3 : Session de contenu ou d'audit haute précision

Suppose que tu audites un flux de sécurité ou que tu écris un article sourcé. Les citations exactes, les chemins de fichiers et les comportements observés comptent.

Meilleur choix :

• garde une sauvegarde structurée ou un fichier de notes
• efface plus tôt que d'habitude
• restaure depuis la sauvegarde exacte plutôt que de faire confiance à un résumé compacté

C'est là où le workflow de sauvegarde gagne. Le problème n'est pas la capacité brute. C'est la fidélité de l'information.

Quand changer CLAUDE_AUTOCOMPACT_PCT_OVERRIDE

Cette variable est utile, mais seulement dans des cas spécifiques.

Augmente-la quand :

• la tâche actuelle est cohérente et tu veux plus de marge avant compaction
• tu surveilles activement l'utilisation
• le coût d'un compact trop précoce est plus élevé que le risque d'attendre

Baisse-la quand :

• la session est désordonnée et tu veux des résumés plus tôt
• tu acceptes des compactions plus fréquentes
• tu veux que Claude garde un ensemble de travail plus serré

Laisse-la tranquille quand :

• tu ne surveilles pas le contexte activement
• tu n'as pas de raison claire de changer le déclencheur
• le vrai problème est le changement de tâche, pas la compaction

Changer le déclencheur ne remplace pas de bonnes limites de session. Ça déplace juste le moment où le même mécanisme sous-jacent se déclenche.

StatusLine : le seul moniteur en temps réel

StatusLine est le seul mécanisme qui obtient des métriques de contexte en temps réel. Les autres hooks ne reçoivent pas les comptes de tokens.

// .claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/context-monitor.mjs"
  }
}

La statusline reçoit du JSON avec context_window.remaining_percentage. Ce sont des données en direct, prêtes à agir.

Calcul critique. Le champ remaining_percentage compte déjà le buffer d'autocompact de 16,5%. Pour le vrai "libre jusqu'à l'autocompact" :

const AUTOCOMPACT_BUFFER_PCT = 16.5;
const freeUntilCompact = Math.max(
  0,
  remaining_percentage - AUTOCOMPACT_BUFFER_PCT,
);

25% restants signifie vraiment 8,5% avant la compaction.

Pourquoi les hooks ne peuvent pas injecter /clear

Un mur technique que beaucoup de gens rencontrent : les hooks ne peuvent pas injecter des commandes slash.

Supposition raisonnable : un hook détecte une utilisation élevée du contexte et injecte /clear. Il ne peut pas :

• UserPromptSubmit n'a pas de champ updatedPrompt. Il peut ajouter du contexte ou bloquer, mais jamais remplacer
• Les commandes slash sautent entièrement l'évaluation des hooks
• Aucun hook ne se déclenche "à la place de" l'entrée utilisateur

Vraies façons d'effacer et de récupérer programmatiquement :

1. Claude Agent SDK. Envoie /clear via le SDK
2. Wrapper CLI headless. Pipe des commandes vers Claude Code headless
3. Workflow manuel. Le hook te prévient, tu lances /clear, SessionStart restaure

Ce qui se passe à 100% de contexte

Pousse le contexte jusqu'au bout et voilà ce qui suit :

1. Meilleur cas. La réponse de Claude est tronquée
2. Cas pire. L'API retourne une erreur, le tour échoue
3. Pire cas. La session devient non réactive

Le buffer de 33K est là pour empêcher que ça arrive. C'est de la protection, pas du gaspillage.

Points clés

1. Le buffer vient de passer de 45K à 33K. Changement non documenté, environ 12K tokens utilisables en plus
2. La compaction se déclenche maintenant à ~83,5% d'utilisation. Ça place le contexte utilisable autour de ~167K (contre ~155K avant)
3. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE déplace le déclencheur. Les valeurs de 1 à 100 définissent quand la compaction se déclenche
4. sonnet[1m] offre 1M tokens de contexte. Une vraie alternative à lutter contre les limites de 200K
5. Les tokens de sortie et le buffer de compaction sont séparés. Ne les confonds pas
6. autoCompact: false peut fonctionner. Il a aussi des bugs signalés
7. StatusLine est le seul moniteur de contexte en direct. Les autres hooks ne voient pas les comptes de tokens
8. Les hooks ne peuvent pas injecter /clear. Passe par le SDK, un wrapper, ou un workflow manuel
9. Un clear proactif plus une récupération structurée bat l'auto-compaction avec perte

Le buffer est là pour de bonnes raisons. Plutôt que de se battre contre lui, travaille avec : garde l'état dans des fichiers de session, lance des sauvegardes sur seuil avant la compaction, et pense à un clear proactif pour les sessions lourdes.

La solution : sauvegardes sur seuil

Le buffer est fixe. La façon dont tu gères l'approche ne l'est pas.

Consulte notre système de sauvegarde sur seuil pour un setup proactif qui surveille le contexte via StatusLine et crée des sauvegardes à 30%, 15% et 5% restants, avant que la compaction efface l'historique de ta session.

Ressources associées

• Context Recovery Hook - Système de sauvegarde sur seuil
• Context Engineering Guide - Utilisation stratégique du contexte
• Memory Optimization - Réduire la surcharge de contexte statique
• Claude Code Hooks Guide - Les 12 types de hooks expliqués