Claude Code sessão lenta ou cara como resolver

Como evitar que sessões longas do Claude Code fiquem lentas e caras

Uma sessão longa do Claude Code fica lenta e cara porque cada turno reenvia todo o contexto, e esse contexto apenas cresce. A solução é manter a higiene em uma ordem específica. Execute /context para ver o que está ocupando o histórico, remova os itens pelos quais você paga em cada requisição, use /clear entre tarefas não relacionadas e /compact com uma instrução dentro de uma única tarefa longa. Trabalhe em períodos contínuos, pois um prompt cache frio transforma uma leitura barata em uma reescrita completa de tudo o que foi dito.

O motivo de o consumo ocorrer é explicado em o medidor de tokens por trás de uma sessão de agente.

Leia o /context antes de alterar qualquer coisa

Não tente adivinhar o que preenche a janela. O Claude Code informará.

O /context [all] exibe o uso atual do contexto como uma grade colorida, com sugestões de otimização para ferramentas com muito contexto e excesso de memória; o all expande o detalhamento por item no modo tela cheia. Leia o resultado como cinco categorias.

• O system prompt. As instruções de harness do próprio Claude Code. Fixas para a sessão.
• Tool definitions. O schema de cada ferramenta que o agente pode chamar, incluindo todos os servidores MCP (Model Context Protocol) conectados.
• Memory files. CLAUDE.md e memória automática, carregados no início da sessão.
• Files and tool results. Cada arquivo lido e tudo o que seus comandos imprimiram de volta.
• Message history. Suas interações e as respostas dele.

Os três primeiros são um custo fixo, pago em cada requisição durante a sessão. Os dois últimos crescem. Reduza o custo fixo uma vez, no início; gerencie a parte crescente continuamente.

Duas strings indicam que a janela está cheia:

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

A primeira é um limite rígido, e a requisição é recusada; o erro de API correspondente é Prompt is too long. A segunda é uma janela de compactação, que pode estar abaixo da janela de contexto real do modelo em um modelo de 1 milhão de tokens. Requisições ainda funcionam após ela, portanto, essa é um aviso em vez de uma recusa.

Em um plano pago, o /usage adiciona a outra metade, sinalizando comportamentos como contexto longo ou cache misses e atribuindo o uso recente a skills individuais, subagents e servidores MCP.

CLAUDE.md é um custo permanente, mantenha-o enxuto

Seu CLAUDE.md é carregado no contexto no início da sessão e permanece lá. Se ele contiver um procedimento de deployment detalhado, esses tokens estarão presentes enquanto você corrige um erro de digitação em um arquivo de teste. A orientação da Anthropic é incluir apenas o essencial e manter o arquivo com menos de 200 linhas.

Mova procedimentos para skills. Uma skill é carregada apenas quando invocada; portanto, um workflow que você executa duas vezes por semana não consome recursos nos outros dias. Skills possuem orçamento próprio após uma compactação: o conteúdo é reinjetado, com limite de 5.000 tokens por skill e 25.000 no total, descartando os mais antigos primeiro. A truncagem preserva o início do arquivo, portanto, coloque as instruções mais importantes no topo do SKILL.md.

O que sobrevive a uma compactação determina onde uma instrução deve ficar.

• O system prompt e o estilo de saída não mudam, pois não fazem parte do histórico de mensagens.
• O CLAUDE.md na raiz do projeto, as regras sem escopo e a memória automática são reinjetados do disco.
• Uma regra com frontmatter paths: é perdida até que um arquivo correspondente seja lido novamente.
• Um CLAUDE.md aninhado em um subdiretório é perdido até que um arquivo nesse subdiretório seja lido novamente.
• Hooks não são afetados, pois um hook executa como código e nunca entra no contexto.

Portanto, uma regra da qual você depende deve estar no CLAUDE.md da raiz do projeto: o Claude Code limpa primeiro as saídas de ferramentas mais antigas e depois resume, então instruções do início da conversa podem ser perdidas. Edite a memória com /memory. O Claude Code mantém a cópia carregada no início da sessão, então um corte no meio da sessão mantém o prompt cache e só é aplicado no próximo /clear, /compact ou reinício.

/clear entre tarefas, /compact dentro de uma

