Claude Code: como evitar sessões lentas e caras

Como evitar que uma sessão longa do Claude Code fique lenta e cara

Uma sessão longa do Claude Code fica lenta e cara porque cada turno reenvia todo o contexto, que continua a crescer. A correção é aplicar uma rotina de manutenção numa ordem fixa. Execute /context para ver o que está a ocupar a janela de contexto, remova os itens pelos quais paga em cada pedido e, em seguida, 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, porque uma cache de prompts fria transforma uma leitura barata numa reescrita completa de tudo o que disse.

A explicação para o contador continuar a avançar está em o contador de tokens por trás de uma sessão de agente.

Leia /context antes de alterar qualquer coisa

Não adivinhe o que preenche a janela. O Claude Code informará isso.

/context [all] mostra o uso atual do contexto numa grelha colorida, com sugestões de otimização para ferramentas que usam muito contexto e para excesso de memória; all expande a discriminação por item no modo de ecrã inteiro. Leia o resultado como cinco categorias.

• O prompt do sistema. As instruções do próprio mecanismo do Claude Code. Fixas durante a sessão.
• Definições das ferramentas. O esquema de todas as ferramentas que o agente pode chamar, incluindo todos os servidores MCP (Model Context Protocol) ligados.
• Ficheiros de memória. CLAUDE.md e a memória automática, carregados no início da sessão.
• Ficheiros e resultados das ferramentas. Todos os ficheiros lidos e tudo o que os seus comandos devolveram.
• Histórico de mensagens. As suas mensagens e as respostas do agente.

Os primeiros três representam um custo fixo, pago em todos os pedidos durante toda a sessão. Os dois últimos crescem. Reduza o custo fixo uma vez, no início; faça a gestão da parte crescente continuamente.

Duas cadeias 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 o pedido é recusado; o erro correspondente da API (application programming interface) é Prompt is too long. A segunda é uma janela de compactação, que pode ficar abaixo da janela de contexto real num modelo de 1 milhão de tokens. Os pedidos continuam a ser aceites depois desse ponto, pelo que se trata de um aviso, não de uma recusa.

Num plano pago, /usage acrescenta a outra metade, assinalando comportamentos como contexto longo ou falhas de cache e atribuindo o uso recente a competências, subagentes e servidores MCP individuais. Se indicar que o limite disponível já foi consumido, qual janela de limite está a aguardar determina se reduzir o contexto o ajuda agora ou se precisa de outro caminho para retomar o trabalho.

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

O seu CLAUDE.md é carregado no contexto no início da sessão e permanece lá. Se contiver um procedimento de implementação detalhado, esses tokens continuam presentes enquanto corrige um erro tipográfico num ficheiro de teste. A orientação da Anthropic é incluir apenas o essencial e manter o ficheiro abaixo de 200 linhas.

Mova os procedimentos para skills. Uma skill é carregada apenas quando é invocada, por isso um fluxo de trabalho executado duas vezes por semana não consome nada nos outros dias. As skills têm o seu próprio orçamento depois de uma compactação: os conteúdos são reinjetados, com um limite de 5,000 tokens por skill e 25,000 no total; as skills mais antigas são removidas primeiro. O truncamento mantém o início do ficheiro, por isso coloque as instruções mais importantes perto do topo de SKILL.md.

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

• O prompt do sistema e o estilo de saída não mudam, porque 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 a partir do disco.
• Uma regra com frontmatter paths: perde-se até que um ficheiro correspondente seja lido novamente.
• Um CLAUDE.md aninhado num subdiretório perde-se até que um ficheiro nesse subdiretório seja lido novamente.
• Os hooks continuam a ser executados, porque um hook é executado como código; apenas o contexto que um hook adicionou anteriormente é resumido com o resto da conversa.

