O Claude Code compacta sem parar: quebre o loop e salve seu trabalho
Por que o Claude Code compacta sua conversa sem parar — como o limite do autocompact, a compactação por inatividade da 2.1.299 e as incompatibilidades de gateway interagem — mais a recuperação com resume e checkpoints, o interruptor Idle compaction do /config, CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, e as correções 2.1.301 e 2.1.309, em gravações reais de tela.
A compactação constante num relance
- A compactação é a sumarização automática que libera espaço de contexto — o Claude Code compacta quando a conversa se aproxima da janela do modelo (200K no Sonnet 4.6/Opus 4.6 sem contexto estendido, cerca de 967K por padrão em modelos de janela 1M).
- "Compacta sem parar" tem três causas comuns: uma janela realmente cheia, a compactação por inatividade adicionada na 2.1.299 (uma conversa com 200K+ tokens deixada ociosa por cerca de 54 minutos é compactada antes de o cache de prompts de uma hora expirar), ou uma incompatibilidade de gateway/nome de modelo corrigida na 2.1.301.
- Nada do que já foi enviado se perde: o resumo guarda o código e as decisões principais, e o resume mais os checkpoints trazem o resto de volta — a linha de compactação numa sessão retomada diz onde as mensagens anteriores estão salvas (2.1.301).
- Ajuste em vez de brigar: /autocompact ou a configuração autoCompactWindow muda a janela, CLAUDE_CODE_AUTO_COMPACT_WINDOW ganha de tudo, e "idleCompaction": false (ou a linha Idle compaction do /config) desliga a compactação por inatividade.
- Dois loops específicos de versão já receberam correção: a compactação repetida atrás de um gateway LLM que nomeia outro modelo (2.1.301) e a compactação repetida após ler arquivos sob um CLAUDE.md aninhado muito grande (2.1.309) — atualize antes de ajustar.
Claude Code: CLAUDE.md, Memory & Session Management
CanalDavid Mahler22:39
Stop Losing Work When You Compact Claude Code
CanalThe Art of Vibe Coding7:28
Model configuration — Claude Code documentation
Docscode.claude.com
Os quadros vêm da apresentação de gerenciamento de sessões do David Mahler — diagramas de contexto animados, a grade de uso do /context com sua linha Autocompact buffer e o diagrama do resumo de compactação. Os slides de limite e handoff vêm do explainer animado de The Art of Vibe Coding. Os fatos foram cruzados com o CHANGELOG do Claude Code (2.1.299, 2.1.301, 2.1.302, 2.1.309) e a documentação oficial de model-config. Um vídeo talking-head e um frame de spinner já usado pelo nosso guia de redução de tokens foram descartados como fontes de quadros.
Os quadros do vídeo permanecem propriedade de seus criadores e são incorporados aqui como documentação passo a passo, com atribuição e links diretos.
Impeça o Claude Code de compactar repetidamente
Passo 1 — Entenda o que a compactação está fazendo
- 1
Saiba o que a compactação realmente é
A compactação é um processo automático que libera espaço de contexto resumindo as mensagens antigas enquanto preserva o código e as decisões principais. O Claude Code compacta quando a conversa se aproxima da janela do modelo — na fronteira dos 200K no Sonnet 4.6 e no Opus 4.6 sem contexto estendido, ou por padrão perto de 967K tokens em modelos com janela nativa de 1M. Ver "Compacting conversation…" uma vez numa sessão longa é o sistema funcionando como projetado, não um erro.
O slide de definição da compactação: um processo automático que resume as mensagens antigas preservando código e decisões principais.Assistir em 10:40 - 2
Veja o que está enchendo sua janela
Rode /context antes de mudar qualquer coisa. Ele imprime o modelo, a contagem de tokens contra a janela e uma quebra por categoria — system prompt, system tools, ferramentas MCP, arquivos de memória, Messages, espaço livre e o Autocompact buffer reservado. Na sessão gravada, Messages sozinho ocupava 129,9k dos 149,1k tokens (65%), com 33k (16,5%) reservados para o buffer — por isso a compactação chegou: a conversa em si, e não um defeito, estava consumindo a janela.
A grade de uso do /context a 75%: Messages com 129,9k tokens e o Autocompact buffer de 33k (16,5%) destacados no rodapé.Assistir em 10:20 - 3
Entenda como é um loop de contexto inchado
Quando saídas longas, leituras de arquivos grandes e resultados de ferramentas enormes se acumulam, o bloco de Messages empurra todo o resto — descrições de skills, ferramentas MCP e instruções memorizadas ficam espremidas antes que você perceba. É o estado em que cada troca a mais dispara outro ciclo de compactação. Se o /context mostra Messages dominando enquanto as linhas de instruções úteis encolhem, a correção é enxugar o que você alimenta à sessão, não só reajustar limites.
O diagrama do contexto inchado: um bloco de Messages tão grande que esmaga descrições de skills, ferramentas MCP e instruções memorizadas.Assistir em 11:26
Passo 2 — Recupere seu trabalho e reinicie a janela
- 4
Recupere: o resumo guarda as decisões, o resume guarda o histórico
Nada do que já foi enviado desaparece. A compactação transforma o bloco de Messages em um Conversation Summary enquanto as linhas CLAUDE.md e Auto Memory ficam no lugar, e os checkpoints do Claude Code mais claude --resume / /resume trazem o resto de volta. Desde a 2.1.301, a linha de compactação numa sessão retomada também diz onde as mensagens anteriores estão salvas, em vez de oferecer um histórico que não consegue carregar. Se uma compactação interrompeu um trabalho importante, retome a sessão e leia o resumo antes de reexplicar qualquer coisa.
O diagrama antes/depois da compactação: as Messages viram um Conversation Summary enquanto as linhas CLAUDE.md e Auto Memory, emolduradas em vermelho, são preservadas.Assistir em 7:56 - 5
Antes de uma compactação grande, escreva o trabalho no disco
Para sessões em que você não pode perder contexto, construa a ponte você mesmo: peça ao Claude Code um documento de handoff (ou use um skill de handoff como o /handoff-doc) que lê a sessão inteira — cada decisão, cada arquivo tocado, cada ponta solta — e destila tudo num HANDOFF.md estruturado no disco. Depois da compactação ou numa sessão nova, apontar o próximo prompt para esse arquivo recupera o rumo mais rápido do que o resumo sozinho.
O fluxo de handoff: o skill /handoff-doc relê a sessão inteira — cada decisão, arquivo tocado e ponta solta — num HANDOFF.md estruturado.Assistir em 1:00 - 6
Ajuste a janela do autocompact em vez de temê-la
O ponto de disparo é ajustável. /autocompact <valor> define para o modelo atual e salva nas configurações do usuário; a chave autoCompactWindow (por exemplo "autoCompactWindow": 200000 em ~/.claude/settings.json) vale para todos os modelos; --autocompact vale por um único lançamento; e a variável de ambiente CLAUDE_CODE_AUTO_COMPACT_WINDOW ganha de tudo, aceitando de 100.000 a 1.000.000 de tokens (a partir da 2.1.304 você pode escrever 200k ou 1M). Os valores são limitados à janela real do modelo, e /autocompact auto volta ao padrão ajustado.
A conta do limite: 20% de uma sessão Opus de 1M tokens é aproximadamente 200.000 tokens — cerca de uma hora de trabalho real.Assistir em 2:12
Passo 3 — Compactação por inatividade: o comportamento da 2.1.299
- 7
Reconheça a compactação por inatividade (Claude Code 2.1.299)
Desde a 2.1.299 existe um segundo gatilho que não tem nada a ver com janela cheia: a compactação por inatividade. Uma conversa com 200K+ tokens que você deixa ociosa por cerca de 54 minutos é compactada antes de o cache de prompts de uma hora expirar, para que sua próxima mensagem não reprocesse a transcrição inteira pelo preço cheio. Se o Claude Code compacta enquanto você estava fora — o aviso aparece na transcrição quando você volta — é a feature, não um loop.
- 8
Desligue a compactação por inatividade ou baixe seu piso
Dois interruptores, ambos documentados no changelog 2.1.299: defina "idleCompaction": false no settings.json para desligar de vez, ou defina CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS para mudar o mínimo de 200K tokens abaixo do qual a compactação por inatividade nunca dispara (ambos exigem v2.1.290 ou mais novo). A partir da 2.1.302 também existe uma linha Idle compaction no /config, e os avisos mostrados depois de uma compactação por inatividade agora dizem como desligá-la. A configuração exige 200K+ tokens ociosos por cerca de 54 minutos — sessões curtas nunca são tocadas.
- 9
Decida se você quer mesmo desligar
A compactação por inatividade troca um custo por outro. Ligada, você perde a transcrição exata ao voltar depois de uma hora; desligada, sua próxima mensagem reprocessa a transcrição inteira de 200K+ tokens com cache expirado — mais lento e cobrado na tarifa de cache miss. Se suas sessões são longas mas você sai com frequência, baixar o CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS costuma ser melhor que desligar: a compactação acontece nos seus termos, contra um bloco menor.
Passo 4 — Loops específicos de versão e prevenção
- 10
Atualize antes de ajustar: o loop de gateway da 2.1.301
Se a compactação realmente se repete numa janela cheia, confira sua versão primeiro. A 2.1.301 corrigiu conversas "sendo compactadas repetidamente, num modelo que você não escolheu, atrás de um gateway LLM cujas respostas nomeiam um modelo diferente do solicitado" — as respostas do gateway nomeavam o modelo X enquanto você pedia o modelo Y, e cada turno recompactava. O mesmo release corrigiu a linha de compactação de sessão retomada que oferecia ctrl+o para histórico não carregado. Usuários de gateway na 2.1.300 ou anterior: atualize antes de mexer em qualquer configuração.
- 11
Enxugue os arquivos CLAUDE.md — o loop de arquivo aninhado da 2.1.309
Outro loop documentado: sessões seguiam compactando depois de ler arquivos sob um CLAUDE.md aninhado muito grande — a 2.1.309 corrigiu, e um CLAUDE.md aninhado acima do limite de tamanho agora carrega só o começo. Audite seus arquivos de memória mesmo assim: o CLAUDE.md de nível de usuário carrega em todos os projetos, arquivos de escopo de projeto carregam no diretório de trabalho, e arquivos de subdiretório sob demanda carregam quando o Claude os visita. Tire dos arquivos sempre carregados tudo o que não é instrução universal.
O diagrama de escopos de memória: CLAUDE.md de nível de usuário para todos os projetos, arquivos de escopo de projeto no diretório de trabalho e arquivos sob demanda que o Claude carrega ao visitar.Assistir em 4:44 - 12
Previna o próximo loop
Três hábitos fazem da compactação um não-evento. Mantenha os arquivos CLAUDE.md enxutos para as instruções sobreviverem a cada compactação. Deixe a compactação acontecer no limite em vez de adiá-la — a qualidade da resposta piora conforme a janela enche, e o resumo escrito com 20% restante é melhor que o escrito a 95%. E descarregue em arquivos o estado que importa (documentos de handoff, planos, checklists) para cada reinício partir de algo melhor que um resumo.
O slide do porquê não adiar: a qualidade da resposta degrada quando o limite de compactação é cruzado e a compactação é postergada.Assistir em 2:20
Compactação por inatividade, a 2.1.299 em detalhe
A compactação por inatividade é a razão mais recente de uma sessão "compactar sem parar" — e a mais fácil de confundir com bug. O changelog 2.1.299 a introduziu no terminal com justificativa explícita, e a 2.1.302 mais a 2.1.301 refinaram os controles em volta. Os fatos, verificados no changelog:
- 1O gatilho: uma conversa com 200K+ tokens deixada ociosa por cerca de 54 minutos — cronometrado para a compactação cair antes de o cache de prompts de uma hora expirar.
- 2A justificativa: "para que sua próxima mensagem não reprocesse tudo" — uma transcrição de 200K+ tokens sem compactar depois da expiração do cache é reprocessada token por token na tarifa de cache miss.
- 3O interruptor: "idleCompaction": false no settings.json — ou, desde a 2.1.302, a linha Idle compaction do /config.
- 4O ajuste: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS muda o mínimo de 200K tokens; conversas abaixo dele nunca são compactadas por inatividade.
- 5O piso de versão: a variável de ambiente e a configuração exigem Claude Code v2.1.290 ou mais novo — em builds antigos a feature simplesmente não existe, o que parece uma mudança repentina de comportamento depois de uma atualização.
- 6As salvaguardas: sessões curtas nunca são tocadas, o aviso aparece na transcrição quando você volta, e desde a 2.1.302 o próprio aviso diz como desligar a feature.
Se você compartilha sessões em equipe, lembre que a configuração é por máquina: "idleCompaction": false nas suas configurações de usuário não acompanha o repo, então a sessão ociosa de um colega pode compactar mesmo que a sua nunca compacte. Para sessões longas compartilhadas, a combinação previsível é um CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS baixado mais um documento de handoff escrito antes de qualquer um se ausentar.