Estes dois comandos parecem intercambiáveis, mas possuem custos muito diferentes.

/clear [name] inicia uma nova conversa com contexto vazio. Ele não envia nenhuma requisição, portanto não tem custo. Passe um nome para rotular a conversa anterior no seletor /resume; /reset e /new são aliases. Use este comando ao mudar para uma tarefa não relacionada, pois, caso contrário, a tarefa antiga será reenviada e cobrada novamente em cada mensagem da nova.

/compact [instructions] libera o contexto mantendo a mesma conversa: ele resume o histórico atual e o substitui. Use este comando dentro de uma tarefa longa onde a continuidade ainda é necessária.

Sempre forneça uma instrução para o /compact. Um comando /compact puro utiliza um prompt padrão que não sabe qual parte do trabalho você ainda precisa. Um comando com instrução mantém o contexto necessário:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Se você compactar pelo mesmo motivo sempre, adicione uma instrução fixa no CLAUDE.md do seu projeto sob um cabeçalho # Compact instructions. Em uma nova sessão, o /compact imprime Not enough messages to compact., o que significa que ainda não há histórico.

Dois custos podem causar confusão aqui. A requisição de sumarização compartilha seu prefixo, então ela lê o cache existente em vez de reprocessar o histórico; a maior parte do tempo é gasta gerando o resumo. Compactar um contexto grande ainda é uma requisição grande, pois a conversa sendo sumarizada é a entrada. O turno após a compactação não é a parte lenta: ele reconstrói o cache para um prompt muito menor.

Existem dois comandos mais baratos. O /rewind [description] reverte o código e a conversa para um checkpoint; para um caminho que você deseja abandonar totalmente, ele é melhor que o compactar, pois trunca o histórico para um prefixo que já está em cache. O /recap anexa um resumo como saída do comando em vez de substituir o histórico, mantendo o prefixo em cache intacto.

A compactação automática repetitiva imprime isto:

Autocompact is thrashing: the context refilled to the limit...

A compactação foi bem-sucedida, mas a saída de um arquivo ou ferramenta preencheu a janela várias vezes seguidas, então o Claude Code parou de tentar. Recupere lendo o arquivo grande em intervalos de linha, executando /compact com um foco que descarte a saída grande, movendo esse trabalho para um subagent, ou /clear se a conversa anterior estiver finalizada.

Servidores MCP possuem overhead fixo

Cada servidor MCP conectado adiciona carga a cada requisição durante toda a sessão. O custo ocorre independentemente de você chamar a ferramenta ou não.

O Claude Code mitiga isso. Por padrão, as definições de ferramentas MCP são adiadas, então apenas os nomes das ferramentas entram no contexto até que o Claude utilize uma ferramenta específica. Execute /context para ver o custo real dos seus servidores, e /mcp disable <name> para remover um que você não usará hoje. Se você executar seus próprios servidores MCP em um VPS, a mesma lógica limita a quantidade de ferramentas que um servidor deve expor.

Faça isso no início de uma sessão. Enquanto as definições forem adiadas, conectar ou desconectar um servidor apenas adiciona informações à conversa, e o cache é mantido. Quando as definições são carregadas no prefixo — porque a busca de ferramentas está desativada ou um servidor está isento de adiamento — a mesma alteração faz com que a próxima requisição releia tudo.

Filtre a saída de ferramentas verbosas antes de entrar no contexto

O resultado de uma ferramenta é um input, e o input é reenviado em cada turno subsequente. Uma execução de teste que gera 20.000 tokens de saída não é um custo único: você paga novamente por isso em cada turno até que o conteúdo saia da janela de contexto.

Filtre na origem. Um hook que reduz a execução de um teste apenas aos erros antes que o Claude os veja transforma esse bloco de saída em apenas algumas centenas de tokens, tanto neste turno quanto em cada reenvio:

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Hooks nunca entram no contexto, pois são executados como código. Faça isso para qualquer ferramenta cuja saída ultrapasse o limite da tela. A mesma lógica se aplica a um arquivo de 3.000 linhas: solicite apenas o intervalo de linhas necessário, pois o arquivo inteiro permanece na janela de contexto após o recebimento.

