Idle compaction no Claude Code: o que faz e como desativar

Você deixa uma sessão longa do Claude Code parada por uma hora, volta e encontra um aviso que nunca tinha visto: “Compacted while idle, before the prompt cache expired.” É a idle compaction, a compactação por inatividade, um recurso que a Anthropic lançou em outubro de 2026 e ampliou em quase toda versão desde então. Ela vem ligada por padrão, por isso muita gente esbarra nela antes de ler a respeito.

Este artigo mostra o que ela faz, quando roda, como ajustar ou desativar e o que muda quando você roda vários agentes lado a lado.

O que mudou e quando

As datas são as de publicação de cada versão no npm; as descrições vêm do changelog do Claude Code.

Se você usa a idle compaction, atualize para a 2.1.318 ou posterior por causa dessa correção.

Por que o Claude Code compacta enquanto você está fora

Cada mensagem reenvia a conversa inteira. O que mantém isso barato é o cache de prompts: a API reaproveita o que já processou. Só que o cache expira depois de um tempo sem atividade. Se você volta depois disso, a próxima mensagem reprocessa todo o histórico como entrada sem cache, o que é lento e caro numa conversa com mais de 200K tokens.

Compactar sai mais barato com o cache ainda quente, porque o pedido de resumo lê o histórico do cache. A idle compaction aproveita essa janela: pouco antes de o cache de uma hora expirar, o Claude Code escreve o resumo. Quando você volta, a próxima mensagem parte desse resumo curto em vez de reconstruir a conversa toda. A documentação de cache de prompts detalha essa troca.

Quando a idle compaction roda

Segundo a referência de configurações, a conversa só entra se atender a tudo isto:

• Sessão: uma sessão interativa no terminal, o painel de chat da extensão do VS Code ou a aba Code do app desktop quando a sessão roda na sua máquina ou via SSH.
• Compactação automática (autoCompactEnabled) ligada.
• Cache de prompts: a conversa está no TTL de uma hora.
• Tamanho: o contexto chegou ao limite, 200.000 tokens por padrão.
• Inatividade: passou cerca de uma hora desde a última requisição, e o computador continua acordado até lá.

A condição do cache pesa mais do que parece. Por padrão, o Claude Code pede o TTL de uma hora só para a conversa principal numa assinatura do Claude, enquanto você está dentro do uso do plano. Com chave de API ou provedor de nuvem o padrão é cinco minutos, então a idle compaction não roda a menos que você defina promptCacheTtl como 1h. Se passar do limite do plano e usar créditos de uso, a conversa principal também cai para cinco minutos.

Como desativar

Escolha uma opção:

• Arquivo de configurações: adicione "idleCompaction": false ao ~/.claude/settings.json, ou ao arquivo de configurações de um projeto para desligar só naquele repositório.
• /config: mude a linha Idle compaction. A escolha vai para as suas configurações de usuário e vale na hora (v2.1.302 ou posterior).
• Variável de ambiente: DISABLE_AUTO_COMPACT=1 desliga a idle compaction junto com a compactação automática. O /compact manual continua funcionando.

{
  "idleCompaction": false
}

Se o /config não mostra a linha, outra fonte de configurações provavelmente define a chave: configurações gerenciadas, um arquivo do projeto ou --settings. Altere lá.

Como ajustar o limite

CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS define o tamanho mínimo da conversa para a idle compaction valer. Valores abaixo de 100.000 sobem para 100.000.

Tem um detalhe que vale saber. Num modelo com janela de 200K, a compactação automática roda antes de a conversa chegar a 200.000 tokens; com o limite padrão, a idle compaction afeta sobretudo sessões com 1M de contexto. Para incluir conversas de 200K, baixe o valor:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

O que fica depois da compactação

A compactação troca o histórico por um resumo, mas nem tudo se perde. O CLAUDE.md da raiz do projeto e a memória automática são recarregados do disco, o plano do modo plano volta e o Claude Code relê até cinco dos arquivos que leu ou editou, começando pelos modificados mais recentemente. Comandos e subagentes em segundo plano continuam rodando. O que vai embora é o detalhe: saídas exatas das ferramentas, raciocínios longos, a conversa que levou a uma decisão. Nosso guia da janela de contexto do Claude Code aprofunda isso.

A regra prática é simples. Se a tarefa tinha acabado, a idle compaction economiza dinheiro e você mal vai perceber. Se parou no meio de algo delicado e quer que o Claude lembre cada passo, desligue para aquele projeto ou volte antes de uma hora.

O que muda com vários agentes

A idle compaction foi pensada para uma pessoa saindo de uma sessão. Com vários agentes em paralelo, o cenário muda:

• Cada sessão é avaliada sozinha. Sessões em pastas diferentes montam prefixos de cache diferentes, então agentes em worktrees git separadas nunca dividem cache. Cada um que passar do limite e ficar parado por cerca de uma hora é compactado por conta própria.
• Agente esperando é agente parado. Quem terminou o turno e aguarda sua revisão ou sua resposta a uma pergunta conta como inativo. Quando você chega ao quarto painel depois do almoço, ele já pode estar trabalhando com um resumo. Para “ok, pode subir” tudo bem; para “volte à abordagem que você descartou antes”, nem tanto.
• Subagentes e colegas de equipe não são o alvo. Por padrão eles ficam no grupo de cache de cinco minutos. A idle compaction trata das suas conversas principais.
• Execuções headless ficam de fora. Execuções com -p e sessões do Agent SDK estão fora das condições, então pipelines noturnos baseados nelas se comportam como antes. Para trabalho interativo à noite, veja como rodar o Claude Code durante a noite.
• O notebook precisa ficar acordado. Se a máquina dormir, a hora passa sem compactação e você volta a pagar uma releitura sem cache.

Uma configuração prática: deixe a idle compaction ligada por padrão, desligue em um ou dois repositórios onde um agente costuma esperar você no meio da tarefa e tente responder dentro de uma hora aos agentes que fazem perguntas.

Onde o AgentVera entra

Nós fazemos o AgentVera, um app desktop para macOS, Windows e Linux que roda Claude Code, Codex e outros 16 agentes de programação lado a lado, cada um num terminal real com a sua instalação e a sua conta. Algumas partes conversam com a idle compaction:

• Economia de tokens: a compactação automática vem ligada para cada agente com limite de 150K tokens, usando o comando de compactação de cada CLI, e cada painel mostra o tamanho do contexto ao vivo. Uma mensagem para um agente parado há mais de uma hora compacta primeiro uma conversa grande, o que cobre também agentes sem idle compaction própria.
• Notificações: você é avisado quando um agente termina ou precisa de algo, então menos agentes ficam esperando além da hora.
• Orçamentos de tokens e limites de uso: um teto por agente e, na barra de status, o uso de 5 horas e semanal de cada conta Claude e Codex.

O plano gratuito inclui até 18 agentes, MCP, Git, Docker, SSH e revisão de código. Para uma comparação mais ampla, veja os melhores apps para Claude Code e Codex em paralelo.

Resumindo

A idle compaction é um padrão pequeno com propósito claro: resumir uma conversa longa enquanto o cache ainda está quente, para que a sua volta não custe uma releitura completa sem cache. Ela precisa de uma sessão interativa, do cache de uma hora e de um contexto grande o bastante. Dá para baixar o limite com CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS ou desligar com "idleCompaction": false ou pelo /config. Quando vários agentes esperam por você ao mesmo tempo, decida por projeto se um resumo basta e responda primeiro aos que precisam do contexto completo.

Fontes: changelog do Claude Code, idleCompaction na referência de configurações, How Claude Code uses prompt caching e Explore the context window.