Todos os artigos

Infra15 min de leitura

Como economizar tokens no Claude Code com rtk e graphify

Como eu gasto menos token no Claude Code com o rtk, que resume a saída do terminal, e o graphify, que responde pelo grafo do código. Com os meus números reais.

Também em English, Español, Français

Todo agente de IA que trabalha no terminal tem o mesmo problema: tudo que o terminal devolve vai parar no contexto do modelo. Teste rodando, log sendo lido, arquivo sendo procurado: cada saída ocupa espaço e custa token.

Uma suíte de testes devolve uma linha de PASS por arquivo, aviso de framework e log que ninguém vai ler. Um git log traz hash completo, e-mail e data de cada commit. Uma pergunta como "onde isso é usado?" vira dez arquivos abertos, um atrás do outro.

Há uns meses eu instalei duas ferramentas pra cortar esse desperdício: o rtk, que resume a saída dos comandos antes de ela chegar no modelo, e o graphify, que transforma o código num grafo pra eu perguntar pro grafo antes de abrir arquivo. As duas estão em alta: em 16/11/2026, o rtk passava de 86 mil estrelas no GitHub e o graphify chegava perto de 149 mil, num repositório criado em abril.

Esse post é como eu uso as duas, com os números reais da minha máquina, e onde elas não ajudam.

TL;DR#

  • O rtk é um binário em Rust que entra como hook no Claude Code: antes de cada comando no terminal, ele troca git log por rtk git log e entrega pro modelo só o que importa.
  • Na minha máquina, desde agosto: 148 mil comandos e 228,1 milhões de tokens economizados, segundo o rtk gain. Mas, quando eu medi na mão, descobri que o número do teste está inflado.
  • O graphify lê o código com tree-sitter, sem LLM e sem mandar nada pra fora, e monta um grafo de funções, imports e chamadas. Aí graphify explain "articlesPath()" responde em 15 linhas o que levaria dez arquivos abertos.
  • Os dois têm limites: o hook do rtk só pega comandos de terminal (as ferramentas nativas Read e Grep passam direto), um filtro pode falhar, e o grafo deixa passar referência.
  • Meça antes de acreditar. Numa suíte de testes de verdade, o rtk gain registrou 99,6% de economia. Comparando com o jest puro, foram 73%.

Pra onde vai o token#

Tudo que uma ferramenta devolve entra no contexto da conversa: a saída de um comando, o conteúdo de um arquivo, o resultado de uma busca. E fica lá, sendo reenviado a cada turno, até a conversa acabar ou ser resumida.

Na prática, eu vejo dois tipos de desperdício:

  1. Saída de comando cheia de ruído. Teste que passou, barra de progresso, hash de 40 caracteres, aviso repetido. O modelo precisa da falha, não de cem linhas de PASS.
  2. Abrir arquivo pra descobrir onde algo está. Pra responder "quem chama essa função?", o agente faz um grep e depois abre arquivo por arquivo pra entender cada uso.

O rtk ataca o primeiro. O graphify ataca o segundo.

O mesmo git log -10, sem e com rtk. O hook troca o comando antes de ele rodar

rtk: o terminal resumido#

O rtk (Rust Token Killer) é um binário único em Rust, com licença Apache-2.0. Ele tem filtros pra mais de 100 comandos: git, gh, npm, jest, vitest, tsc, eslint, pytest, cargo, docker, ls, grep e por aí vai. Cada filtro sabe o que importa naquela saída. No teste, só as falhas com a asserção. No git log, uma linha por commit. No grep, os resultados agrupados por arquivo.

Como ele entra no Claude Code#

A instalação é brew install rtk e depois rtk init -g, que registra um hook no ~/.claude/settings.json. O meu ficou assim:

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "rtk hook claude" }]
      }
    ]
  }
}

Um hook PreToolUse roda antes de cada ferramenta. Esse só olha pro Bash: o Claude Code avisa que vai rodar um comando, o rtk devolve o comando reescrito, e é essa versão que roda. Dá pra ver a troca com rtk rewrite. Essas são saídas reais:

O agente pedeO que roda
git log -10rtk git log -10
npx jestrtk jest
cat src/root.tsxrtk read src/root.tsx
cd src && git statuscd src && rtk git status
git log | head -5rtk git log | head -5
python3 build.py(nada: sem filtro, roda igual)

Comando composto também funciona: ele reescreve cada pedaço que conhece. E o que ele não conhece passa direto.

Antes e depois: um git log de verdade#

Rodei git log -10 no repositório desse blog, sem e com o rtk. Sem, cada commit vem assim:

commit 0785527405c98135c27f735d944f7a560279cb31
Author: Yasmin Lopes <...>
Date:   Mon Nov 16 19:12:27 2026 -0300
 
    feat(artigos): publica o post do rscovery

