Hooks de Backup de Contexto para o Claude Code

Problema: A compactação automática é um evento único. Quatro horas numa build, o contexto passa 83%, e o summarizer dispara. Na próxima volta, o Claude tem um resumo do que fizeste. As strings de erro exatas, as assinaturas de funções, e os dois motivos pelos quais deitaste fora a primeira abordagem desapareceram.

O resumo acerta no essencial. Os detalhes não sobrevivem.

Solução Rápida: Guarda um backup estruturado a partir dos 50K tokens usados, depois escreve um novo a cada 10K tokens. Além disso, triggers de percentagem a 30%, 15%, e 5% livres servem como rede de segurança para janelas mais pequenas. Quando a compactação finalmente disparar, tens um ficheiro markdown com cada pedido do utilizador, cada edição de ficheiro, e cada decisão que te interessa.

StatusLine é o Único Hook com Dados de Tokens ao Vivo

A maioria dos hooks do Claude Code não vê métricas de contexto. PreToolUse, PostToolUse, Stop — nenhum deles sabe quão cheia está a janela.

StatusLine é a exceção. Em cada volta recebe um payload JSON que inclui context_window.remaining_percentage, por isso tens números ao vivo de quanto espaço resta.

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

Nenhum outro mecanismo no Claude Code dá visibilidade em tempo real. Sem isto, estás a voar às cegas até a compactação aparecer.

O Cálculo do Buffer

Aqui está a parte que confunde as pessoas. O campo remaining_percentage inclui um buffer fixo de 33K tokens de autocompact que não podes usar de facto. A implementação considera isso com um cálculo baseado em tokens em vez de percentagem:

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

Numa janela de 200K, esse buffer de 33K representa 16,5%. Numa janela de 1M, é apenas 3,3%. Um contador fixo de tokens mantém a matemática correta em todos os tamanhos de janela.

O Sistema de Dois Triggers

A compactação automática é reativa. Dispara quando já estás fundo na janela, depois perde detalhes durante a summarização.

Um sistema de backup precisa de ser proativo. Dois rails de triggers correm lado a lado:

Triggers Baseados em Tokens (Primário)

Este rail funciona igual independentemente do tamanho da janela. Numa janela de 1M, o primeiro backup dispara a 5% de uso. Numa janela de 200K, dispara a 25% de uso. De qualquer forma, tens cobertura antecipada.

Triggers Baseados em Percentagem (Rede de Segurança)

Pensa neste rail como a rede de segurança. Apanha casos que o rail de tokens pode perder, como sessões que abrem com uma injeção de prompt grande. Em janelas de 200K os dois rails sobrepõem-se. Em janelas de 1M, o rail de tokens é o que dispara primeiro, porque atingir 30% restante significa que já queimaste 670K+ tokens.

Arquitetura de Três Ficheiros

Um sistema de backup em produção precisa de separação de responsabilidades. Três ficheiros fazem o trabalho:

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

backup-core.mjs

Este ficheiro trata de tudo o que tem a ver com criar backups:

• Parsing de transcrição: Lê o ficheiro de transcrição JSONL e extrai pedidos do utilizador, modificações de ficheiros, tarefas, e respostas-chave do Claude
• Formatação markdown: Estrutura os dados como ficheiro markdown legível
• Operações de ficheiro: Guarda backups numerados com timestamps
• Gestão de estado: Acompanha qual sessão está ativa e qual é o caminho do backup atual

O insight chave: backups devem ser estruturados, não dumps em bruto. Markdown agrupa informação logicamente para que encontres o que precisas rapidamente ao recuperar.

statusline-monitor.mjs

Este corre em cada volta via StatusLine. O seu trabalho:

1. Calcular tokens totais usados e a percentagem "livre até compactação" real
2. Verificar triggers baseados em tokens (50K primeiro, depois a cada 10K)
3. Verificar limiares de percentagem como rede de segurança (30%, 15%, 5%)
4. Acionar backup-core quando qualquer trigger dispara
5. Mostrar status formatado com caminho do backup

O caminho do backup aparece na statusline assim que existe um backup para a sessão atual:

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

Essa segunda linha aparece assim que passas 50K tokens. Sem esperar até o contexto ficar crítico.

conv-backup.mjs

Os hooks PreCompact disparam mesmo antes da compactação acontecer. É a tua última hipótese de capturar estado. Este ficheiro aciona backup-core com precompact_auto ou precompact_manual como razão do trigger.

