Uso de tokens no Claude Code: mantenha a saída de ferramentas fora do contexto

Seu agente executou a suíte de testes três vezes, e a conta é maior que a tarefa. A razão raramente é o código que ele escreveu. São os logs de teste: assim que um resultado de ferramenta entra no contexto do Claude Code, toda requisição posterior o carrega de novo. A solução é encolher a saída da ferramenta antes que o modelo a veja. A forma oficial é um hook PreToolUse no Bash; a forma de terceiros é o plugin context-mode. Ambos estão abaixo, com uma estimativa de custo para uma sessão longa em um modelo CheapTokens.

Por que um log é pago várias vezes#

Segundo a página de custos do Claude Code (https://code.claude.com/docs/en/costs, verificada em 23 de outubro de 2026), o Claude Code envia a conversa completa a cada requisição, e cada uso de ferramenta dispara outra requisição que carrega os resultados da ferramenta. O cache de prompt relê o histórico a uma taxa de cache mais barata, mas os tokens ainda estão lá.

Digamos que o agente execute npm test e receba um log de 10.000 linhas. A documentação diz que esse tipo de log pode ter dezenas de milhares de tokens. Suponha 30.000 tokens. Faça o que fizer a seguir, esses 30.000 tokens fazem parte da entrada do passo 11, do passo 12, do passo 13, e assim por diante até você /clear ou compactar. E aí está a pegadinha: o log é útil por um passo, e você paga por ele por trinta.

Correção 1: um hook PreToolUse que filtra a saída de testes#

A mesma página de documentação sugere hooks como pré-processamento: um hook PreToolUse no Bash reescreve comandos de teste (npm test, pytest, go test) para que passem por grep -A 5 -E '(FAIL|ERROR|error:)' | head -100. O agente então vê apenas as falhas mais algumas linhas de contexto, não 10.000 linhas de pontinhos verdes. A documentação diz que isso pode transformar dezenas de milhares de tokens em centenas.

Este é o script daquela página de documentação (verificada em 23 de outubro de 2026). Ele precisa de jq. Crie a pasta com mkdir -p ~/.claude/hooks, salve o script como ~/.claude/hooks/filter-test-output.sh e execute chmod +x nele:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'

if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Depois registre-o em ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }]
      }
    ]
  }
}

Para verificar se funciona, abra /hooks dentro do Claude Code e procure a entrada PreToolUse, ou comece com claude --debug-file ./claude-debug.txt e peça ao agente para executar npm test. Quando o hook tiver reescrito o comando, o arquivo terá uma linha modified tool input keys com o campo command. Se os testes passarem, a saída fica vazia, então o agente recebe um sucesso silencioso; ajuste o padrão se o seu runner imprimir falhas de forma diferente.

Correção 2: context-mode para grandes resultados de ferramentas#

Um hook só cobre comandos que você consegue canalizar. Capturas de tela do Playwright ou uma lista de vinte issues do GitHub vêm de ferramentas MCP. É nisso que o context-mode foca. Segundo seu README (https://github.com/mksglu/context-mode, verificado em 23 de outubro de 2026; não mostra versão nem data), é um servidor MCP e plugin que mantém a saída bruta das ferramentas fora da janela de contexto, armazena o estado da sessão em SQLite e roteia chamadas de ferramentas por hooks. Ele precisa do Claude Code v1.0.33 ou mais recente, e sua licença é a Elastic License 2.0, que não é uma licença de código aberto OSI.

Instale dentro do Claude Code:

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

Reinicie ou execute /reload-plugins, depois verifique com /context-mode:ctx-doctor. A variante somente MCP, claude mcp add context-mode -- npx -y context-mode, adiciona as ferramentas mas não tem roteamento automático.

O projeto relata grandes reduções: 315 KB viram 5,4 KB (98%), uma captura de página de 56 KB vira 299 bytes, 986 KB viram 62 KB. Esses são os números do próprio autor: trate-os como o teto e meça na sua própria sessão com /context antes e depois.

Quanto custa uma sessão longa, com e sem filtragem#

Aqui está a aritmética de uma sessão hipotética. É uma sessão de codificação de 40 passos com contexto base médio de 20.000 tokens, 500 tokens de saída por passo, e três execuções de teste, nos passos 10, 20 e 30. Cada log bruto tem 30.000 tokens; a versão filtrada tem 500.

• Um log do passo 10 é reenviado nas 30 requisições seguintes: 30 × 30.000 = 900.000 tokens. Passo 20: 20 × 30.000 = 600.000. Passo 30: 10 × 30.000 = 300.000. Entrada extra: 900.000 + 600.000 + 300.000 = 1.800.000.
• Filtrado: (30 + 20 + 10) × 500 = 30.000 de entrada extra.
• Entrada base: 40 × 20.000 = 800.000. Saída: 40 × 500 = 20.000.
• Então a sessão é 800.000 + 1.800.000 = 2.600.000 tokens de entrada sem filtro e 800.000 + 30.000 = 830.000 com filtro, com 20.000 tokens de saída de qualquer forma.

O cálculo conta cada token de entrada à taxa cheia. O cache reduz o número real, mas reduz os dois casos pela mesma lógica. Os preços atuais do MiniMax-M2.7 (MiniMaxAI/MiniMax-M2.7, contexto de 180K, até 8.192 tokens de saída), que é o modelo que combina com loops de agente com muita entrada como este, estão no gráfico abaixo.

Premissas: 40 passos, contexto base de 20.000 tokens, 500 tokens de saída por passo, três execuções de teste de 30.000 tokens (filtrado: 500).

No MiniMax-M2.7 a sessão custa $0.133 sem filtro e $0.0445 com filtro, e no total, com entrada e saída contadas juntas, é mais barata que o preço de referência do OpenRouter. Cerca de dois terços da entrada no caso sem filtro são logs que o agente leu uma vez.

O ponto não são os dólares exatos. É que o filtro remove cerca de 1.770.000 de 2.600.000 tokens de entrada (2.600.000 − 830.000 = 1.770.000) em qualquer modelo, e um modelo mais barato reduz o preço de cada token que sobra.

Execute o Claude Code em um modelo CheapTokens#

O Claude Code fala o protocolo Anthropic Messages, e o CheapTokens o suporta. A URL base para o Claude Code não tem /v1. A configuração completa está em como conectar o Claude Code ao CheapTokens. A versão curta, com uma chave de exemplo:

export ANTHROPIC_BASE_URL=https://api.cheaptokens.dev
export ANTHROPIC_AUTH_TOKEN=YOUR_CHEAPTOKENS_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

Use o id completo da documentação; nomes curtos de tabelas de preços não são aceitos pela API. Os preços de todos os modelos estão na página de preços. Para os outros hábitos que reduzem a conta do Claude Code (/clear, /compact, /mcp, subagentes), veja Como tornar o Claude Code mais barato. Para ver como entrada e saída são contadas em uma requisição real, leia Quantos tokens uma requisição de API usa.

Checklist rápido#

1. Execute /context em uma sessão longa e veja o que está ocupando espaço.
2. Adicione o hook do Bash para comandos de teste; confirme a reescrita em /hooks ou no log de depuração.
3. Se ferramentas MCP retornarem capturas grandes, experimente o context-mode e compare /context antes e depois.
4. /clear entre tarefas não relacionadas, para que logs antigos parem de acompanhar.