Hooks de sauvegarde de contexte pour Claude Code

Problème : la compaction automatique est un événement unique. Quatre heures dans un build, le contexte dépasse 83%, et le résumeur se déclenche. Au tour suivant, Claude a un aperçu de ce que tu as fait. Les chaînes d'erreur exactes, les signatures de fonctions, et les deux raisons pour lesquelles tu as abandonné la première approche ont disparu.

Le résumé capture l'esquisse. Les détails ne survivent pas.

Solution rapide : sauvegarde un snapshot structuré à partir de 50K tokens utilisés, puis écrit-en un nouveau toutes les 10K tokens après ça. En plus de ça, des déclencheurs en pourcentage à 30%, 15% et 5% libres agissent comme filet de sécurité pour les fenêtres plus petites. Quand la compaction se déclenche enfin, tu as un fichier markdown avec chaque requête utilisateur, chaque modification de fichier, et chaque décision qui t'importe.

StatusLine est le seul hook avec des données de tokens en direct

La plupart des hooks Claude Code ne voient pas les métriques de contexte. PreToolUse, PostToolUse, Stop, aucun d'eux ne sait à quel point la fenêtre est pleine.

StatusLine est l'exception. À chaque tour, il reçoit un payload JSON qui inclut context_window.remaining_percentage, donc tu as des chiffres en direct sur la place restante.

{
  "session_id": "abc123...",
  "context_window": {
    "remaining_percentage": 35.5,
    "context_window_size": 200000
  }
}

Aucun autre mécanisme dans Claude Code ne te donne une visibilité en temps réel. Sans ça, tu voles à l'aveugle jusqu'à ce que la compaction frappe.

Le calcul du buffer

Voilà la partie qui surprend. Le champ remaining_percentage inclut un buffer d'autocompact fixe de 33K tokens que tu ne peux pas vraiment utiliser. L'implémentation tient compte de ça avec un calcul basé sur les tokens plutôt que sur un pourcentage :

const AUTOCOMPACT_BUFFER_TOKENS = 33000;
const autocompactBufferPct = (AUTOCOMPACT_BUFFER_TOKENS / windowSize) * 100;
const freeUntilCompact = Math.max(0, pctRemainTotal - autocompactBufferPct);

Sur une fenêtre de 200K, ce buffer de 33K représente 16.5%. Sur une fenêtre de 1M, c'est seulement 3.3%. Un nombre fixe de tokens garde le calcul correct sur toutes les tailles de fenêtre.

Le système de double déclencheur

La compaction automatique est réactive. Elle se déclenche une fois que tu es déjà profond dans la fenêtre, puis jette des détails pendant la résumisation.

Un système de sauvegarde doit être proactif. Deux rails de déclenchement fonctionnent en parallèle :

Déclencheurs basés sur les tokens (primaire)

Ce rail fonctionne pareil quelle que soit la taille de la fenêtre. Sur une fenêtre de 1M, la première sauvegarde se déclenche à 5% d'utilisation. Sur une fenêtre de 200K, à 25% d'utilisation. Dans tous les cas, tu as une couverture précoce.

Déclencheurs basés sur le pourcentage (filet de sécurité)

Pense à ce rail comme le filet de sécurité. Il attrape les cas que le rail de tokens pourrait manquer, comme les sessions qui s'ouvrent avec une grosse injection de prompt. Sur des fenêtres de 200K les deux rails se chevauchent. Sur des fenêtres de 1M, c'est le rail de tokens qui se déclenche en premier, parce qu'atteindre 30% de restant signifie déjà que tu as brûlé 670K+ tokens.

Architecture à trois fichiers

Un système de sauvegarde en production veut une séparation claire des responsabilités. Trois fichiers font le travail :

.claude/hooks/ContextRecoveryHook/
├── backup-core.mjs        # Shared backup logic
├── statusline-monitor.mjs # Threshold detection + display
└── conv-backup.mjs        # PreCompact hook trigger

backup-core.mjs

Ce fichier gère tout ce qui concerne la création de sauvegardes :

