tokenleak

Visão Geral

Cada resultado que um agente puxa para o contexto é reenviado em cada chamada posterior até a compactação. Assim, uma leitura de log de 6k tokens no início de uma sessão de 60 chamadas é paga cerca de 55 vezes a mais. Essas regras fazem com que o agente permita apenas o que a próxima decisão precisa: localizar antes de ler, computar em vez de ler dados, limitar a saída de comandos, nunca reler, agrupar chamadas independentes. Em mais de 80 execuções A/B no Claude Code (Sonnet 5), eles reduziram o custo em 32% com a mesma taxa de aprovação de 40/40; no Haiku 4.5, eles só ajudam em conjunto com a guarda de leitura do plugin (-20%). O método e os resultados brutos estão no repositório de origem.

Quando Usar Esta Habilidade

• Use em tarefas de codificação que leem arquivos, executam testes, compilações ou instalações, usam git ou pesquisam uma base de código.
• Use quando o usuário quiser economizar tokens, reduzir custos ou permanecer dentro dos limites de uso.
• Use quando uma sessão continua atingindo a compactação porque a saída da ferramenta preenche o contexto.

Regras

1. Localize, depois leia. Não sabe o tamanho de um arquivo? Verifique-o (wc -l) junto com sua primeira pesquisa. Pesquise (grep -n, rg -n, Grep), depois leia apenas a região que você precisa (offset/limite, sed -n 'A,Bp'). Leia um arquivo inteiro apenas se for curto (menos de ~300 linhas) ou se você realmente precisar de tudo.
2. Calcule, não leia. Para perguntas sobre dados (contagens, totais, filtros, pesquisas em arquivos de big data, CSV, JSON, logs), execute um script curto ou um comando único que imprima apenas a resposta. Nunca puxe os dados em si para o contexto.
3. Limite cada comando. Nunca permita que testes, compilações, instalações ou logs sejam transmitidos para o contexto sem limites.
   • Modos silencioso ou apenas falhas: pytest -q -x, vitest run --reporter=dot, go test ./... 2>&1 | grep -v '^ok', cargo test -q, npm ci --silent, make -s.
   • Tarefas longas: L="${TMPDIR:-/tmp}/out.log"; cmd > "$L" 2>&1; echo "exit=$?"; tail -n 40 "$L". Precisa de mais? grep -n -m 20 -E 'error|FAIL|panic' "$L" no log salvo. Nunca execute um trabalho novamente apenas para ver mais de sua saída.
   • Itere no único teste com falha, não na suíte inteira. Execute a suíte completa uma vez no final, silenciosamente.
4. Nunca releia o que você tem. Um arquivo que você leu ou escreveu ainda está no contexto. Releia apenas após a compactação ou após algo mais tê-lo alterado.
5. Agrupe chamadas independentes. Leituras e pesquisas que não dependem umas das outras vão em um turno (chamadas de ferramenta paralelas), e etapas de shell que não precisam de julgamento entre elas vão em um comando (wc -l a b; grep -n x a | head). Cada viagem de ida e volta extra reenvia tudo.
6. Diffs em vez de arquivos. git status -s, git diff --stat e depois git diff -- <path>, git log --oneline -n 15, git show --stat <sha>.
7. Edite, não reescreva. Edições direcionadas apenas. Nunca reescreva um arquivo inteiro para alterar algumas linhas, e nunca cole de volta no chat código que já está no disco.
8. Restrinja pesquisas e buscas. Escopo por caminho e tipo de arquivo, limite os resultados (-m, head_limit, | head -n 30, -l apenas para nomes). Selecione campos de APIs e JSON (--json a,b, jq '.items[] | {id,name}', per_page). Faça uma pergunta precisa a uma busca na web em vez de despejar a página.
9. Delegue exploração ampla. Se uma resposta significa abrir 10+ arquivos e você só precisa da conclusão, passe-a para um subagente se o seu agente tiver um. Apenas o resumo dele entra no seu contexto.
10. Responda de forma concisa. Comece com o resultado. Sem recapitulação passo a passo, sem reafirmar o diff, sem resumo final do que o usuário já pode ver, sem enchimento.

Nunca economize tokens por

• truncar tão drasticamente que você perca o erro real (amplie com grep/sed -n no log salvo em vez disso);
• pular uma leitura que você precisa para editar corretamente, ou adivinhar o conteúdo do arquivo;
• pular a verificação. Execute os testes, silenciosamente.

Limitações

• As economias dependem da carga de trabalho e do modelo: no benchmark, uma tarefa curta de correção de testes ganhou 5%, compilações barulhentas e recursos de vários arquivos 24-51%; modelos pequenos como Haiku 4.5 mal seguem as regras sem a guarda de leitura do plugin.
• O benchmark cobre dois modelos e quatro tarefas pequenas em um repositório sintético, e as execuções variam de 2 a 4x.
• As regras custam cerca de 850 tokens de contexto por si só; em sessões muito curtas, elas podem não se pagar.
• A auditoria de transcrição complementar (tokenleak.py) está no repositório de origem e não está incluída aqui.

Exemplos

Localize antes de ler e passe ao agente apenas o que a próxima decisão precisa:

wc -l app/service.py          # size, alongside the search
rg -n "def handle_" app/      # find the region first
sed -n '120,180p' app/service.py

Limite uma compilação barulhenta e mantenha a falha visível:

…