Por isso, uma regra de que depende deve ficar no CLAUDE.md da raiz do projeto: Claude Code limpa primeiro as saídas mais antigas das ferramentas e depois faz um resumo, pelo que as instruções do início da conversa podem perder-se. Edite a memória com /memory. Claude Code mantém a cópia carregada no início da sessão, por isso uma redução no meio da sessão mantém a cache do prompt e não entra em vigor até ao próximo /clear, /compact ou reinício. A perda de contexto é apenas uma das razões para uma regra deixar de ser seguida. Quando a regra ainda está claramente na janela de contexto e, mesmo assim, é ignorada, analise primeiro as outras causas antes de a reescrever.

/clear entre tarefas, /compact dentro de uma

Estes dois comandos parecem intercambiáveis, mas têm custos muito diferentes.

/clear [name] inicia uma nova conversa com o contexto vazio. Não envia nenhum pedido, por isso não tem custo. Passe um nome para identificar a conversa anterior no seletor /resume; /reset e /new são aliases. Use-o assim que mudar para uma tarefa não relacionada, porque, caso contrário, a tarefa antiga seria reenviada e cobrada novamente a cada mensagem da nova tarefa.

/compact [instructions] liberta espaço no contexto e mantém a mesma conversa: resume o histórico até esse momento e substitui-o pelo resumo. Use-o dentro de uma tarefa longa, quando ainda precisa de continuidade.

Dê sempre uma instrução a /compact. Um /compact isolado resume com base num prompt predefinido que não sabe de que parte do trabalho ainda precisa. Um comando com instrução preserva essa informação:

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

Se faz a compactação sempre pelo mesmo motivo, coloque uma instrução permanente no CLAUDE.md do seu projeto, sob um cabeçalho # Compact instructions. Numa sessão nova, /compact apresenta Not enough messages to compact., o que significa que a conversa tem poucos turnos para ser resumida. Isto pode acontecer mesmo com o contexto cheio, quando uma única colagem grande o ocupou.

Há dois custos que são frequentemente confundidos. O pedido de resumo partilha o seu prefixo, por isso lê a cache existente em vez de processar novamente o histórico, e a maior parte do tempo é usada para gerar o resumo. Compactar um contexto grande continua a ser um pedido grande, porque a conversa resumida é a entrada. O turno depois da compactação não é a parte lenta: ele reconstrói a cache para um prompt muito mais curto.

Existem dois comandos mais baratos. /rewind reverte o código e a conversa para um checkpoint. Para um caminho que pretende abandonar completamente, é melhor do que compactar, porque recua até um prefixo que já está em cache. /recap acrescenta um resumo como saída de comando, em vez de substituir o histórico, mantendo intacto o prefixo em cache.

Quando a compactação automática é executada repetidamente, aparece isto:

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

A compactação foi concluída, mas um ficheiro ou a saída de uma ferramenta voltou a preencher a janela várias vezes seguidas, por isso o Claude Code deixou de tentar. Recupere lendo o ficheiro grande por intervalos de linhas, executando /compact com um foco que elimine a saída grande, transferindo esse trabalho para um subagente ou usando /clear se a conversa anterior já terminou.

Os servidores MCP representam um custo fixo

Cada servidor MCP que liga acrescenta dados a todos os pedidos durante toda a sessão. Paga esse custo mesmo que não o utilize.

O Claude Code reduz este impacto. Por predefinição, as definições das ferramentas MCP são adiadas. Assim, apenas os nomes das ferramentas entram no contexto até o Claude utilizar uma ferramenta específica. Execute /context para ver o custo real dos seus servidores e /mcp disable <name> para remover um que não vai utilizar hoje. Se executar os seus próprios servidores MCP num VPS, o mesmo cálculo limita o número de ferramentas que cada servidor deve expor.

Faça isto no início da sessão. Enquanto as definições permanecerem adiadas, ligar ou desligar um servidor apenas acrescenta conteúdo à conversa, e a cache permanece disponível. Quando as definições são carregadas no prefixo, porque a pesquisa de ferramentas está desativada, indisponível ou abaixo do limite auto, a mesma alteração faz com que o pedido seguinte leia tudo novamente.

Filtrar a saída detalhada das ferramentas antes de entrar no contexto

