Kontext-Backup-Hooks für Claude Code

Problem: Die Auto-Komprimierung ist ein einmaliges Ereignis. Nach vier Stunden Entwicklung übersteigt der Kontext 83%, und der Zusammenfasser feuert. Beim nächsten Turn hat Claude eine Zusammenfassung von dem, was du gemacht hast. Die exakten Fehlermeldungen, Funktions-Signaturen und die zwei Gründe, warum du den ersten Ansatz verworfen hast, sind weg.

Die Zusammenfassung trifft den Rahmen. Die Details überleben nicht.

Schneller Gewinn: Speichere ab 50K verwendeten Tokens ein strukturiertes Backup, dann schreibe alle 10K Tokens ein neues. Dazu kommen prozentuale Auslöser bei 30%, 15% und 5% verbleibend als Sicherheitsnetz für kleinere Fenster. Wenn die Komprimierung schließlich feuert, hast du eine Markdown-Datei mit jeder Nutzeranfrage, jedem Datei-Edit und jeder Entscheidung, die dir wichtig ist.

StatusLine ist der einzige Hook mit Live-Token-Daten

Die meisten Claude Code Hooks sehen keine Kontext-Metriken. PreToolUse, PostToolUse, Stop, keiner von ihnen weiß, wie voll das Fenster ist.

StatusLine ist die Ausnahme. Bei jedem Turn bekommt sie einen JSON-Payload, der context_window.remaining_percentage enthält, also live Zahlen darüber, wie viel Platz noch übrig ist.

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

Kein anderer Mechanismus in Claude Code gibt dir Echtzeit-Sichtbarkeit. Ohne ihn fliegst du blind, bis die Komprimierung zuschlägt.

Die Puffer-Berechnung

Hier ist der Teil, der viele verwirrt. Das Feld remaining_percentage enthält einen festen 33K-Token-Autocompact-Puffer, den du eigentlich nicht nutzen kannst. Die Implementierung berücksichtigt das mit einer token-basierten Berechnung statt eines Prozentsatzes:

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

Bei einem 200K-Fenster sind diese 33K 16,5%. Bei einem 1M-Fenster nur 3,3%. Eine feste Token-Anzahl hält die Mathematik bei jeder Fenstergröße korrekt.

Das duale Auslösesystem

Die Auto-Komprimierung ist reaktiv. Sie feuert, wenn du bereits tief im Fenster bist, und wirft dann Details beim Zusammenfassen weg.

Ein Backup-System muss proaktiv sein. Zwei Auslöse-Schienen laufen parallel:

Token-basierte Auslöser (Primär)

Diese Schiene funktioniert unabhängig von der Fenstergröße gleich. Bei einem 1M-Fenster feuert das erste Backup bei 5% Auslastung. Bei einem 200K-Fenster bei 25% Auslastung. So oder so bekommst du frühe Abdeckung.

Prozentuale Auslöser (Sicherheitsnetz)

Stell dir diese Schiene als Sicherheitsnetz vor. Sie fängt Fälle ab, die die Token-Schiene verpassen könnte, wie Sitzungen, die mit einer großen Prompt-Injektion beginnen. Bei 200K-Fenstern überlappen sich die beiden Schienen. Bei 1M-Fenstern feuert die Token-Schiene zuerst, weil 30% verbleibend bereits bedeutet, dass du 670K+ Tokens verbraucht hast.

Drei-Dateien-Architektur

Ein Produktions-Backup-System will klare Aufgabentrennung. Drei Dateien erledigen die Arbeit:

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

backup-core.mjs

Diese Datei kümmert sich um alles beim Erstellen von Backups:

• Transkript-Parsing: Liest die JSONL-Transkriptdatei und extrahiert Nutzeranfragen, Datei-Änderungen, Aufgaben und Claudes wichtigste Antworten
• Markdown-Formatierung: Strukturiert die Daten als lesbare Markdown-Datei
• Datei-Operationen: Speichert nummerierte Backups mit Zeitstempeln
• Zustandsverwaltung: Verfolgt, welche Sitzung aktiv ist und wie der aktuelle Backup-Pfad lautet

Der Schlüssel: Backups sollen strukturiert sein, keine rohen Dumps. Markdown gruppiert Informationen logisch, damit du beim Wiederherstellen schnell findest, was du brauchst.

statusline-monitor.mjs

Diese läuft bei jedem Turn via StatusLine. Ihre Aufgabe:

1. Berechne verwendete Tokens gesamt und den echten "frei bis Komprimierung"-Prozentsatz
2. Prüfe token-basierte Auslöser (erst 50K, dann alle 10K)
3. Prüfe prozentuale Schwellenwerte als Sicherheitsnetz (30%, 15%, 5%)
4. Löse backup-core aus, wenn ein Auslöser feuert
5. Zeige formatierten Status mit Backup-Pfad an

Der Backup-Pfad erscheint in der Statusline, sobald ein Backup für die aktuelle Sitzung existiert:

[!] 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

Diese zweite Zeile erscheint, sobald du 50K Tokens überschreitest. Kein Warten, bis der Kontext kritisch wird.

conv-backup.mjs

PreCompact-Hooks feuern direkt vor der Komprimierung. Das ist deine letzte Chance, den Zustand zu erfassen. Diese Datei löst backup-core mit precompact_auto oder precompact_manual als Auslösegrund aus.

Stell sie dir als Notfall-Backup vor. StatusLine-basierte Schwellenwerte sind proaktiv. PreCompact ist reaktiv, aber immer noch viel besser als alles zu verlieren.

