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

URL: https://agentvera.dev/pt/blog/claude-code-idle-compaction/ · Publicado: 2026-11-06

O Claude Code agora resume conversas longas que ficam paradas por cerca de uma hora. O que mudou da v2.1.299 à v2.1.318, como desativar e o efeito em agentes paralelos.

**Resumo:**

- Desde a v2.1.299 (14 de outubro de 2026), o Claude Code resume uma conversa com mais de 200K tokens parada por cerca de uma hora, pouco antes de o cache de uma hora expirar.
- Para desativar, use "idleCompaction": false no settings.json ou a linha Idle compaction do /config (v2.1.302+). DISABLE_AUTO_COMPACT=1 desliga junto com a compactação automática.
- Cada sessão em paralelo tem o próprio cache e é compactada separadamente: um agente que espera sua resposta há uma hora pode voltar trabalhando a partir de um resumo.

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](https://code.claude.com/docs/en/changelog "Claude Code changelog").

| Versão | Data | Mudança |
| --- | --- | --- |
| 2.1.299 | 14 de outubro de 2026 | Idle compaction no terminal: uma conversa com mais de 200K tokens parada por cerca de 54 minutos é compactada antes de o cache de uma hora expirar. Chegam `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` e a configuração `idleCompaction`. |
| 2.1.302 | 16 de outubro de 2026 | Uma linha **Idle compaction** no `/config` para desligar ou religar. O aviso depois de uma compactação passa a dizer como desativar. |
| 2.1.314 | 30 de outubro de 2026 | Idle compaction no VS Code e na aba Code do app desktop. Também roda para assinantes com telemetria desligada e no Bedrock, Vertex, Foundry e gateways de LLM quando o cache de uma hora está ativo. |
| 2.1.318 | 3 de novembro de 2026 | Corrigido: a idle compaction podia trocar a conversa por uma resposta que não era um resumo. |

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](https://code.claude.com/docs/en/prompt-caching "How Claude Code uses prompt caching") detalha essa troca.

## Quando a idle compaction roda

Segundo a [referência de configurações](https://code.claude.com/docs/en/settings-reference#idlecompaction "idleCompaction"), 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.

```json
{
  "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:

```json
{
  "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](/pt/blog/claude-code-context-window/ "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](/pt/blog/run-claude-code-overnight/ "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](/pt/features/token-savings/ "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](/pt/blog/best-tools-parallel-ai-coding-agents/ "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](https://code.claude.com/docs/en/changelog "Claude Code changelog"), [idleCompaction na referência de configurações](https://code.claude.com/docs/en/settings-reference#idlecompaction "idleCompaction"), [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching "Prompt caching") e [Explore the context window](https://code.claude.com/docs/en/context-window "Context window").

## Perguntas frequentes

**O que é idle compaction no Claude Code?** Uma conversa longa que você deixou de lado é resumida pouco antes de o cache de prompts de uma hora expirar. Sua próxima mensagem envia o resumo em vez de todo o histórico, que de outra forma seria reprocessado sem cache.

**Como desativo a idle compaction?** Coloque "idleCompaction": false em um arquivo de configurações ou mude a linha Idle compaction no /config (Claude Code v2.1.302 ou posterior). DISABLE_AUTO_COMPACT=1 também desativa, junto com a compactação automática.

**Por que minha conversa foi compactada se eu não rodei /compact?** Se o terminal mostra uma linha começando com “Compacted while idle, before the prompt cache expired”, foi a idle compaction. No VS Code e no app desktop o aviso menciona “a summary written while you were away”.

**Funciona com chave de API ou no modo -p?** Ela exige uma sessão interativa (terminal, painel de chat do VS Code ou a aba Code do app desktop) com o cache de uma hora. Com chave de API a conversa principal usa por padrão o cache de cinco minutos, a menos que você defina promptCacheTtl como 1h, e execuções com -p ficam de fora.

**Afeta vários agentes rodando em paralelo?** Cada sessão é avaliada sozinha. Agentes em pastas ou worktrees diferentes têm caches separados, então cada um que passar do limite e ficar parado por cerca de uma hora é compactado de forma independente.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/