Com o rtk, cada commit vira uma linha, com hash curto, data relativa e autor. A mensagem longa de um commit aparece cortada, com um aviso de quantas linhas sumiram:

0785527 feat(artigos): publica o post do rscovery (4 minutes ago) <Yasmin Lopes>
87c3543 feat(artigos): botao de copiar nos blocos de codigo (5 minutes ago) <Yasmin Lopes>
5abcd1b feat(artigos): rascunho do post arquivo apagado nao some (rscovery) (10 minutes ago) <Yasmin Lopes>
  Post sobre por que da pra recuperar arquivo apagado de HD, SSD e pendrive,
  como o rscovery acha esses dados por assinatura e como apagar de verdade
  antes de vender. Quatro ilustracoes, animacao da varredura, capa #20 e
  [+1 lines omitted]

Foram 2.244 caracteres sem e 1.243 com: 45% a menos. Num git log isso é pouco. A diferença grande aparece no teste.

Antes e depois: a suíte de testes do app#

Aqui eu esperava o número bonito. Rodei os 103 arquivos de teste do maior módulo do backend de um projeto meu, sem e com o rtk:

CaracteresTokens (estimados)
npx jest src/modules/game, sem rtk8.6032,1 mil
o mesmo comando, com rtk2.288570

Uns 73% a menos. Bom, mas longe dos 94,5% que o rtk gain mostra pro jest. E, quando eu fui olhar o histórico do rtk (ele guarda tudo num SQLite na sua máquina), essa mesma execução estava registrada assim:

original_cmd  rtk_cmd       input_tokens  output_tokens  savings_pct
jest run      rtk jest run  142508        539            99.6

142 mil tokens de entrada, contra os 2,1 mil que o jest puro devolveu. A diferença é que o rtk não roda o jest do jeito normal: ele pede o relatório em JSON, que é muito maior (nesse caso, 558.065 caracteres), filtra esse JSON e mede a economia contra ele. Ou seja, a base da conta é uma saída que você nunca veria sem o rtk.

E nem o filtro funcionou dessa vez. O que chegou pro modelo foi isso, seguido do começo do JSON cortado em 2.000 caracteres:

[RTK:PASSTHROUGH] jest parser: All parsing tiers failed
[RTK:PASSTHROUGH] Output truncated (558065 chars → 2000 chars)
[full output: ~/Library/Application Support/rtk/tee/1794868468_jest_run.log]

O resumo vem no começo do JSON (passou tudo, 1.419 testes), então o modelo soube o resultado. Mas, se um teste tivesse falhado no meio dos 103 arquivos, o motivo podia ficar depois do corte, e o agente teria que abrir o log completo.

Mais um dado: a suíte inteira do app, com 3.088 testes passando, devolve só 1.926 caracteres no jest puro. Quando tudo passa, o jest já é curto. O rtk faz diferença de verdade quando a saída tem ruído: console.log no meio do teste, aviso de framework, falha com stack trace.

Os meus números#

Com isso em mente, olha o meu rtk gain em 16/11/2026:

RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════
 
Total commands:    148053
Input tokens:      405.1M
Output tokens:     177.1M
Tokens saved:      228.1M (56.3%)
Total exec time:   4661m25s (avg 1.9s)
Efficiency meter: ██████████████░░░░░░░░░░ 56.3%

"Input" é o tamanho da saída original dos comandos. "Output" é o que o modelo leu depois do filtro. Em três meses e meio, os meus agentes rodaram 148 mil comandos no terminal e, pela conta dele, o rtk deixou de mandar 228,1 milhões de tokens pro contexto.

Agora, o que ele diz por comando:

O que o rtk gain registrou até 16/11/2026. A barra do jest é medida contra o JSON que o próprio rtk pede
  • O jest é 61% do total, mas é a barra menos confiável. São 139,9 milhões de tokens em 2.422 execuções, contados contra o JSON, como eu mostrei acima. A economia real é menor, e eu não tenho como recalcular o histórico.
  • Busca economiza pouco por vez, mas roda muito. O grep rodou 45 mil vezes com média de 24,9%.
  • Ler arquivo quase não muda. O cat virou rtk read 24 mil vezes, com média de 4,7%. Faz sentido: num arquivo de código, quase toda linha importa.
  • Varia muito com o trabalho do mês. Em setembro, mês de muito teste, a economia registrada foi de 83,7%. Em outubro, de 29,7%.

Uma ressalva que o próprio README faz: o rtk estima tokens como bytes divididos por 4, e ele reduz a saída dos comandos, que é só uma parte do que você manda pro modelo. Cortar 90% da saída não é cortar 90% da conta.

graphify: perguntar pro grafo antes de abrir arquivo#

O graphify lê uma pasta e monta um grafo de conhecimento: cada função, tipo, arquivo e import vira um nó, e cada chamada ou import vira uma aresta. Com o grafo pronto, o agente pergunta pra ele em vez de sair abrindo arquivo.