• Parsing de transcript : lit le fichier de transcript JSONL et extrait les requêtes utilisateur, modifications de fichiers, tâches, et réponses clés de Claude
• Formatage markdown : structure les données en fichier markdown lisible
• Opérations sur les fichiers : sauvegarde des backups numérotés avec timestamps
• Gestion d'état : suit quelle session est active et quel est le chemin de sauvegarde actuel

L'insight clé : les sauvegardes doivent être structurées, pas des dumps bruts. Le markdown regroupe les informations logiquement pour que tu trouves ce dont tu as besoin rapidement lors d'une récupération.

statusline-monitor.mjs

Celui-ci tourne à chaque tour via StatusLine. Son boulot :

1. Calculer les tokens totaux utilisés et le vrai pourcentage "libre jusqu'à compaction"
2. Vérifier les déclencheurs basés sur les tokens (50K d'abord, puis toutes les 10K)
3. Vérifier les seuils en pourcentage comme filet de sécurité (30%, 15%, 5%)
4. Déclencher backup-core quand un déclencheur se déclenche
5. Afficher le statut formaté avec le chemin de sauvegarde

Le chemin de sauvegarde apparaît dans la statusline dès qu'une sauvegarde existe pour la session actuelle :

[!] Opus 4.6 | 65k / 1m | 6% used 65,000 | 90% free 900,000 | thinking: On
-> .claude/backups/3-backup-18th-Feb-2026-2-15pm.md

Cette deuxième ligne apparaît dès que tu dépasses 50K tokens. Pas d'attente jusqu'à ce que le contexte devienne critique.

conv-backup.mjs

Les hooks PreCompact se déclenchent juste avant que la compaction se produise. C'est ta dernière chance de capturer l'état. Ce fichier déclenche backup-core avec precompact_auto ou precompact_manual comme raison de déclenchement.

Pense à ça comme la sauvegarde d'urgence. Les seuils basés sur StatusLine sont proactifs. PreCompact est réactif, mais quand même bien mieux que tout perdre.

Configuration

Deux entrées settings.json font le câblage :

{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/ContextRecoveryHook/statusline-monitor.mjs"
  },
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/ContextRecoveryHook/conv-backup.mjs",
            "async": true
          }
        ]
      }
    ]
  }
}

Le async: true sur PreCompact est important. Les sauvegardes ne doivent pas ralentir le processus de compaction.

Format des fichiers de sauvegarde

Les noms de fichiers sont numérotés et utilisent des timestamps lisibles par les humains :

.claude/backups/1-backup-26th-Jan-2026-4-30pm.md
.claude/backups/2-backup-26th-Jan-2026-5-15pm.md
.claude/backups/3-backup-26th-Jan-2026-5-45pm.md

À l'intérieur, tu obtiens un résumé structuré :

# Session Backup
 
**Session ID:** abc123...
**Trigger:** tokens_60k_update
**Context Remaining:** 94.0%
**Generated:** 2026-01-26T17:45:00.000Z
 
## User Requests
 
- Create two blog posts about context management
- Add the new post to blog-structure.ts
- Fix the internal linking
 
## Files Modified
 
- apps/web/src/content/blog/guide/mechanics/context-buffer-management.mdx
- apps/web/src/content/blog/tools/hooks/context-recovery-hook.mdx
- apps/web/src/content/blog/blog-structure.ts
 
## Tasks
 
### Created
 
- **Write Post 1: Context Buffer Management**
- **Write Post 2: Context Recovery Hook**
 
### Completed
 
- 2 tasks completed
 
## Skills Loaded
 
- content-writer

Pas un transcript brut. Un résumé structuré qui te dit ce qui s'est passé, ce qui a changé, et ce qui est encore en attente.

Le workflow de récupération

Quand la compaction se produit :

1. StatusLine affiche le chemin de sauvegarde : tu vois exactement quel fichier a ta dernière sauvegarde
2. Lance /clear : démarre une session fraîche (plus propre que de continuer avec un contexte compacté)
3. Charge la sauvegarde : lis le fichier markdown pour restaurer le contexte
4. Continue le travail : Claude a maintenant un contexte structuré de ce que tu faisais