O resultado de uma ferramenta é uma entrada, e é reenviado em todas as mensagens seguintes. Uma execução de teste que despeja 20,000 tokens de saída não tem um custo único: paga por ela novamente em todas as mensagens até que saia da janela.

Filtre na origem. Um hook que reduz uma execução de teste apenas às falhas antes de Claude a ver transforma essa saída extensa em algumas centenas de tokens, nesta mensagem e em todas as retransmissões seguintes:

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

Os hooks nunca entram no contexto por si próprios, porque são executados como código. Faça isto para qualquer ferramenta cuja saída ultrapasse uma janela do terminal. A mesma lógica aplica-se a um ficheiro com 3,000 linhas: peça o intervalo de linhas de que precisa, porque o ficheiro completo permanece na janela assim que chega.

Defina o âmbito do que o agente lê e delegue o trabalho ruidoso

Um prompt que identifica o ficheiro e o sintoma lê esse ficheiro. Um pedido aberto para organizar o projeto lê tudo o que o agente considerar relevante, e cada uma dessas leituras permanece na janela de contexto.

Delegue o trabalho verboso a um subagente. As execuções de testes e o processamento de logs consomem contexto real; um subagente mantém essa saída na sua própria janela e devolve apenas um resumo. A contrapartida é que um subagente cria a sua própria cache, sem ocorrências na primeira chamada, e usa o período de validade de cinco minutos mesmo numa subscrição. A delegação protege de forma fiável o seu contexto principal. Nem sempre reduz o total de tokens.

O relógio da cache: trabalhe por períodos contínuos

A cache de prompts é o que torna o reenvio acessível. Escrever o prefixo custa 1.25x a tarifa base de entrada, ou 2x com a duração de uma hora. Lê-lo novamente custa 0.1x no Haiku 5.5, 0.05x no Opus 5.5 e no Sonnet 5.5 ($0.20 e $0.10 por milhão de tokens), e 0.025x no Fable 5.1 ($0.25 por milhão). Cada utilização atualiza a entrada sem custo adicional, por isso o relógio começa a contar novamente a partir da última utilização. Estes multiplicadores mostram a estrutura da fatura, mas não o seu valor. Combine-os com o custo real de um milhão de tokens para converter uma janela de contexto completa num valor em dólares.

A duração que obtém depende da forma como se autentica. É por isso que a afirmação genérica de que "a sua cache expira após cinco minutos" está errada.

• Numa subscrição Claude, o Claude Code solicita automaticamente a duração de uma hora.
• Depois de ultrapassar o limite do seu plano e começar a utilizar créditos de utilização, essa utilização é faturada, pelo que a duração volta a ser de cinco minutos.
• Com uma chave de API ou um fornecedor de cloud, a duração mantém-se em cinco minutos. Definir promptCacheTtl como 1h ou ENABLE_PROMPT_CACHING_1H=1 ativa a duração de uma hora, e FORCE_PROMPT_CACHING_5M=1 força o regresso a cinco minutos.

O conselho sobre o ritmo é o mesmo nos dois casos: trabalhe por períodos contínuos. Uma pausa superior à duração da cache faz com que o turno seguinte volte a escrever todo o prefixo acumulado. Uma sessão do Claude Code separada num tmux não tem custo enquanto está inativa. A cache quente é o que se perde durante esse período de inatividade.

Algumas ações eliminam a cache enquanto ainda está a trabalhar: mudar de modelo, alterar o nível de esforço em modelos mais antigos, ativar o modo rápido, ligar ou desligar um servidor MCP ou negar uma ferramenta inteira quando as definições das ferramentas são carregadas antecipadamente, ativar ou desativar um plugin que adiciona ferramentas, compactar, remover imagens antigas quando uma conversa contém demasiadas imagens e atualizar o Claude Code. No Opus 5.5, Sonnet 5.5, Haiku 5.5 e Fable 5.1 com uma chave de API ou uma subscrição, uma alteração do esforço mantém agora a cache. /model é a surpresa habitual, porque cada modelo tem a sua própria cache. Por isso, o pedido seguinte lê todo o histórico sem acertos de cache, apesar de o conteúdo ser idêntico. Essa nova leitura é faturada às tarifas do modelo de destino como uma nova escrita na cache. Assim, uma mudança para Fable a meio da sessão cobra todo o histórico acumulado às tarifas publicadas de escrita na cache do Fable: $12.50 por milhão de tokens com a duração de cinco minutos ou $20 com a duração de uma hora, o mesmo no Fable 5 e no Fable 5.1.

