Como reduzir tokens no Claude Code: Context Mode e Headroom

Para reduzir o consumo de tokens no Claude Code, descubra primeiro o que ocupa o contexto e evite levar saídas desnecessárias de ferramentas para a conversa. Comece pelos controles nativos; experimente o Context Mode para processar dados seletivamente e continuar o trabalho após a compactação, ou o Headroom para comprimir conteúdo por meio de um proxy local. Se o maior consumo vem do raciocínio e de tentativas repetidas sem sucesso, ajuste o escopo da tarefa e a escolha do modelo antes de adicionar qualquer um deles.

Em 2026-10-21, a versão atual do Claude Code é a 2.1.306. A instalação do Headroom abaixo fixa a versão 0.41.0.

Onde o Claude Code está gastando tokens?

Use /context para diagnosticar a ocupação do contexto e /usage para consultar o consumo e a estimativa de custo. Cada comando responde a uma pergunta diferente.

Pergunta	Onde verificar	O que mostra
Por que esta conversa está enchendo o contexto?	/context	Espaço ocupado por instruções, mensagens, ferramentas e outros elementos do contexto
Quanto esta sessão consumiu?	/usage	Categorias de tokens e custo estimado da sessão
Estou perto de atingir o limite da assinatura?	Informações do plano em /usage	Consumo da franquia do plano, separado da cobrança da API
Quanto foi efetivamente cobrado?	Registros de uso do provedor responsável pela cobrança	Valores calculados conforme as tarifas e regras desse provedor

No Claude Code atual, /cost é um alias de /usage. O valor em dólares é uma estimativa: ele não significa que cada solicitação incluída no Pro ou Max gera aquela cobrança adicional. A diferença está explicada na documentação de custos do Claude Code.

Logs extensos, capturas do estado do navegador, arquivos de dependências e resultados repetidos de ferramentas podem ocupar bastante contexto. As mensagens anteriores também participam das solicitações seguintes, mas o cache de prompts pode tornar a reutilização da entrada mais barata do que uma entrada nova. Portanto, reduzir o conteúdo visível em 50% não produz automaticamente uma conta 50% menor.

Use os controles nativos antes de adicionar compressão

Escolha o controle conforme a origem do desperdício: limite a busca quando houver saída demais, abra uma conversa nova para outro assunto e compacte o histórico quando precisar continuar uma tarefa longa.

Informe ao Claude os caminhos exatos dos arquivos, os nomes dos testes que falham e um comando concreto para verificar o resultado. Pedir a análise de um módulo com falha costuma gerar menos trabalho desnecessário do que pedir que ele entenda o repositório inteiro antes de fazer uma alteração pequena.

Use /clear entre tarefas sem relação, depois de registrar as métricas de consumo que deseja guardar. Para continuar a mesma tarefa, use /compact com instruções específicas, por exemplo:

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

Essas práticas de gerenciamento de contexto estão documentadas, mas a compactação produz um resumo, não uma memória exata de tudo o que aconteceu. Mantenha critérios de aceitação importantes nas instruções permanentes do projeto ou nas notas da tarefa.

Evite compactar após cada troca de mensagens. A compactação faz uma solicitação para gerar o resumo e substitui o histórico; a próxima solicitação precisa estabelecer um prefixo mais curto no cache. Compactar com frequência pode economizar contexto ao custo de trabalho adicional e reconstrução do cache.

Para tarefas simples em modelos que oferecem controle de esforço de raciocínio, experimente /effort low. Um esforço menor pode reduzir o trabalho de raciocínio, mas não diminui um log que uma ferramenta já retornou. Alterações de esforço feitas por comando ficam salvas para o modelo selecionado, então restaure sua configuração preferida após a comparação. A documentação de configuração de modelos explica os controles disponíveis e os aliases.

Subagentes oferecem outra forma nativa de separar o trabalho: eles usam um contexto próprio e retornam um resumo. Isso preserva espaço na conversa principal, mas suas solicitações também consomem tokens.

Context Mode ou Headroom: qual experimentar?

Escolha o Context Mode quando puder reduzir os dados antes de devolvê-los ao Claude. Escolha o Headroom quando quiser passar chamadas de ferramentas já existentes por uma camada de compressão.

Seu gargalo	Experimente primeiro	O que muda
Arquivos ou logs grandes que podem ser consultados ou processados localmente	Context Mode	Claude usa ferramentas de execução e busca para receber resultados selecionados
Perda de partes do estado da tarefa após a compactação	Context Mode	Hooks do ciclo da sessão registram eventos e recuperam informações para continuar
Saída excessiva de ferramentas do fluxo atual	Headroom	Um proxy local comprime o conteúdo elegível antes de encaminhar as solicitações
Tarefas curtas dominadas por raciocínio ou novas tentativas	Controles nativos de escopo, esforço e modelo	A quantidade de trabalho muda antes da introdução de outro componente

