O que é Auto Compact no Claude Code?

Claude Code é o assistente de programação agentic da Anthropic que pode ler uma base de código, editar arquivos, executar comandos e integrar-se com ferramentas em fluxos de trabalho no terminal, IDE, aplicativo desktop e navegador. Como ele trabalha dentro de uma janela de contexto compartilhada, sessões longas acabam se enchendo de histórico de chat, saída de arquivos e conversas de ferramentas. O Claude Code gerencia isso automaticamente compactando o histórico da conversa quando você se aproxima do limite, e instruções iniciais podem ser perdidas se estiverem apenas no histórico do chat.

Isso importa ainda mais em 2026 porque a Anthropic continua a direcionar o Claude Code para um trabalho mais longo e mais autônomo. Em 25 de março de 2026, a Anthropic publicou “Claude Code auto mode: a safer way to skip permissions”, dizendo que os usuários aprovam 93% dos prompts de permissão e descrevendo o modo automático como um meio-termo baseado em classificador entre aprovação manual e pular permissões de forma insegura. Em 5 de fevereiro de 2026, a Anthropic também lançou o Claude Opus 4.6, destacando programação mais forte, melhor depuração e sessões agentic mais longas. Essas atualizações não são a mesma coisa que auto compact, mas mostram claramente a direção do produto: menos interrupções, sessões mais longas e continuidade mais confiável.

A CometAPI atualmente oferece acesso à Claude API a um preço menor que a API oficial, por exemplo Claude Sonnet 4.6, Claude Opus 4.6 e o Claude 5.

O que o Auto Compact realmente significa no Claude Code

Auto Compact é um mecanismo integrado de otimização de contexto no Claude Code (a ferramenta CLI/desktop da Anthropic) e no ecossistema mais amplo da Claude API. Ele intervém automaticamente quando sua conversa se aproxima do teto da janela de contexto do modelo — normalmente em torno de 200.000 tokens para modelos carro-chefe como Claude Opus 4 ou Sonnet 4. A documentação de hooks é explícita: PreCompact dispara antes de uma operação de compactação, e o matcher auto significa “auto-compact quando a janela de contexto estiver cheia.” O hook correspondente PostCompact dispara após a conclusão da compactação e recebe o compact_summary gerado.

Isso é importante porque compactação não é a mesma coisa que “memory”. Auto memory é o sistema de anotações do próprio Claude, enquanto compactação é um mecanismo de gerenciamento de sessão que comprime o estado da conversa ao vivo. A documentação de memory é clara que CLAUDE.md é persistente, auto memory é escrita pelo Claude, e a compactação é o momento em que o histórico da conversa da sessão é reduzido para que o modelo possa continuar trabalhando.

Em vez de forçar um novo chat (e perder o histórico) ou deixar o modelo “esquecer” detalhes críticos, o Auto Compact:

1. Analisa o histórico completo — identificando elementos centrais que valem a pena manter.
2. Gera um resumo conciso — de decisões, arquitetura de código, bugs resolvidos, estados de arquivos e próximos passos.
3. Substitui mensagens mais antigas — por esse resumo (um “bloco de compactação” em termos de API).
4. Retoma sem interrupções — com o contexto preservado.

Dados-chave (2026):

• Limiar de acionamento: Padrão de ~95% da capacidade (ou ~25% restante). Alguns usuários relatam um buffer interno reservando 20–45k tokens (~22,5% do contexto) para o próprio processo de compactação.
• Melhoria de desempenho: Desde o Claude Code v2.0.64, a compactação é “instantânea” em vez de levar minutos.
• Exemplo de economia de tokens (de benchmarks do Claude Agent SDK): Um fluxo de 5 tickets caiu de 204k para 82k tokens de entrada (redução de 58,6%) com dois eventos de compactação.

Auto Compact não é o mesmo que /clear (que apaga tudo) nem uma simples truncagem. Ele preserva de modo inteligente o que importa — diffs de código recentes, escolhas arquiteturais, convenções de nomenclatura — enquanto condensa loops de depuração resolvidos e tangentes exploratórias.

Por que usar Auto Compact no Claude Code?