Pensa nisto como o backup de emergência. Os limiares baseados em StatusLine são proativos. PreCompact é reativo, mas ainda muito melhor do que perder tudo.

Configuração

Duas entradas no settings.json fazem a ligação:

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

O async: true no PreCompact importa. Backups não devem atrasar o processo de compactação.

Formato do Ficheiro de Backup

Os nomes dos ficheiros são numerados e usam timestamps legíveis:

.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

Dentro de cada um, tens um resumo estruturado:

# 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

Não é uma transcrição em bruto. É um resumo estruturado que te diz o que aconteceu, o que mudou, e o que ainda está pendente.

O Fluxo de Recuperação

Quando a compactação acontece:

1. StatusLine mostra o caminho do backup: Vês exatamente qual ficheiro tem o teu backup mais recente
2. Corre /clear: Começa uma sessão nova (mais limpo do que continuar com contexto compactado)
3. Carrega o backup: Lê o ficheiro markdown para restaurar o contexto
4. Continua o trabalho: O Claude agora tem contexto estruturado sobre o que estavas a fazer

Trabalhar com contexto compactado significa que o Claude tem um resumo da sessão mas perdeu os detalhes. Carregar um backup estruturado devolve-te esses detalhes.

Por Que /clear em Vez de Continuar?

Após a compactação, existem dois tipos de contexto lado a lado:

1. Resumo de compactação: Auto-gerado, com perdas, capta o essencial
2. Backup carregado: Estruturado, detalhado, capta as especificidades

Manter ambos pode criar confusão. O resumo pode contradizer detalhes no backup. Começar de novo com /clear e carregar apenas o backup dá contexto mais limpo e fiável.

Rastreamento de Estado

StatusLine e PreCompact atualizam ambos um ficheiro de estado partilhado:

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

Isto permite ao monitor StatusLine saber:

• Que sessão está a rastrear (para resetar o estado quando as sessões mudam)
• Qual era a última percentagem de contexto (para detetar cruzamentos de limiar de percentagem)
• Quantos tokens foram usados no último backup (para calcular o próximo intervalo de 10K)
• Onde o backup atual está guardado (para mostrar na statusline)

Detalhes do Parsing de Transcrição

O sistema de backup faz parse dos ficheiros de transcrição JSONL do Claude Code para extrair dados relevantes. Aqui está o que captura:

O parser descarta o ruído. Resultados de ferramentas, mensagens de sistema, e inputs de um único carácter são filtrados, ficando apenas o que realmente importa para a recuperação de sessão.

Por Que Isto Supera o Rastreamento Manual

Podias copiar contexto importante para um ficheiro à mão enquanto trabalhas. Não o farás. Estás focado na implementação, não na documentação.

O sistema baseado em tokens corre sozinho. A partir dos 50K tokens usados, tens um backup a cada 10K tokens sem pensar nisso. Zero carga cognitiva.

E os backups já estão estruturados. Não é uma colagem em bruto da conversa, mas secções organizadas que podes examinar em segundos.

Comparação: Compactação Automática vs. Backup por Limiar

A compactação automática é o padrão porque a maioria dos utilizadores nunca configura um sistema de backup. Mas se vives em sessões longas de várias horas onde a precisão importa, um backup baseado em tokens dá-te opções de recuperação muito melhores. Numa janela de contexto de 1M, acabas com dezenas de snapshots capturados ao longo da sessão em vez de perder tudo num único evento de compactação.

Pontos-Chave

1. StatusLine é o único monitor de contexto ao vivo — Outros hooks não recebem contagens de tokens
2. Triggers baseados em tokens disparam cedo — Primeiro backup a 50K usados, depois a cada 10K, independentemente do tamanho da janela
3. Limiares de percentagem são uma rede de segurança — 30%, 15%, 5% livres apanham casos extremos em janelas menores
4. A percentagem bruta inclui um buffer de 33K — Calcula o "livre até compactar" real usando contagens de tokens
5. Backups estruturados superam dumps em bruto — Faz parse das transcrições em markdown organizado
6. Arquitetura de três ficheiros — Separação limpa entre deteção, lógica de backup, e triggers
7. Fluxo de recuperação: /clear + carregar — Mais limpo do que misturar contexto compactado com backup

Recursos Relacionados

• Gestão de Buffer de Contexto — Por que existe o buffer de 33K-45K
• Guia de Hooks do Claude Code — Todos os 12 tipos de hooks explicados
• Engenharia de Contexto — Uso estratégico do contexto
• Hooks do Ciclo de Vida da Sessão — Automação de setup e limpeza