Pular para conteúdo

Ferramentas de token do dev

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-04

Duas ferramentas recomendadas da casa operacionalizam a disciplina de tokens do agente: o rtk corta o que entra no contexto (input) e o caveman corta o que o agente escreve (output). O princípio (input frugal + output terso + carve-out) vale sem elas; as ferramentas são os atalhos que o operacionalizam.

Escopo: são de máquina de dev (~/.claude/~/.config), instaladas uma vez — não são arquivos de repo (a exceção é o hook do caveman, versionável per-repo).

rtk — corta o input

O rtk é um proxy que resume a saída de CLI antes de ela entrar no contexto do agente: economiza muitos tokens em operações de dev sem perder substância.

Instalar

Repo canônico (instruções completas e por plataforma): rtk-ai/rtk. Resumo:

  • macOS / Linux (rec.): brew install rtk — ou curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh.
  • Cargo (qualquer plataforma com Rust): cargo install --git https://github.com/rtk-ai/rtk.
  • Windows: baixe rtk-x86_64-pc-windows-msvc.zip dos releases, ponha rtk.exe no PATH e rode do terminal (não dê duplo-clique).

Verifique (cuidado com a colisão de nome — reachingforthejack/rtk é outro tool, "Rust Type Kit"):

rtk --version   # deve responder rtk 0.40+
rtk gain         # analítico de economia — se falhar, é o rtk errado

Habilitar (hook transparente)

O rtk reescreve os comandos Bash do Claude Code de forma transparente, via hook PreToolUse:

rtk init -g       # instala o hook no config global do Claude Code
                  # (--gemini / --codex / --agent cursor p/ outros agentes; --auto-patch p/ CI)

Reinicie o Claude Code depois. Confira que o hook está no ~/.claude/settings.json (PreToolUse → "rtk hook claude"). Sem o hook ativo, a economia é ~0 — já houve sessão com cobertura real de 6,5% por hook não instalado. Dry-run de como um comando seria reescrito: rtk hook check './gradlew check'.

Configurar como padrão

rtk config cria/mostra ~/.config/rtk/config.toml. O padrão recomendado da casa já traz os diretórios gerados por stack em ignore_dirs (o default cru do rtk foca em target/Maven):

[filters]
ignore_dirs = [".git", "node_modules", "target", "build", ".gradle", ".dart_tool",
               "__pycache__", ".venv", "vendor"]

[tee]
enabled = true
mode = "failures"   # em falha, salva o log cheio num tee-file; leia-o só se precisar

Regras por stack — o pulo do gato

O hook só corta tokens no comando que ele vê. Furam o hook (e perdem a economia): | pipe, &&/;, $(...)/subshell e prefixo de env (JAVA_HOME=… ./gradlew). Por isso:

Stack Regra
Java / Gradle ./gradlew check bare, sem pipe (o rtk resume + faz tee em falha; leia o tee-log só se preciso). sdk default java 25 pra dispensar o prefixo JAVA_HOME= (que fura o hook); JDK ≠ default → JAVA_HOME=<path> rtk gradlew … explícito. Nunca | tail/| grep.
Flutter o rtk não cobre flutter → não terceirize: use flutter test -r failures-only (reporter frugal na fonte — ver ci-testes).
git (todas) git diff/git status bare (diff ~87-90%); evite --porcelain (o rtk colapsa pra "ok" e some com a lista).
arquivos (todas) Bash executa (build, git, scripts), não lê: Read/Grep/Glob nativos em vez de cat/sed/grep -rn/ls -la/find crus (rtk find nem aceita -exec/-not).

Comando sem handler nativo (ex. mkdocs, python3, node, os gates de validação): não espere um handler nem canalize pra | grep — envolva com um wrapper genérico: rtk err <cmd> (roda e mostra só erros/avisos; 1 linha em sucesso) ou rtk summary <cmd> (resumo heurístico). Ex.: rtk err mkdocs build --strict, rtk err python3 scripts/valida-frontmatter.py docs/. Cobre a maior parte do que o rtk discover marca como "unhandled" — ajuste de uso nosso, sem tocar o tool.

Medir: rtk gain (economia acumulada) e rtk discover (oportunidades perdidas na sessão — foi ele que flagrou 4,9% de aproveitamento numa sessão java-micronaut, ~82K tokens vazando por prefixo+pipe justo no maior ganho, o Gradle).

Reconcilia a norma frugal: as flags de reporter (--quiet, -r failures-only, --console=plain) ficam na fonte e são compatíveis com o rtk — o que cede ao bare+rtk é o pós-processamento com pipe (| tail/| grep), que o rtk substitui resumindo + tee.

caveman — corta o output

O caveman injeta uma regra de estilo terso que corta ~65–75% dos tokens de output do agente com a exatidão técnica intacta. É regra de estilo, não dependência: o mecanismo recomendado (o hook abaixo) funciona sem o plugin. O princípio, os níveis e o carve-out verbatim (o que nunca comprimir — mensagem de commit, linha §6, código, tabelas de dado, .ia/) estão em Trabalho com agentes de IA.