Defina o escopo de leitura do agente e delegue tarefas ruidosas

Um prompt que especifica um arquivo fará a leitura apenas desse arquivo. Um pedido genérico para organizar o projeto fará a leitura de tudo o que o agente considerar relevante, e cada uma dessas leituras ocupará espaço na janela de contexto.

Delegue tarefas verbosas para um subagente. Execuções de testes e o processamento de logs consomem muito contexto; um subagente mantém essa saída em sua própria janela e retorna apenas um resumo. O tradeoff: um subagente constrói seu próprio cache, que não possui hits na primeira chamada, e utiliza o tempo de vida de cache de cinco minutos mesmo em assinaturas. A delegação protege o seu contexto principal de forma confiável. Ela nem sempre reduz o total de tokens.

O clock do cache: trabalhe em períodos

O prompt caching torna o reenvio acessível: 0.1x a taxa de entrada base para leitura do prefixo, contra 1.25x para escrita, ou 2x para escrita com lifetime de uma hora. Cada uso renova a entrada sem custo adicional, portanto o cronômetro reinicia a partir do último uso.

O lifetime que você recebe depende de como você se autentica; é por isso que a afirmação genérica "seu cache expira após cinco minutos" está incorreta.

• Em uma assinatura Claude, o Claude Code solicita o lifetime de uma hora automaticamente.
• Quando você ultrapassa o limite do seu plano e utiliza créditos de uso, você é cobrado por esse uso, então o tempo cai para cinco minutos.
• Em uma API key ou provedor de nuvem, o tempo permanece em cinco minutos. ENABLE_PROMPT_CACHING_1H=1 opta pelo lifetime de uma hora, e FORCE_PROMPT_CACHING_5M=1 força o retorno para cinco minutos.

O conselho sobre o ritmo é o mesmo para ambos os casos: trabalhe em períodos contínuos, pois um intervalo de ociosidade que exceda o lifetime fará com que sua próxima execução reescreva todo o prefixo acumulado. Uma sessão do Claude Code desvinculada no tmux não custa nada enquanto ociosa, e o cache aquecido é o que o tempo de ociosidade preserva.

Algumas ações descartam o cache enquanto você ainda está trabalhando: trocar de modelo, alterar o nível de esforço, ativar o fast mode, conectar ou desconectar um servidor MCP, habilitar ou desabilitar um plugin, negar uma ferramenta inteira, compactar e atualizar o Claude Code. /model é a surpresa comum, pois cada modelo possui seu próprio cache; assim, a próxima requisição lerá todo o histórico sem hits de cache, mesmo que o conteúdo seja idêntico.

Editar arquivos, editar CLAUDE.md, invocar skills e comandos, executar /recap, fazer rewind e iniciar um subagent mantêm o cache. O escopo é limitado a uma máquina e um diretório; portanto, duas sessões em diretórios diferentes não compartilham o cache entre si.

Para verificar se o caching está funcionando, leia current_usage. cache_creation_input_tokens foi escrita na taxa de escrita do cache; cache_read_input_tokens foi servida a aproximadamente um décimo da taxa de entrada padrão. Um alto ratio de leitura para criação indica um estado saudável. Se a criação permanecer alta turno após turno, algo em seu prefixo está mudando constantemente.

Um context window maior resolve isso?

Parcialmente. Vários modelos atuais suportam um context window de 1 milhão de tokens, e a compactação funciona da mesma forma no limite superior. A economia não muda, pois o prompt completo ainda é reenviado e cobrado em cada turno. Um context window maior define quando você é forçado a agir; a higiene define o custo. Se o problema for o valor cobrado em vez do limite de tokens, qual plano do Claude se adapta ao seu fluxo de trabalho decide se você gastará dólares ou a cota do plano.

Edição de contexto e compactação na API são coisas diferentes

Se você estiver construindo seu próprio agente na Messages API, comandos de barra (slash commands) não existem e você deve implementá-los manualmente. Dois recursos do lado do servidor realizam essa função, e eles não são o mesmo recurso.