Editar ficheiros, editar CLAUDE.md, invocar skills e comandos, executar /recap, recuar e criar um subagente mantêm a cache. A cache está limitada a uma máquina e a um diretório, por isso duas sessões em diretórios diferentes não utilizam a cache uma da outra. Esse âmbito segue o CLI, não a sua conta. Por isso, nada é transferido para a aplicação Claude para desktop, que no Linux é uma instalação beta separada, paralela ao CLI.

Para verificar se a cache está a funcionar, leia current_usage. cache_creation_input_tokens foi escrito à tarifa de escrita na cache; cache_read_input_tokens foi servido à tarifa de leitura da cache do modelo, entre 2.5% e 10% da tarifa de entrada normal, dependendo do modelo. Um rácio elevado entre leituras e criações é saudável. Se a criação se mantiver elevada em todos os turnos, alguma parte do seu prefixo está a mudar continuamente.

Uma janela de contexto maior resolve isto?

Em parte. Todos os modelos atuais (Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5) usam uma janela de contexto de 1 million tokens, e a compactação funciona da mesma forma com esse limite maior. A economia não muda, porque o prompt completo continua a ser reenviado e faturado em cada turno. Uma janela maior determina quando é obrigado a agir; a higiene determina o custo. Se o problema for a fatura, e não o limite, qual plano Claude se adequa à forma como trabalha determina se está a gastar dólares ou a utilizar o plafond do plano.

A edição do contexto e a compactação na API são coisas diferentes

Se está a criar o seu próprio agente na Messages API, não existem comandos de barra e terá de implementar isto sozinho. Reserve orçamento para esse trabalho desde o início, porque as permissões gratuitas da API não pagarão pelos seus tokens. Os utilizadores novos recebem uma pequena quantidade de créditos gratuitos para testar a API, e a permissão permanente indicada pela Anthropic (50 horas gratuitas por dia por organização na página de preços, 1,550 por mês na documentação) cobre o tempo de execução do contentor de execução de código, que é cobrado separadamente dos tokens. Cada turno reenvia o histórico não reduzido e cobra todo o seu conteúdo: à tarifa de leitura da cache enquanto o prefixo está em cache, e à tarifa completa de entrada ou a um adicional de escrita na cache quando não está. O fornecedor escolhido para a implementação define essa aritmética antes de qualquer redução, por isso, se a escolha ainda estiver em aberto, calcule o custo da mesma carga de trabalho nas duas APIs em vez de comparar as tarifas anunciadas por token. Existem duas funcionalidades do lado do servidor para fazer este trabalho, mas não são a mesma funcionalidade.

A edição do contexto limpa seletivamente conteúdo específico do histórico da conversa à medida que este cresce, substituindo cada resultado limpo por texto de marcador para que o Claude saiba que algo foi removido. É uma funcionalidade beta: envie anthropic-beta: context-management-2025-06-27 e configure as estratégias em context_management.edits. clear_tool_uses_20250919 limpa os resultados das ferramentas, e clear_thinking_20251015 gere os blocos de raciocínio. O seu trigger tem como predefinição 100,000 tokens de entrada, keep os últimos 3 usos de ferramentas e clear_tool_inputs false, por isso as entradas permanecem e apenas os resultados são removidos.

A compactação gera um resumo e substitui por ele o histórico completo da conversa. Está disponível em duas funcionalidades beta. A compactação por limiar é executada dentro dos pedidos normais: envie anthropic-beta: compact-2026-01-12 e use o tipo de edição compact_20260112. O acionador tem como predefinição {"type": "input_tokens", "value": 150000}, e o valor tem de ser pelo menos 50,000. A compactação a pedido permite que o seu código decida quando a executar: envie anthropic-beta: compact-2026-09-04 com um "compaction": {"type": "summarize"} de nível superior, e a resposta será apenas o bloco de resumo. A visão geral da Anthropic sobre compactação recomenda usar a compactação a pedido sempre que estiver disponível.