Sessões longas de programação são a norma. A implementação de um único recurso pode abranger 50+ turnos: planejamento, depuração, refatoração, testes. Sem compactação, o uso de tokens cresce linearmente, a qualidade da resposta se degrada e os custos disparam.

Para desenvolvedores, o ganho é menos fadiga de recomeço. Em vez de copiar manualmente um resumo para uma nova sessão, você deixa o Claude compactar a sessão e continuar. Isso é especialmente útil em correção de bugs, refatorações multiarquivo, mudanças orientadas a testes e fluxos ricos em revisões, nos quais a conversa pode ficar muito longa. As sessões do Claude Code começam com uma janela de contexto nova, então a compactação é um dos principais mecanismos que tornam o trabalho de longa duração prático.

Benefícios centrais

• Comprimento de sessão ilimitado: Continue indefinidamente sem começar do zero.
• Eficiência de custo e desempenho: Reduz dramaticamente os tokens de entrada. Relatos do mundo real mostram economias de 50–60% em fluxos de trabalho multifásicos.
• Melhor foco e estabilidade: Evita “sobrecarga de contexto”, quando o modelo alucina ou esquece restrições anteriores.
• Preserva conhecimento institucional: Decisões chave permanecem no contexto mesmo após centenas de mensagens.
• Sem atrito para fluxos agentic: Crítico ao usar ferramentas, servidores MCP ou setups multiagente no Claude Code.

Quando você deve confiar no auto compact?

Use o auto compact quando a tarefa for naturalmente de longa duração: refatorações multiarquivo, sessões de depuração que alternam entre logs e código-fonte, implementação de recursos com verificação repetida, ou pesquisa que exige muitas chamadas de ferramenta. A documentação da Anthropic aponta explicitamente para sessões longas em que a janela de contexto se enche de conversa irrelevante, conteúdo de arquivos e comandos, e diz que a compactação automática preserva código e decisões essenciais enquanto libera espaço.

É menos adequado quando a tarefa é curta, isolada, ou requer instruções precisas e permanentemente retidas. Essas instruções do início da conversa podem se perder após a compactação, razão pela qual regras de projeto pertencem ao CLAUDE.md, não a um prompt descartável que pode ser comprimido depois.

Quando usar (ou ativar):

• Ativado por padrão para a maioria dos usuários — ideal para programação diária, grandes refatorações ou projetos exploratórios.
• Tarefas de longa duração — processamento de filas, pipelines de dados ou bases de código multiarquivo.
• Ambientes de equipe/enterprise — onde a continuidade do contexto entre sessões importa.
• Projetos de alto risco — em que perder uma única decisão arquitetural pode custar horas.

Quando considerar desativar (via /config):

• Você quer cada token do contexto para controle ultrapréciso.
• Você prefere gerenciamento totalmente manual (power users que salvam/restauram planos via arquivos).

Últimas notícias (2025–2026): Em março de 2025, a Anthropic melhorou a lógica de preservação do Auto Compact, tornando os resumos mais inteligentes ao reter “informações importantes enquanto reduz o uso de tokens”. No fim de 2025, o acionamento foi refinado (às vezes mais cedo, em 64–75% de uso, para evitar falhas de compactação). No início de 2026, houve bugs temporários nas interfaces web/desktop (marcados como corrigidos em meados de janeiro, mas com relatos residuais), enquanto o CLI permaneceu estável. A versão 2.0.64 (fev. 2026) tornou a compactação instantânea, um grande avanço para a experiência do desenvolvedor.

Como usar o Auto Compact no Claude Code: guia passo a passo

O Claude Code foi projetado para que cada sessão comece com uma janela de contexto nova. Isso é útil porque cada nova tarefa começa de forma limpa, e também facilita perceber quando uma sessão está ficando ruidosa. Recomenda-se /clear entre tarefas não relacionadas para que contexto obsoleto não continue consumindo espaço.

Etapa 1: Verifique o status atual do contexto

Use /context para visualizar a carga de contexto atual. A lista de comandos integrada do Claude Code diz que /context mostra uma grade colorida e destaca inchaço de memória, sugestões de otimização e avisos de capacidade. Isso torna o caminho mais rápido para saber se você está se aproximando do ponto em que a compactação automática provavelmente será acionada.

Na sua sessão do Claude Code, digite:

/context