O que eu gosto nele:

  • Código é lido localmente com tree-sitter, sem LLM e sem mandar nada pra fora. Documentos, PDFs e imagens precisam de um modelo pra extrair o sentido, mas código não.
  • Cada aresta diz de onde veio: EXTRACTED quando está escrito no código, INFERRED quando o graphify deduziu, AMBIGUOUS quando ele não tem certeza.
  • Não é busca por embedding. É um grafo de verdade, que dá pra percorrer: vizinhos de um nó, caminho entre dois nós, comunidades de arquivos que conversam entre si.

Montando o grafo desse blog#

Instalei com pipx install graphifyy (com dois "y" mesmo) e rodei no repositório desse blog:

$ graphify update .
Re-extracting code files in . (no LLM needed)...
  AST extraction: 170/170 files (100%) [10 workers]
[graphify watch] Rebuilt: 1049 nodes, 1410 edges, 83 communities
[graphify watch] graph.json, graph.html and GRAPH_REPORT.md updated in graphify-out

Levou 1,5 segundo. Na pasta graphify-out/ ficam o graph.json (o grafo inteiro), um graph.html pra navegar clicando, e o GRAPH_REPORT.md, um resumo com os nós mais conectados:

## God Nodes (most connected - your core abstractions)
1. `cn()` - 31 edges
2. `useI18n()` - 23 edges
3. `compilerOptions` - 20 edges
4. `compilerOptions` - 18 edges
5. `articlesPath()` - 15 edges
6. `ArticleMeta` - 14 edges
7. `absoluteUrl()` - 12 edges

Bate com o que eu sei do projeto: cn() junta classes do Tailwind em todo componente, useI18n() traduz o site nos quatro idiomas e articlesPath() monta o endereço da lista de artigos em cada idioma.

Um exemplo real: quem usa articlesPath()?#

Essa é a pergunta típica antes de mexer numa função. Sem o grafo, o caminho do agente é um grep (23 linhas em 10 arquivos) e depois abrir esses arquivos pra entender cada uso: 30.622 caracteres, uns 7,6 mil tokens.

Com o grafo:

$ graphify explain "articlesPath()"
Node: articlesPath()
  ID:        articles_paths_articlespath
  Source:    src/features/articles/paths.ts L18
  Type:      code
  Community: 0
  Degree:    15
 
Connections (15):
  <-- paths.ts [contains] [EXTRACTED]
  <-- static-build.ts [imports] [EXTRACTED]
  <-- article-page.tsx [imports] [EXTRACTED]
  <-- site-pages.ts [imports] [EXTRACTED]
  <-- article-seo.ts [imports] [EXTRACTED]
  <-- articles-page.tsx [imports] [EXTRACTED]
  <-- articlesListMeta() [calls] [EXTRACTED]
  <-- articleMeta() [calls] [EXTRACTED]
  <-- renderRss() [calls] [EXTRACTED]
  <-- ArticlesPage() [calls] [EXTRACTED]
  <-- trail-filter.tsx [imports] [EXTRACTED]
  <-- ArticlePage() [calls] [EXTRACTED]
  <-- TrailFilter() [calls] [EXTRACTED]
  <-- routes.ts [imports] [EXTRACTED]
  <-- navHref() [calls] [INFERRED]

São 798 caracteres, uns 200 tokens. E já diz mais que o grep: quais funções chamam (o RSS, o SEO, a página), não só quais arquivos citam o nome. Daí o agente abre só o arquivo que interessa.

A mesma pergunta, respondida abrindo arquivos ou consultando o grafo

A regra que eu deixei pro Claude#

O graphify tem um graphify claude install, que instala um hook pra empurrar o assistente pro grafo. Eu preferi escrever a regra no meu ~/.claude/CLAUDE.md, que vale pra todo projeto. Ela é em português no original; aqui vai traduzida:

~/.claude/CLAUDE.md
# Token saving (default in EVERY session, EVERY project)
 
2. **graphify (graph-first)**: before opening a file to answer "where/how/what connects",
   use the graph. At the start of every task on a codebase, silently:
   - `which graphify`: if installed AND `graphify-out/graph.json` exists in the project,
     navigate the graph (`GRAPH_REPORT.md`, `graphify query/path/explain`) BEFORE Read.
   - Installed but no graph, in a code project I'll change: run
     `graphify update .` once (AST-only, cheap) and then use the graph.
   - Not installed: carry on with Grep/Read silently (don't warn, don't block).
   - Never read more than 3 source files per question; if you need to, the question is
     too broad, ask me to narrow it. Trust EXTRACTED/INFERRED edges; only verify AMBIGUOUS.

E um comando /econ que reativa as duas coisas numa sessão que começou sem elas.

O grafo também erra#

