Buffer de Contexto do Claude Code

Você chega em 167K tokens. Claude compacta. O contexto escorrega. Sempre. Sem falha.

A parte chata: uma fatia da sua janela de contexto fica fora de alcance, reservada pelo próprio Claude Code. Essa fatia costumava ser 45.000 tokens (22,5% de 200K). No início de 2026, o buffer caiu para cerca de 33.000 tokens (16,5%), liberando uns 12K a mais de tokens para trabalho real.

Nenhum anúncio cobriu essa mudança no changelog oficial do Claude Code. A pista mais próxima é a v2.1.21: "Fixed auto-compact triggering too early on models with large output token limits", que provavelmente reajustou o cálculo do buffer. Posts e docs online ainda jogam fora o número de 45K, mas /context agora reporta 33K nas versões atuais.

O buffer existe por boas razões. Entender exatamente como funciona separa quem luta contra o sistema de quem trabalha com ele.

Leia esta página quando o buffer em si é a questão: quando a compactação dispara, por que o espaço reservado existe e quais variáveis de ambiente realmente fazem diferença. Se você quer o impacto mais amplo no fluxo de trabalho da janela maior, leia 1M Context Window in Claude Code. Se você quer regras práticas sobre quando continuar numa sessão versus resetá-la, leia Context Management.

Como a Auto-Compactação Realmente Funciona

O uso de contexto é monitorado continuamente pelo Claude Code. Em cerca de 83,5% da janela total (ante ~77-78% antes), a auto-compactação entra em ação.

Aqui está a sequência:

1. Claude resume o histórico da sua conversa
2. Mensagens antigas são substituídas por um resumo condensado
3. Você perde detalhes granulares do início da sessão
4. A sessão continua com contexto reduzido

Numa janela de 200K, a compactação cai por volta de 167K tokens de uso real. Aqueles 33K de buffer não ficam ociosos. Claude os gasta na própria sumarização.

O Comando /context

Rode /context para ver exatamente onde seus tokens estão indo:

claude-opus-4-5-20251101 · 76k/200k tokens (38%)

System prompt: 2.7k tokens (1.3%)
System tools: 16.8k tokens (8.4%)
Custom agents: 1.3k tokens (0.7%)
Memory files: 7.4k tokens (3.7%)
Skills: 1.0k tokens (0.5%)
Messages: 9.6k tokens (4.8%)
Free space: 118k (58.9%)
Autocompact buffer: 33.0k tokens (16.5%)

A linha Messages é seu histórico de conversa. Acompanhe ela subir. Quando o espaço livre chega a zero (buffer incluído), a compactação dispara.

Por Que o Buffer Existe

Três trabalhos caem sobre esses ~33K:

1. Espaço de trabalho para compactação. O processo de sumarização em si precisa de tokens para operar
2. Buffer de conclusão. Permite que tarefas atuais terminem antes de a compactação disparar
3. Espaço para geração de resposta. Claude precisa de memória de trabalho para raciocinar e construir respostas

O buffer está integrado na arquitetura do Claude Code. Pedidos para torná-lo configurável foram fechados como duplicatas. A Issue #15435 do GitHub pediu isso. A resposta foi não.

O Equívoco sobre Tokens de Saída

Muitos desenvolvedores acham que CLAUDE_CODE_MAX_OUTPUT_TOKENS governa o buffer de compactação.

Não governa.

Dois mecanismos diferentes, zero sobreposição:

• Tokens de saída. Limita o tamanho de uma única resposta do Claude
• Buffer de compactação. Espaço de contexto reservado que dispara a auto-compactação

Configure CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000 e você vai encolher o comprimento máximo de resposta do Claude. O contexto antes da compactação não vai mudar. O buffer de 33K é fixo.

# This limits response length, NOT context buffer
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

Razões para baixar os tokens de saída:

• Respostas mais rápidas (menos para gerar)
• Custos menores por resposta
• Forçar concisão

Contexto utilizável antes da compactação? Ainda ~167K.

Um detalhe que vale destacar: embora CLAUDE_CODE_MAX_OUTPUT_TOKENS não mexa no buffer de compactação, empurrá-lo muito alto pode reduzir sua janela de contexto efetiva. Tokens de saída são cortados do mesmo pool de contexto, então uma reserva de saída maior toma espaço do histórico e contexto de sistema. O padrão de 32K equilibra bem para a maioria dos fluxos.

O Impacto no Mundo Real

Imagine uma sessão pesada típica:

Com um buffer de 33K, a compactação bate em 167K. Esse é seu teto de trabalho, 12K mais alto do que o antigo de 155K.