Edição de contexto remove seletivamente conteúdos específicos do histórico da conversa conforme ele cresce, substituindo cada item removido por um texto de placeholder para que o Claude saiba que algo foi excluído. É uma versão beta: envie anthropic-beta: context-management-2025-06-27 e configure as estratégias em context_management.edits. clear_tool_uses_20250919 limpa resultados de ferramentas (tool results), e clear_thinking_20251015 gerencia blocos de pensamento (thinking blocks). O trigger tem como padrão 100.000 tokens de entrada, o keep os últimos 3 usos de ferramentas, e o clear_tool_inputs é definido como false, garantindo que as entradas permaneçam e apenas os resultados sejam removidos.

Compactação gera um resumo e substitui todo o histórico da conversa por ele. Também é uma versão beta: envie anthropic-beta: compact-2026-01-12 e use o tipo de edição compact_20260112. O gatilho padrão é {"type": "input_tokens", "value": 150000}, e o valor deve ser de no mínimo 50.000.

A compactação possui uma regra de transferência que quebra agentes silenciosamente. A resposta começa com um bloco de conteúdo compaction contendo o resumo, seguido pelo bloco de texto normal. Você deve reenviar esse bloco em requisições posteriores, e a API então descartará todos os blocos de conteúdo anteriores a ele. Na prática: anexe o conteúdo completo de response.content, não apenas o texto.

A documentação da Anthropic define a compactação no lado do servidor como a estratégia principal para gerenciar o contexto em conversas longas, e a edição de contexto como a opção para controle refinado sobre o que é removido. Verifique o suporte do modelo primeiro. Os modelos atuais Opus, Sonnet e Fable suportam compactação; claude-haiku-4-5 não suporta, e a página de compactação contém a lista atualizada. Nenhuma das betas controla o /compact do Claude Code, que sua documentação descreve como uma requisição de sumarização única enviada pelo cliente.

FAQ

Por que minha sessão do Claude Code fica mais lenta e cara quanto mais tempo ela dura?

Porque a conversa inteira é enviada novamente em cada turno. Uma pergunta de uma linha em uma sessão aberta o dia todo carrega todo o histórico do dia. O prompt caching mantém o custo baixo enquanto o cache estiver ativo, a 0.1x da taxa de input base para leitura; quando um turno não encontra o cache, o mesmo prefixo é reescrito a 1.25x. Execute /context para ver o que está ocupando a janela, e leia o que compõe a cobrança de uma sessão do Claude Code para entender o mecanismo.

Qual é a diferença entre /clear e /compact no Claude Code?

O /clear inicia uma nova conversa com contexto vazio. Ele não envia nenhuma requisição, portanto não tem custo, sendo a escolha correta para tarefas não relacionadas. O /compact mantém a mesma conversa e substitui o histórico por um resumo, sendo a escolha correta dentro de uma única tarefa longa. Forneça um foco, como em /compact keep only the plan and the diff, pois a instrução define o que será mantido.

Como vejo o que está consumindo a janela de contexto do meu Claude Code?

Execute /context, ou /context all para o detalhamento completo por item. Ele exibe o system prompt, definições de ferramentas, servidores MCP, arquivos de memória e o histórico em uma grade colorida, com sugestões para ferramentas com muito contexto e excesso de memória. Em planos pagos, o /usage também atribui o uso recente a skills, subagents e servidores MCP individuais.

Devo usar uma janela de contexto de 1 milhão de tokens em vez de compactar?

Uma janela maior apenas adia o problema em vez de resolvê-lo. Vários modelos atuais suportam uma janela de contexto de 1 milhão de tokens, incluindo Opus 4.8 e Sonnet 5, e a compactação funciona da mesma forma neles. Cada turno ainda reenvia o prompt completo e ainda gera cobrança; portanto, uma conversa de 400.000 tokens é cara independentemente de caber ou não no limite.

Qual é a diferença entre context editing e compaction na Claude API?

O context editing limpa seletivamente o conteúdo antigo, principalmente resultados de ferramentas, deixando um texto de placeholder onde cada um estava para que o Claude saiba que foi removido. A compaction gera um resumo e substitui o histórico completo por ele. A documentação da Anthropic define a compaction como a estratégia principal para conversas longas e posiciona o context editing como a opção de ajuste fino. Ambos são betas com seus próprios headers, e ambos são independentes do /compact do Claude Code.