Quando conferi a resposta acima com o grep, achei três coisas que você precisa saber:

  • Ele deixou passar um arquivo. O src/routes/articles.tsx chama articlesPath() dentro de um objeto (handle.alternates), e essa chamada não virou aresta. O grafo achou 9 dos 10 arquivos. Pra renomear uma função, eu ainda confirmo com grep.
  • INFERRED às vezes é só nome parecido. Na seção de "conexões surpreendentes" do relatório, ele ligou um describe() do plugin de imagens a um resolve() do servidor de preview. Não tem relação nenhuma: é dedução por nome. A minha regra confia em INFERRED, e esse caso me fez rever isso.
  • Pergunta em linguagem natural funciona mal no código. O graphify query faz uma busca por palavras e anda pelo grafo a partir delas. Perguntei como a capa de cada idioma é escolhida e ele começou pelos títulos de um artigo em inglês (o grafo também indexa os .mdx). Pelo nome do símbolo, como "ArticleMeta cover", ele acerta.

E o grafo envelhece: o relatório diz de qual commit ele saiu. Mexeu no código, rode graphify update . de novo.

Limites e quando não usar#

O hook do rtk só pega o terminal. As ferramentas nativas do Claude Code, como Read, Grep e Glob, não passam pelo Bash, então chegam inteiras. O README do rtk diz que dá pra comprimir essas também com um pipeline, que eu não uso. Por isso a minha regra pede: pra saída grande (diff, log de teste, build), prefira rodar pelo terminal.

O hook só vê o que passa pelo Bash

Um filtro pode quebrar o comando. Isso aconteceu enquanto eu escrevia esse post. Num app meu, o npx jest virou rtk jest, e o rtk decidiu rodar o jest pelo pnpm, porque o projeto tem um pnpm-lock.yaml esquecido ao lado do package-lock.json. O pnpm do corepack estava quebrado na minha máquina. Resultado: o teste nem rodou, o comando saiu com erro e o modelo recebeu só isso:

[RTK:PASSTHROUGH] jest parser: All parsing tiers failed
 
[full output: ~/Library/Application Support/rtk/tee/1794867612_jest_run.log]

Sem o rtk, os mesmos testes passavam. E o rtk gain ainda registrou essa execução como 90% de economia. Um agente que lê "falhou" sem ver o motivo pode sair consertando o que não está quebrado. A pista estava no log completo, que o rtk salva e aponta.

Quando você precisa da saída inteira, peça. Num erro que o filtro cortou demais, rode o comando sem filtro: na versão 0.43 que eu uso é rtk proxy git log, e no README atual o nome é rtk bypass. Continua contando no rtk gain.

Não use o grafo pra projeto pequeno ou pergunta sobre um arquivo só. Se você já sabe qual arquivo abrir, abra. O próprio relatório mede o projeto antes e avisa quando o grafo não compensa.

Cuidado com o que sai da sua máquina.

  • O rtk tem telemetria opcional. Confira com rtk telemetry status (a minha está desligada).
  • O graphify não tem telemetria, mas guarda cada pergunta em ~/.cache/graphify-queries.log. E se você pedir pra ele ler documentos, PDFs ou imagens, esse conteúdo vai pro modelo que você configurar.
  • A pasta graphify-out/ tem o mapa do seu código. Eu deixo fora do git.

Confira se é o rtk certo. Existe outro projeto chamado rtk no crates.io. Se rtk gain não mostrar o painel de economia, você instalou o outro.

Como montar o seu#

brew install rtk
rtk init -g
pipx install graphifyy
graphify update .

Reinicie o Claude Code depois do rtk init -g. Depois de uns dias, rode rtk gain pra ver o que mudou de verdade no seu caso.

O que aprendi#

O contador mede contra a base dele. O rtk gain disse 99,6% numa suíte em que o ganho real, comparado com o jest puro, foi de 73%. Ainda é bom. Mas, se eu fosse decidir pelo painel, ia achar que economizo bem mais do que economizo. Pra saber de verdade, rode o mesmo comando com rtk proxy e compare.

A economia aparece onde tem ruído. Teste com log, lint com centenas de avisos, ps aux, git log. Teste passando sem log já é curto, e ler arquivo quase não muda nada.

Toda camada nova é um lugar novo pra quebrar. O hook é invisível de propósito, e é por isso que, quando ele erra, demora pra você perceber. Hoje, quando um teste falha de um jeito estranho, a primeira coisa que eu olho é se o comando rodou mesmo.

Grafo é mapa, não verdade. Ele responde rápido e barato o "quem usa isso?", e acerta quase sempre. Pra mudança que não pode deixar nada pra trás, como renomear, eu confirmo no texto do código.

Referências#

Atualizado em

  • Infra
  • claude-code
  • ia
  • tokens
  • rtk
  • graphify
  • rust

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.