Konfiguration

Zwei settings.json-Einträge erledigen die Verkabelung:

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

Das async: true bei PreCompact ist wichtig. Backups sollten den Komprimierungsprozess nicht verlangsamen.

Backup-Dateiformat

Dateinamen sind nummeriert und verwenden menschenlesbare Zeitstempel:

.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

Innerhalb jeder Datei bekommst du eine strukturierte Zusammenfassung:

# 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

Kein rohes Transkript. Eine strukturierte Zusammenfassung, die dir sagt, was passiert ist, was sich geändert hat und was noch aussteht.

Der Wiederherstellungs-Workflow

Wenn die Komprimierung passiert:

1. StatusLine zeigt Backup-Pfad: Du siehst genau, welche Datei dein neuestes Backup enthält
2. Führe /clear aus: Starte eine frische Sitzung (sauberer als mit komprimiertem Kontext weiterzumachen)
3. Backup laden: Lies die Markdown-Datei, um den Kontext wiederherzustellen
4. Weiterarbeiten: Claude hat jetzt strukturierten Kontext darüber, was du gemacht hast

Mit komprimiertem Kontext zu arbeiten bedeutet, dass Claude eine Zusammenfassung der Sitzung hat, aber die Einzelheiten verloren gehen. Ein strukturiertes Backup laden gibt dir diese Einzelheiten zurück.

Warum /clear statt Weitermachen?

Nach der Komprimierung existieren zwei Arten von Kontext nebeneinander:

1. Komprimierungs-Zusammenfassung: Automatisch generiert, verlustbehaftet, erfasst den Kern
2. Geladenes Backup: Strukturiert, detailliert, erfasst Einzelheiten

Beides zu haben kann verwirren. Die Zusammenfassung könnte Details im Backup widersprechen. Mit /clear frisch starten und nur das Backup laden gibt saubereren, zuverlässigeren Kontext.

Zustandsverfolgung

StatusLine und PreCompact aktualisieren beide eine gemeinsame Zustandsdatei:

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

Das lässt den StatusLine-Monitor wissen:

• Welche Sitzung er verfolgt (um den Zustand beim Sitzungswechsel zurückzusetzen)
• Wie der letzte Kontext-Prozentsatz war (um das Überschreiten von Schwellenwerten zu erkennen)
• Wie viele Tokens beim letzten Backup verwendet wurden (um das nächste 10K-Intervall zu berechnen)
• Wo das aktuelle Backup liegt (um es in der Statusline anzuzeigen)

Details zum Transkript-Parsing

Das Backup-System parst Claude Codes JSONL-Transkriptdateien, um aussagekräftige Daten herauszuziehen. Hier ist, was es erfasst:

Der Parser entfernt das Rauschen. Tool-Ergebnisse, System-Nachrichten und Eingaben mit einem einzelnen Zeichen werden herausgefiltert, sodass du mit dem zurückbleibst, was für die Sitzungswiederherstellung wirklich wichtig ist.

Warum das besser ist als manuelle Verfolgung

Du könntest wichtigen Kontext während der Arbeit von Hand in eine Datei kopieren. Du wirst es nicht tun. Du bist auf die Implementierung fokussiert, nicht auf Dokumentation.

Das token-basierte System läuft alleine. Ab 50K verwendeten Tokens bekommst du alle 10K Tokens ein Backup, ohne darüber nachzudenken. Cognitive Load ist null.

Und die Backups sind bereits strukturiert. Kein roher Konversations-Dump, sondern organisierte Abschnitte, die du in Sekunden überfliegen kannst.

Vergleich: Auto-Komprimierung vs. Schwellenwert-Backup

Auto-Komprimierung ist der Standard, weil die meisten Nutzer nie ein Backup-System einrichten. Aber wenn du in langen Mehrstunden-Sitzungen lebst, wo Präzision wichtig ist, gibt ein token-basiertes Backup viel bessere Wiederherstellungsoptionen. Bei einem 1M-Kontextfenster bekommst du Dutzende von Snapshots während der gesamten Sitzung, statt alles an ein einzelnes Komprimierungs-Ereignis zu verlieren.

Wichtigste Erkenntnisse

1. StatusLine ist der einzige Live-Kontext-Monitor - Andere Hooks bekommen keine Token-Zahlen
2. Token-basierte Auslöser feuern früh - Erstes Backup bei 50K verwendet, dann alle 10K, unabhängig von der Fenstergröße
3. Prozentuale Schwellenwerte sind das Sicherheitsnetz - 30%, 15%, 5% frei fangen Randfälle bei kleineren Fenstern ab
4. Roher Prozentsatz enthält einen 33K-Puffer - Berechne echtes "frei bis Komprimierung" mit Token-Zahlen
5. Strukturierte Backups schlagen rohe Dumps - Parse Transkripte in organisiertes Markdown
6. Drei-Dateien-Architektur - Klare Trennung zwischen Erkennung, Backup-Logik und Auslösern
7. Wiederherstellungs-Workflow: /clear + laden - Sauberer als komprimierten Kontext mit Backup zu mischen

Weiterführende Ressourcen

• Context Buffer Management - Warum der 33K-45K-Puffer existiert
• Claude Code Hooks Guide - Alle 12 Hook-Typen erklärt
• Context Engineering - Strategische Kontext-Nutzung
• Session Lifecycle Hooks - Setup- und Cleanup-Automatisierung