A compactação por limiar tem uma regra de transferência que pode interromper agentes sem aviso. A resposta começa com um bloco de conteúdo compaction que contém o resumo, seguido pelo bloco de texto normal. Tem de devolver esse bloco nos pedidos seguintes, e a API elimina então todos os blocos de conteúdo anteriores. Na prática: acrescente o conteúdo completo de response.content, não apenas o texto. A compactação a pedido funciona ao contrário: remova por sua conta as mensagens resumidas, coloque o bloco devolvido no início de messages e envie-o exatamente como foi devolvido, incluindo a assinatura.

A documentação da Anthropic chama à compactação do lado do servidor a estratégia principal para gerir o contexto em conversas longas, e à edição do contexto a opção para controlar com maior precisão o que é removido. Verifique primeiro o suporte dos modelos. Todos os modelos atuais suportam os dois tipos de compactação, incluindo o Haiku 5.5; o modelo mais antigo claude-haiku-4-5 não suporta, e cada página de compactação contém a lista atualizada. Nenhuma destas funcionalidades beta controla o próprio /compact do Claude Code, que a documentação descreve como um pedido de resumo separado enviado pelo cliente com o seu histórico.

FAQ

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

Porque a conversa completa é enviada novamente a cada turno. Assim, uma pergunta de uma linha numa sessão aberta durante todo o dia inclui o dia inteiro. O armazenamento em cache de prompts mantém esse custo baixo enquanto o cache está ativo: uma leitura custa 0.1x a tarifa base de entrada no Haiku 5.5, 0.05x no Opus 5.5 e no Sonnet 5.5, e 0.025x no Fable 5.1. Quando um turno não encontra o prefixo no cache, o mesmo prefixo é gravado novamente a 1.25x, ou a 2x com o período de retenção de uma hora. Execute /context para ver o que está a ocupar a janela e leia o que é faturado numa sessão do Claude Code para perceber o mecanismo.

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

/clear inicia uma conversa nova com o contexto vazio. Não envia nenhum pedido, não tem qualquer custo e é a opção correta entre tarefas sem relação. /compact mantém a mesma conversa e substitui o histórico por um resumo. Por isso, é a opção correta dentro de uma tarefa longa. Indique um foco, como em /compact keep only the plan and the diff, porque essa instrução determina o que é preservado.

Como posso ver o que está a ocupar a janela de contexto do Claude Code?

Execute /context, ou /context all para obter a discriminação completa por item. O comando mostra o prompt do sistema, as definições das ferramentas, os servidores MCP, os ficheiros de memória e o histórico numa grelha colorida. Também apresenta sugestões para ferramentas que consomem muito contexto e para excesso de memória. Num plano pago, /usage também atribui o uso recente a skills, subagentes e servidores MCP individuais.

Devo usar uma janela de contexto de 1 million tokens em vez de compactar?

Uma janela maior adia o problema, mas não o resolve. Todos os modelos atuais (Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5) usam uma janela de contexto de 1 million tokens, e a compactação funciona da mesma forma nesse caso. Cada turno continua a reenviar o prompt completo e continua a ser faturado. Por isso, uma conversa com 400,000 tokens é cara, esteja ou não dentro do limite.

Qual é a diferença entre edição de contexto e compactação na Claude API?

A edição de contexto limpa seletivamente conteúdo antigo, sobretudo resultados de ferramentas, e deixa texto de marcador no lugar de cada item para que Claude saiba que foi removido. A compactação gera um resumo e substitui por ele o histórico completo. A documentação da Anthropic chama à compactação a estratégia principal para conversas longas e apresenta a edição de contexto como a opção de controlo mais detalhado. Ambas são funcionalidades beta com cabeçalhos próprios e ambas são separadas de /compact do Claude Code.