Habilitar — hook SessionStart (recomendado, sem plugin)

Versionável, compartilhado, contido: mesmo padrão do checa-constituicao.sh. Crie .claude/caveman.sh:

#!/usr/bin/env bash
# Injeta a regra de estilo terso da casa em toda sessão de agente.
cat <<'EOF'
Responda terso: dropa artigo, filler, gentileza, hedging. Fragmentos OK. Termo técnico exato.
Padrão: [coisa] [ação] [razão]. [próximo passo].
VERBATIM (nunca comprimir): código, nomes de API/CLI, tipos de commit, strings de erro, a
mensagem de commit pronta e a linha §6 (REGRA Nº 2), tabelas de dado, specs/planos .ia/.
Desligar na sessão: "stop caveman".
EOF

Entrada no array SessionStart do .claude/settings.json (soma às que já existam, ex. a do checa-constituicao.sh):

{ "hooks": { "SessionStart": [ { "hooks": [
  { "type": "command", "command": "bash .claude/caveman.sh" }
] } ] } }

Instalar o plugin (opcional — atalho /caveman)

Repo canônico: juliusbrussee/caveman. Install:

  • Claude Code (plugin): claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman — fica ativo por default desde a 1ª mensagem (modo full), sem comando.
  • Universal (qualquer agente, requer Node ≥18): macOS/Linux/WSL/Git Bash → curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash; Windows PowerShell → irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex.

O plugin adiciona o toggle /caveman lite|full|ultra. Não use caveman-init para Claude Code: ele só grava regra para Cursor/Windsurf/Cline/Copilot/AGENTS.md e ignora o Claude Code. Pontual (sem persistir): diga caveman mode; desligue com normal mode (ou stop caveman).

Configurar — intensidade

Níveis (full recomendado · lite quando a revisão pede fluidez · ultra a evitar no fluxo X-Adm) descritos em agentes § Estilo terso. Com o plugin, o modo default resolve nesta ordem: env CAVEMAN_DEFAULT_MODE → .caveman.json do repo → config do usuário → full. Modo ativo = flag ~/.claude/.caveman-active (some quando off).

Higiene do .claude/settings.json — versionado enxuto, pessoal fora

O .claude/settings.json é versionado e carregado por todo mundo que abre o repo. Se ele acumular grants hiper-específicos, o harness anexa um a cada sessão e o arquivo suja o git continuamente — e o pior vem depois: força git commit --amend repetido, que troca o hash do commit sob a tag e solta a tag da release (ela passa a apontar para um commit que não existe mais). A divisão da casa evita o ciclo:

  • Versionado (.claude/settings.json) — só o compartilhado: hooks (ex. SessionStart do caveman/checa-constituicao.sh), additionalDirectories (caminho relativo, portável) e um allow-list por ferramenta — wildcard no nome do comando, não no prefixo de argumento — que absorve os comandos comuns, para o harness quase nunca ter grant novo a anexar:
"allow": [
  "Bash(git *)", "Bash(rtk *)", "Bash(mkdocs *)", "Bash(docker *)",
  "Bash(python *)", "Bash(python3 *)", "Bash(py *)", "Bash(node *)", "Bash(npm *)",
  "Bash(curl * https://docs.xadm.biz/*)"
]

Por ferramenta e não por prefixo de argumento de propósito: o allow-list por prefixo exato (python3 scripts/*, mkdocs build *) é quebradiço — cada variação de forma (interpretador python/py, npm install vs npm i, flag antes do subcomando, arg fora do prefixo previsto) volta a pedir prompt e trava a /xadm-release no meio. O interpretador Python varia por SO — python3 no Linux, python/py no Windows — e o namespace da ferramenta idem (Bash(...) no Git Bash/WSL, PowerShell(...) no Windows nativo: regra de um NÃO casa o outro), então liste as três formas em ambos os namespaces (PowerShell(python *), PowerShell(python3 *), PowerShell(py *)). O curl fica escopado (docs.xadm.biz) de propósito — não alargue download genérico. Composto continua veneno (pipe, $(...), multi-linha): wildcard cura variação de forma, não comando opaco.

  • Pessoal (.claude/settings.local.json) — grants de máquina, caminhos absolutos do home, experimentos descartáveis. Fica no .gitignore — linha exata .claude/settings.local.json (cuidado com o typo .settings.local.json, ponto a mais que casa com nada e deixa o arquivo pessoal vazar para o git em outra máquina que não tenha o ignore global).

Proibido acumular no versionado entry hiper-específico e descartável — comando exato com hash, caminho absoluto de scratchpad, cp … && … ; … de um passo pontual. É justo isso que recomeça o ciclo de amend e solta a tag. Comando novo aparecendo com frequência: alargue o padrão (Bash(rtk *)), não cole a variante exata.

Bash(git *) libera git commit/push/reset sem prompt — é intencional (zero churn). A REGRA Nº 2 segue valendo: ela é comportamental (o agente não commita sozinho); o grant só tira o prompt quando o comando é legítimo (/xadm-release, ou a seu pedido).