Teste uma ferramenta por vez para identificar o que causou a diferença.

Os percentuais publicados não são diretamente comparáveis. O material de benchmark do Context Mode mede bytes de saída em exemplos selecionados. Os resultados de 21%–57% do Headroom vêm de cargas de saída de ferramentas geradas de forma reproduzível e avaliadas offline. Nenhum deles determina a redução na conta completa do Claude Code, nem dispensa a verificação de que a tarefa continua sendo concluída corretamente.

Context Mode: retorne o resultado, não o arquivo inteiro

O Context Mode é útil quando uma operação local consegue produzir a resposta sem inserir todos os dados de entrada na conversa do Claude. O plugin também registra determinados eventos da sessão em SQLite e usa hooks, ou seja, ações acionadas por eventos, para recuperar informações de continuidade após a compactação.

O pacote atual exige Node.js 22.5.0 ou mais recente. Confira sua instalação no Bash:

claude --version
node --version

Dentro do Claude Code, siga a instalação pelo marketplace documentada pelo projeto:

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Reinicie o Claude Code e execute:

/context-mode:ctx-doctor

O comando de diagnóstico verifica componentes como ambientes de execução, registro do plugin, hooks e suporte a buscas no SQLite. Resolva as falhas relevantes antes de considerar o plugin ativo. Instalar apenas o servidor MCP não fornece a mesma integração com os eventos da sessão.

Para uma verificação concreta, abra um projeto npm que já tenha um package-lock.json na versão 2 ou 3. Peça ao Claude para chamar ctx_execute_file com path: "package-lock.json", language: "javascript" e este código:

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

A ferramenta disponibiliza o arquivo por meio de FILE_CONTENT. O resultado esperado é um objeto JSON pequeno com os três campos solicitados, em vez do arquivo completo. Os valores dependem do projeto; eles contam entradas no arquivo de dependências, não nomes únicos de pacotes.

Depois, execute:

/context-mode:ctx-stats

O comando de estatísticas deve mostrar atividade do Context Mode. Se não houver chamadas, ainda não foi demonstrado que a execução passou pela ferramenta solicitada. As métricas de redução da saída não equivalem a um cálculo da fatura.

Aplique o mesmo padrão aos logs: calcule contagens localmente, selecione erros relevantes e retorne trechos exatos com a localização da fonte. Mantenha a leitura direta para arquivos de código pequenos cujo conteúdo preciso o Claude precisa conhecer.

O Context Mode usa a Elastic License 2.0. Seu isolamento de execução também não é uma sandbox de segurança completa do sistema operacional: as ferramentas de execução podem herdar acesso ao sistema de arquivos. Preserve as permissões e os controles de sandbox que normalmente aplica aos comandos executados pelo agente.

Headroom: comprima a saída elegível por meio de um proxy local

O Headroom atende a fluxos em que você quer manter as ferramentas normais do Claude Code enquanto um proxy reduz a saída elegível. Seu comportamento padrão para programação também considera a estabilidade do cache; ele não promete comprimir todos os arquivos de código ou todas as solicitações.

Este exemplo usa uma chave de API do Anthropic Console, portanto gera cobranças de API separadas da assinatura Claude. Ele pressupõe que uv e Claude Code estejam instalados, que não exista um proxy Headroom em execução e que não haja configurações conflitantes de gateway personalizado ou provedor de nuvem. Gateways corporativos existentes precisam de uma integração adequada à sua configuração.

No Bash, instale a versão fixada do pacote de proxy conforme as instruções de instalação do Headroom:

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

A verificação deve identificar a versão 0.41.0. Leia a chave sem exibi-la no terminal, pressione Enter e inicie o Claude por meio do Headroom:

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Autorize o uso da chave personalizada se o Claude solicitar e confira /status para confirmar a credencial e o modelo ativos. Se você recusou a chave anteriormente, a documentação de autenticação descreve a opção “Use custom API key” em /config.

O comando inicia ou reutiliza um proxy local, abre o Claude por meio dele e registra o servidor MCP de recuperação do Headroom na configuração do Claude Code. --code-memory none dispensa a integração adicional com Serena, mas mantém a recuperação de dados do Headroom disponível. Não acrescente --no-mcp a este exemplo, pois ele remove o mecanismo de recuperação associado aos marcadores de conteúdo comprimido. Essas opções estão definidas na implementação do comando na versão 0.41.0.

As variáveis de ambiente ativam a coleta local de telemetria e desativam seu envio opcional. As solicitações continuam sendo encaminhadas ao provedor de modelo configurado.

Anote o endereço do proxy exibido na inicialização. A porta usual é 8787, mas o comando pode selecionar outra porta disponível. Em um segundo terminal Bash, substitua pela porta efetivamente usada, se necessário:

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