Para onde vai a informação? Para o resumo. Nomes exatos de variáveis, mensagens de erro precisas, escolhas sutis do início da sessão tudo é espremido num recap que pega o essencial e perde o detalhe.

O Que Você Pode Realmente Controlar

1. Sobrescrever a Porcentagem do Gatilho de Compactação

Uma variável de ambiente realmente muda quando a auto-compactação dispara: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.

# Trigger compaction at 90% instead of the default ~83.5%
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90
 
# Trigger earlier at 70% for more aggressive compaction
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

Valores de 1 a 100 são aceitos. O número define diretamente a porcentagem em que a auto-compactação dispara. Um valor maior dá mais contexto utilizável antes da compactação e deixa menos espaço para o resumo. Um valor menor dispara a compactação mais cedo, mantém mais espaço de trabalho e te dá menos espaço antes do primeiro hit.

É o mais próximo de um buffer configurável que você consegue. Não muda o tamanho do buffer. Move o momento em que a compactação dispara em relação à janela total.

2. Usar Modelos com Contexto Estendido

Em vez de brigar com o limite de 200K, apele para a janela de contexto de 1M tokens.

A partir de março de 2026, a janela de contexto de 1M está geralmente disponível para Opus 4.6 e Sonnet 4.6, sem premium de preço. Um pedido de 900K tokens custa o mesmo por token que um de 9K. Veja nosso guia de janela de contexto de 1M para o detalhamento completo do que mudou e o que isso significa para seu fluxo.

/model sonnet[1m]

Com 1M tokens, o limite de compactação se afasta muito. Mesmo após um buffer proporcional, o espaço antes da compactação cresce substancialmente. Veja o guia de seleção de modelos para a referência completa de aliases.

3. Desativar a Auto-Compactação (Arriscado)

// ~/.claude/settings.json
{
  "autoCompact": false
}

Atenção. A Issue #18264 do GitHub reporta que a configuração pode ser ignorada em alguns casos. Mesmo quando funciona, você arrisca bater nos limites duros de contexto e crashar sessões.

Só mude isso se estiver pronto para:

• Monitorar o contexto manualmente com /context
• Rodar /compact antes de chegar a 100%
• Aceitar crashes de sessão ocasionais

4. Compactação Manual em Pontos Estratégicos

Desative o auto-compact e compacte no seu ritmo:

/compact   # Compact when you decide
/clear     # Full reset when starting new major task

Bons momentos para compactar de propósito:

• Após completar uma feature maior
• Antes de começar um novo componente
• Quando o contexto de debugging parece obsoleto

Vantagem: você escolhe o que é resumido e quando, o que mantém os detalhes finos ao redor do trabalho ativo.

5. Trabalhar Dentro do Limite de 167K

Aceite que sessões pesadas vão compactar. Configure para isso:

• Mantenha CLAUDE.md e skills enxutos
• Use arquivos de sessão para persistir estado
• Divida tarefas complexas em múltiplas sessões

6. Estratégia de Backup Proativo

O movimento mais eficaz: fazer backup antes da compactação chegar.

Uma ideia que está pegando na comunidade do Claude Code: limpeza proativa a 50% mais recuperação estruturada supera a auto-compactação com perda de dados.

A auto-compactação condensa sua conversa e descarta o detalhe fino. Mas faça isso em vez disso:

1. Registre continuamente sua sessão em um backup estruturado
2. Limpe o contexto manualmente em um limite (como 50%)
3. Recarregue do backup estruturado em vez do resumo com perdas

A fidelidade do contexto sobe. O backup guarda detalhes exatos que a sumarização descarta.

Como Escolher Seu Modo de Operação

A maioria das pessoas não precisa de uma configuração mágica. Precisa do modo certo para o tipo de trabalho que está fazendo.

A pergunta certa não é "como vejo o buffer?". É "o quanto uma compactação com perda custa para esta sessão?"

Três Exemplos Práticos

Exemplo 1: Build de feature comum

Você está construindo uma feature, mexendo em alguns arquivos, e a sessão dificilmente vai passar de 100K tokens.

Melhor opção:

• use os padrões
• cheque /context uma ou duas vezes
• não complique

O buffer não é seu problema aqui.

Exemplo 2: Sessão de debugging com muitos becos sem saída

Você passa 40 minutos inspecionando logs, traces e hipóteses fracassadas. Você já sabe que a próxima fase será implementação.

Melhor opção:

• não espere pelo autocompact
• rode /compact focus on the confirmed root cause, affected files, and fix plan
• continue para a implementação

Isso mantém o diagnóstico útil enquanto descarta o lixo.

Exemplo 3: Sessão de conteúdo de alto detalhe ou auditoria

Suponha que você está auditando um fluxo de segurança ou escrevendo um artigo com muitas fontes. Citações exatas, caminhos de arquivo e comportamento observado importam.