Isso mostra “Context left until auto-compact: XX%” — sua barra de progresso em tempo real.

Etapa 2: Configure o Auto-Compact (opcional)

Quando a janela de contexto fica cheia, o Claude Code compacta a conversa automaticamente. A referência de hooks rotula esse evento como auto, e ele dispara quando a janela de contexto está cheia. Na prática, você não “liga” o auto compact, e sim deixa o Claude Code fazer isso quando necessário.

/config

Navegue até “Auto-compact enabled” e alterne entre true/false. O padrão é habilitado. Você também pode ajustar configurações relacionadas, como o uso de servidores MCP, para liberar tokens de forma proativa.

Etapa 3: Deixe o Auto-Compact rodar automaticamente

Quando você chega a ~95%:

• O Claude exibe “Compacting our conversation so we can keep chatting…” (ou similar).
• Ele roda em segundo plano e retoma.
• Você verá o novo resumo no topo do contexto.

Dica: Não espere chegar a 0%. Faça a compactação manual mais cedo para obter melhores resultados (veja as melhores práticas abaixo).

Etapa 4: Use hooks se quiser automatizar o que acontece ao redor da compactação

O Claude Code expõe os hooks PreCompact e PostCompact. A referência de hooks mostra que PreCompact pode detectar se a compactação é manual ou automática, e PostCompact recebe o compact_summary gerado. Isso torna os hooks uma ótima opção para logging, trilhas de auditoria, notas pós-compactação ou automação externa.

Um padrão simples de hook é assim:

{  "hooks": {    "PostCompact": [      {        "matcher": "auto",        "hooks": [          {            "type": "command",            "command": "./scripts/save-compact-summary.sh"          }        ]      }    ]  }}

E o script shell correspondente pode ler o JSON da entrada padrão, porque hooks de comando do Claude Code recebem JSON dessa forma:

#!/usr/bin/env bashset -euo pipefailjq -r '.compact_summary // empty' \  | sed 's/^/[compact] /' \  >> .claude/compact-log.txt

A documentação confirma que hooks de comando recebem JSON via stdin e que PostCompact inclui compact_summary, então esse padrão está alinhado com o modelo atual de hooks.

Etapa 5: Compactação manual com precisão (recomendado)

Use /compact quando quiser que o assistente comprima o thread agora. Você pode incluir instruções que moldem o resumo que deseja preservar. A página de comandos integrados da Anthropic lista /compact [instructions] como “Compact conversation with optional focus instructions,”

/compact keep the auth flow decisions, the current test plan, and the open TODOs

Esse padrão é útil logo antes de uma passagem de bastão, antes de uma troca de branch, ou antes de você pedir ao Claude para iniciar uma nova fase de trabalho.

Exemplos de uso real:

• Após depuração: /compact keep the solution we found, remove debugging steps
• Marco do projeto: /compact focus on the new feature requirements

Compactação em nível de API (Avançado – Python SDK e Messages API)

Para agentes ou scripts personalizados, use as ferramentas oficiais de compactação.

Exemplo do Claude Agent Python SDK (automático para fluxos que usam ferramentas):

from anthropic import Anthropic

client = Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=your_tools,
    messages=messages,
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,  # or lower for aggressive compaction
        "model": "claude-haiku-4-5",        # cheaper summarizer
        "summary_prompt": """Create a focused summary preserving:
1. COMPLETED TASKS and key outcomes
2. CURRENT STATE and open items
3. NEXT STEPS
Wrap in <summary></summary> tags."""
    }
)

Detecte eventos de compactação:

if curr_msg_count < prev_msg_count:
    print(f"Compaction occurred! Messages reduced from {prev_msg_count} to {curr_msg_count}")
```<grok-card data-id="f4afb5" data-type="citation_card" data-plain-type="render_inline_citation" ></grok-card>

Messages API completa (beta, 2026) – requer header:
```bash
curl https://api.anthropic.com/v1/messages \
  --header "anthropic-beta: compact-2026-01-12" \
  --data '{
    "model": "claude-opus-4-6",
    "messages": [...],
    "context_management": {
      "edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 150000},
        "pause_after_compaction": true
      }]
    }
  }'