Agora dê ao Claude iniciado dessa forma uma tarefa delimitada sobre um test.log existente e suficientemente grande: listar os testes distintos que falharam e citar a primeira mensagem exata de erro de cada um, sem modificar arquivos. Quando terminar, consulte /stats novamente.

Uma resposta de funcionamento normal confirma que o proxy está em execução. O aumento de requests.total mostra que solicitações concluídas foram contabilizadas; examine requests.failed e requests.rate_limited separadamente. A documentação das métricas explica esses campos. Economia zero em uma entrada curta ou protegida contra compressão não comprova uma falha de roteamento.

Se a autenticação falhar, verifique conflitos em ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL e nas configurações do provedor antes de tentar novamente. Se nenhuma solicitação aparecer, confira a porta exibida e o endereço usado pela sessão iniciada.

O mecanismo de compressão, cache e recuperação do Headroom permite recuperar os originais retidos quando o Claude precisa de detalhes omitidos. Essa recuperação acrescenta trabalho, e o armazenamento tem prazo limitado; se o original não estiver mais disponível, volte ao arquivo de origem ou execute o comando novamente.

Após sair do Claude iniciado pelo Headroom, remova a configuração deste teste no terminal original, a partir do mesmo projeto e com a porta correta:

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

O comando unwrap remove as configurações gerenciadas pelo Headroom e tenta parar o proxy correspondente. A remoção da variável elimina do ambiente a credencial exportada para este teste; confira /status antes de voltar ao seu método habitual de autenticação.

Use modelos mais baratos para subtarefas delimitadas

Use um modelo com preço menor em tarefas cujo resultado seja barato de conferir, como extrair falhas de um log fornecido. Isso altera o preço do trabalho, mas não garante um consumo menor de tokens.

Para estabelecer uma referência usando os recursos nativos, crie .claude/agents/log-summary.md:

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

Reinicie o Claude Code após criar o diretório de agentes e acione o subagente com um log existente:

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

Consulte /tasks durante a execução para verificar o modelo efetivamente usado e compare o trecho retornado com o log original. maxTurns limita os turnos, não dólares ou tokens; atingir esse limite pode deixar o resultado incompleto. Os campos e os detalhes de carregamento estão documentados na referência de subagentes.

haiku é um alias, portanto a configuração do provedor determina o modelo concreto. Reserve decisões de projeto difíceis ou depurações ambíguas para o modelo que as resolve com confiabilidade. Um subagente barato que exige correções repetidas pode aumentar o custo total.

Se você usa o BetterToken com pagamento conforme o consumo, siga sua configuração para Claude Code: a URL base compatível com Anthropic é https://bettertoken.ai, sem /v1. Verifique ANTHROPIC_DEFAULT_HAIKU_MODEL e os demais mapeamentos de aliases. Atribuir o mesmo ID de modelo a todos os aliases significa que selecionar haiku não seleciona outro modelo mais barato. Escolha IDs compatíveis de forma deliberada, compare os preços atuais dos modelos e do cache e confira o modelo registrado e a cobrança. A cobrança da API BetterToken é separada de uma assinatura Claude; trate essa configuração de provedor separadamente do teste do Headroom com acesso direto à Anthropic apresentado acima.

Decida pelo custo da tarefa concluída e pela qualidade do resultado

Mantenha uma ferramenta de compressão apenas se ela melhorar a tarefa concluída depois de considerar o cache, os subagentes, a recuperação de dados e as novas tentativas.

Compare o mesmo estado do repositório, prompt, modelo concreto, nível de esforço e comando de verificação. Registre se cada execução começa com o cache aquecido ou frio, pois misturar essas condições pode distorcer o resultado. Confira tanto a alteração ou resposta final quanto a exatidão das evidências citadas.

Na contabilização da API Anthropic, input_tokens, cache_creation_input_tokens e cache_read_input_tokens são categorias separadas; input_tokens sozinho não representa toda a entrada. Inclua também os tokens de saída. Para tarifas por milhão de tokens, calcule sum(token_count × category_rate / 1,000,000) para todas as solicitações, separando as gravações no cache por duração quando os preços forem diferentes. Acrescente qualquer cobrança obrigatória que não seja baseada em tokens.

A exibição do cache da conversa principal no Claude Code exige a versão 2.1.251 ou posterior e não inclui subagentes. Os contadores de economia do proxy ajudam no diagnóstico, mas a comparação financeira deve usar os registros do provedor responsável pela cobrança.

Se um erro omitido provocar outra investigação, um subagente precisar constantemente de ajuda ou a recuperação dos dados recriar o volume original de contexto, reduza a compressão ou delimite melhor a tarefa. O resultado útil é uma tarefa correta com menos trabalho pago no total.