Melhor opção:

• mantenha um backup estruturado ou arquivo de notas
• limpe mais cedo do que o normal
• restaure do backup exato em vez de confiar num resumo compactado

É aqui que o fluxo de backup ganha. O problema não é capacidade bruta. É fidelidade da informação.

Quando Mudar CLAUDE_AUTOCOMPACT_PCT_OVERRIDE

Essa variável é útil, mas só em casos específicos.

Aumente quando:

• a tarefa atual é coerente e você quer mais espaço antes da compactação
• você está monitorando o uso ativamente
• o custo de uma compactação muito cedo é maior que o risco de esperar

Diminua quando:

• a sessão está bagunçada e você quer resumos mais cedo
• você está ok com compactações mais frequentes
• você quer que Claude mantenha o conjunto de trabalho mais enxuto

Deixe como está quando:

• você não está monitorando o contexto ativamente
• você não tem uma razão clara para mudar o gatilho
• o problema real é troca de tarefa, não compactação

Mudar o gatilho não substitui bons limites de sessão. Só desloca quando o mesmo mecanismo subjacente dispara.

StatusLine: O Único Monitor em Tempo Real

StatusLine é o único mecanismo que obtém métricas de contexto em tempo real. Outros hooks não recebem contagens de tokens.

// .claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/context-monitor.mjs"
  }
}

O statusline recebe JSON com context_window.remaining_percentage. São dados ao vivo, prontos para agir.

Cálculo crítico. O campo remaining_percentage já conta o buffer de autocompact de 16,5%. Para o "livre até autocompact" real:

const AUTOCOMPACT_BUFFER_PCT = 16.5;
const freeUntilCompact = Math.max(
  0,
  remaining_percentage - AUTOCOMPACT_BUFFER_PCT,
);

25% restante realmente significa 8,5% antes da compactação.

Por Que Hooks Não Conseguem Injetar /clear

Uma parede técnica com que muita gente esbarra: hooks não conseguem injetar slash commands.

Suposição razoável: um hook detecta uso alto de contexto e injeta /clear. Não consegue:

• UserPromptSubmit não tem campo updatedPrompt. Pode adicionar contexto ou bloquear, mas nunca substituir
• Slash commands pulam a avaliação de hooks completamente
• Nenhum hook dispara "em vez de" input do usuário

Formas reais de limpar e recuperar programaticamente:

1. Claude Agent SDK. Envie /clear via SDK
2. Wrapper CLI headless. Passe comandos para o Claude Code headless
3. Fluxo manual. Hook avisa, você roda /clear, SessionStart restaura

O Que Acontece com 100% de Contexto

Empurre o contexto até a borda e veja o que segue:

1. Melhor caso. A resposta do Claude é truncada
2. Caso pior. A API retorna um erro, a rodada falha
3. Pior caso. A sessão fica sem resposta

O buffer de 33K existe para evitar que isso aconteça. É proteção, não desperdício.

Pontos-Chave

1. O buffer caiu de 45K para 33K. Mudança não documentada, uns 12K a mais de tokens utilizáveis
2. A compactação agora dispara em ~83,5% de uso. Isso coloca o contexto utilizável em ~167K (ante ~155K)
3. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE muda o gatilho. Valores de 1 a 100 definem quando a compactação dispara
4. sonnet[1m] oferece contexto de 1M tokens. Uma alternativa real a brigar com limites de 200K
5. Tokens de saída e buffer de compactação são separados. Não os confunda
6. autoCompact: false pode funcionar. Também tem bugs reportados
7. StatusLine é o único monitor de contexto ao vivo. Outros hooks não veem contagens de tokens
8. Hooks não conseguem injetar /clear. Passe pelo SDK, um wrapper ou um fluxo manual
9. Limpeza proativa mais recuperação estruturada supera a auto-compactação com perdas

O buffer existe por boas razões. Em vez de lutar contra ele, trabalhe junto: mantenha estado em arquivos de sessão, faça backups baseados em limite antes da compactação, e pense em limpeza proativa para sessões pesadas.

A Solução: Backups Baseados em Limite

O buffer é fixo. Como você lida com a aproximação dele não é.

Confira nosso sistema de backup baseado em limite para uma configuração proativa que observa o contexto pelo StatusLine e cria backups a 30%, 15% e 5% restantes, antes que a compactação apague seu histórico de sessão.

Recursos Relacionados

• Context Recovery Hook - Sistema de backup baseado em limite
• Context Engineering Guide - Uso estratégico de contexto
• Memory Optimization - Reduzir overhead de contexto estático
• Claude Code Hooks Guide - Todos os 12 tipos de hooks explicados