Travailler avec un contexte compacté signifie que Claude a un résumé de la session mais a perdu les détails. Charger une sauvegarde structurée te donne ces détails en retour.

Pourquoi /clear plutôt que de continuer ?

Après la compaction, deux types de contexte coexistent :

1. Résumé de compaction : auto-généré, avec perte, capture l'essentiel
2. Sauvegarde chargée : structurée, détaillée, capture les détails

Garder les deux peut créer de la confusion. Le résumé peut contredire des détails de la sauvegarde. Repartir à zéro avec /clear et charger uniquement la sauvegarde donne un contexte plus propre et plus fiable.

Suivi d'état

StatusLine et PreCompact mettent à jour un fichier d'état partagé :

// ~/.claude/claudefast-statusline-state.json
{
  "sessionId": "abc123...",
  "lastFreeUntilCompact": 25.5,
  "lastBackupAtTokens": 60000,
  "currentBackupPath": ".claude/backups/3-backup-18th-Feb-2026-2-15pm.md"
}

Ça permet au moniteur StatusLine de savoir :

• Quelle session il suit (pour réinitialiser l'état quand les sessions changent)
• Quel était le dernier pourcentage de contexte (pour détecter les franchissements de seuil en pourcentage)
• Combien de tokens étaient utilisés à la dernière sauvegarde (pour calculer le prochain intervalle de 10K)
• Où se trouve la sauvegarde actuelle (pour l'afficher dans la statusline)

Détails du parsing de transcript

Le système de sauvegarde parse les fichiers de transcript JSONL de Claude Code pour extraire des données significatives. Voici ce qu'il capture :

Le parser élimine le bruit. Les résultats d'outils, les messages système, et les entrées à un seul caractère sont filtrés, donc tu te retrouves avec ce qui compte vraiment pour la récupération de session.

Pourquoi c'est mieux que le suivi manuel

Tu pourrais copier le contexte important dans un fichier à la main pendant que tu travailles. Tu ne le feras pas. Tu es focalisé sur l'implémentation, pas sur la documentation.

Le système basé sur les tokens tourne tout seul. À partir de 50K tokens utilisés, tu obtiens une sauvegarde toutes les 10K tokens sans y penser. La charge cognitive est nulle.

Et les sauvegardes sont déjà structurées. Pas un copier-coller brut de conversation, mais des sections organisées que tu peux scanner en quelques secondes.

Comparaison : compaction automatique vs sauvegarde par seuil

La compaction automatique est la valeur par défaut parce que la plupart des utilisateurs ne configurent jamais un système de sauvegarde. Mais si tu vis dans des sessions longues de plusieurs heures où la précision est importante, une sauvegarde basée sur les tokens te donne de bien meilleures options de récupération. Sur une fenêtre de contexte de 1M, tu te retrouveras avec des dizaines de snapshots capturés tout au long de la session au lieu de tout perdre dans un seul événement de compaction.

Points clés à retenir

1. StatusLine est le seul moniteur de contexte en direct : les autres hooks n'ont pas accès aux compteurs de tokens
2. Les déclencheurs basés sur les tokens se déclenchent tôt : première sauvegarde à 50K utilisés, puis toutes les 10K, quelle que soit la taille de la fenêtre
3. Les seuils en pourcentage sont un filet de sécurité : 30%, 15%, 5% libres captent les cas limites sur les fenêtres plus petites
4. Le pourcentage brut inclut un buffer de 33K : calcule le vrai "libre jusqu'à compaction" en utilisant les compteurs de tokens
5. Les sauvegardes structurées battent les dumps bruts : parse les transcripts en markdown organisé
6. Architecture à trois fichiers : séparation propre entre détection, logique de sauvegarde, et déclencheurs
7. Workflow de récupération : /clear + chargement : plus propre que de mélanger contexte compacté et sauvegarde

Ressources liées

• Gestion du buffer de contexte : pourquoi le buffer de 33K-45K existe
• Guide des hooks Claude Code : les 12 types de hooks expliqués
• Ingénierie du contexte : utilisation stratégique du contexte
• Hooks du cycle de vie de session : automatisation du setup et du nettoyage