Habilidade de Compactação Estratégica

Sugere a /compact manual em pontos estratégicos do seu fluxo de trabalho, em vez de depender de compactação automática arbitrária.

Quando Ativar

• Executando sessões longas que se aproximam dos limites de contexto (mais de 200 mil tokens)
• Trabalhando em tarefas multifases (pesquisa → planejamento → implementação → teste)
• Alternando entre tarefas não relacionadas dentro da mesma sessão
• Após concluir um marco importante e iniciar um novo trabalho
• Quando as respostas ficam lentas ou menos coerentes (pressão de contexto)

Por que Compactação Estratégica?

A compactação automática é acionada em pontos arbitrários:

• Frequentemente no meio da tarefa, perdendo contexto importante
• Sem consciência dos limites lógicos da tarefa
• Pode interromper operações complexas de várias etapas

Compactação estratégica em limites lógicos:

• Após a exploração, antes da execução — Compacta o contexto de pesquisa, mantém o plano de implementação
• Após concluir um marco — Novo começo para a próxima fase
• Antes de grandes mudanças de contexto — Limpa o contexto de exploração antes de uma tarefa diferente

Como Funciona

O script suggest-compact.js é executado em PreToolUse (Editar/Escrever) e combina dois sinais:

1. Tamanho do contexto (primário) — Lê o último registro usage da transcrição da sessão (transcript_path no payload do hook) e soma input_tokens + cache_read_input_tokens + cache_creation_input_tokens (o tamanho real do contexto da vez). Sugere /compact em um limite escalonado pela janela — 160 mil tokens em uma janela de 200 mil, 250 mil em uma janela de 1 milhão (detectado a partir de um marcador de modelo [1m], ou inferido quando os tokens observados já excedem 200 mil) — e reapresenta após cada 60 mil tokens adicionais de crescimento de contexto.
2. Contagem de chamadas de ferramenta (secundário) — Conta as invocações de ferramentas na sessão; sugere em um limite configurável (padrão: 50 chamadas), depois a cada 25 chamadas.

A contagem de ferramentas sozinha é um indicador fraco de pressão na janela: algumas leituras de arquivos grandes ou respostas de MCP podem preencher a janela em poucas chamadas, enquanto muitas chamadas pequenas podem ultrapassar 50 com uma janela quase vazia. O sinal de tamanho de contexto é acionado quando realmente importa.

Configuração do Hook

Instalado como um plugin? Nenhuma configuração é necessária. O hooks/hooks.json do plugin já registra suggest-compact.js (ID do hook pre:edit-write:suggest-compact, ativo nos perfis de hook standard e strict). Não copie o bloco abaixo para ~/.claude/settings.json — ~/.claude/scripts/ não existe em instalações de plugin, e duplicar um hook de plugin causa execução dupla.

Se instalado manualmente (./install.sh), adicione ao seu ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      }
    ]
  }
}

Configuração

Variáveis de ambiente:

• COMPACT_THRESHOLD — Chamadas de ferramenta antes da primeira sugestão (padrão: 50)
• COMPACT_CONTEXT_THRESHOLD — Tokens de contexto antes da sugestão de tamanho de contexto (padrão: 160000 em uma janela de 200 mil, 250000 em uma janela de 1 milhão; 0 desabilita o sinal de contexto)
• COMPACT_CONTEXT_INTERVAL — Tokens de contexto adicionais antes que a sugestão se repita (padrão: 60000)
• COMPACT_STATE_TTL_DAYS — Dias antes que arquivos de estado por sessão obsoletos no diretório temporário sejam limpos (padrão: 14)
• ECC_CONTEXT_WINDOW_TOKENS — Tamanho explícito da janela de contexto, em tokens, substituindo a detecção automática. Defina isso para modelos de janela grande cujo ID reportado não tenha um marcador [1m] (por exemplo, Opus 4.x de 400 mil, ou uma nova família de modelos de janela de 1 milhão) para que o limite seja escalonado para a janela real em vez de usar o padrão de 200 mil e superestimar o uso de contexto.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Substituição nativa do tamanho da janela do Claude Code, em tokens; honrado como fallback quando ECC_CONTEXT_WINDOW_TOKENS não está definido.

A janela de contexto é de outra forma detectada automaticamente a partir de um marcador de modelo [1m] ou inferida quando os tokens observados já excedem 200 mil. Em um modelo de janela grande que não carrega nenhum desses sinais, defina uma das substituições acima para que a sugestão /compact seja acionada no ponto certo.

Guia de Decisão de Compactação

Use esta tabela para decidir quando compactar:

…