A API retorna um bloco de compactação que você deve repassar nas chamadas futuras. Instruções personalizadas e pausar dão controle total sobre o orçamento (por exemplo, impor um teto total de 3M tokens entre sessões).

Se você estiver usando a Claude API da CometAPI, altere o cabeçalho da mensagem para "https://api.cometapi.com/v1/messages\\".

Auto-Compact vs Compactação manual vs Clear: tabela comparativa

Boas práticas para o Auto Compact do Claude Code (dicas de profissionais)

Compacte de forma proativa

A terceira regra é usar a compactação como um reset, não como muleta. Se o thread estiver cheio de becos sem saída, peça ao Claude para compactar com uma instrução clara sobre o que importa: objetivo atual, abordagem escolhida, testes com falha e questões não resolvidas. Na prática, isso torna o resumo muito mais útil do que deixar o sistema compactar às cegas e torcer pelo melhor.

Mantenha suas instruções duráveis curtas.

A Anthropic diz que arquivos acima de 200 linhas podem reduzir a aderência, então grandes blocos de políticas geralmente são piores do que regras concisas e bem delimitadas. Use .claude/rules/ para comportamento específico por tipo de arquivo ou caminho, e use imports @path quando precisar de detalhes de suporte mais ricos sem inchar o arquivo de instruções principal.
Tokens grátis primeiro — Desative servidores MCP não utilizados com /mcp ou @server-name disable antes de compactar.

Combine com CLAUDE.md

Trate CLAUDE.md como a fonte da verdade para qualquer coisa que você quer que sobreviva a uma sessão longa. CLAUDE.md é relido após /compact, o que o torna o lugar certo para comandos de build, convenções de codificação e as regras persistentes que você nunca quer perder. Auto memory também é útil, mas é um sistema diferente com um propósito diferente.

Outras dicas

Monitore via /context — Mantenha o uso abaixo de 70–80% quando possível.

Para usuários de API — Defina limiares mais baixos (por exemplo, 50k–100k) e use modelos de sumarização mais baratos como Haiku.

Desative apenas quando necessário — A maioria dos desenvolvedores agora recomenda manter o Auto-Compact ativado após as melhorias de 2025.

Teste a compactação — Primeiro em sessões não críticas para ver como o seu fluxo específico é resumido.

Impacto no mundo real: Desenvolvedores relatam sessões produtivas 2–3x mais longas e menos momentos de “o Claude esqueceu o que estávamos fazendo”.

Problemas comuns e solução de problemas (edição 2026)

• Auto-compact não aciona: Verifique web/desktop vs CLI; alguns bugs de jan. 2026 foram corrigidos, mas confirme a versão.
• Contexto perdido após compactação: Use /compact manual com instruções explícitas na próxima vez.
• Loops infinitos ou 102% de uso: Raro; reinicie a sessão ou use /clear como último recurso.
• Compactação lenta: Problema pré-v2.0.64 — atualize o Claude Code.
• Erros com blocos de compactação na API: Sempre anexe o conteúdo completo do bloco de compactação nas chamadas subsequentes.

Conclusão

Auto compact é um dos mecanismos ocultos mais importantes no Claude Code porque mantém sessões longas de programação utilizáveis sem forçar você a reiniciar sempre que a janela de contexto enche. A regra prática é simples: deixe o auto compact lidar com o excesso, use /compact quando quiser controle, guarde orientações duráveis em CLAUDE.md, e use /clear ou /rewind quando a estrutura da sessão mudar. Essa combinação oferece o melhor equilíbrio entre continuidade, controle e velocidade em fluxos de trabalho longos com o Claude Code.

Auto Compact no Claude Code representa um salto no desenvolvimento assistido por IA na prática. Ao gerenciar inteligentemente a janela de contexto de 200k tokens, elimina o maior ponto de fricção em programação de longa duração: ficar sem “memória”. Com desempenho instantâneo (2026), opções ricas de configuração e poderosas extensões de API, agora é um recurso maduro e testado em batalha usado diariamente por milhares de desenvolvedores.

Passos de ação hoje:

1. Abra o Claude Code e execute /config — confirme que o Auto-Compact está ativado.
2. Tente um /compact manual com instruções no seu projeto atual.
3. Explore o Python SDK ou a Messages API para agentes automatizados na CometAPI.