$ Instalando o RTK no OpenCode

Como este guia foi produzido: Depois de configurar o RTK, pedi ao próprio OpenCode que documentasse a instalação usando o prompt “um guia sobre como o RTK está instalado aqui”. O resultado serviu como base para este texto, que foi revisado e ajustado antes da publicação. Achei interessante preservar essa informação porque ela mostra um uso prático de agentes de IA: não apenas escrever código, mas também documentar o ambiente recém-configurado. E por ele foi resolvido o problema do warning.

O que é o RTK

RTK é um proxy de CLI de alta performance. Ele reescreve comandos como ls, git, grep, read, psql, docker, tsc etc. para produzir saídas mais compactas e otimizadas para LLMs. O plugin do OpenCode intercepta comandos bash e aplica automaticamente rtk rewrite.

Pré-requisitos

• Rust instalado (rustc --version)
• OpenCode instalado
• Node.js instalado (node --version)

1. Instalar o binário RTK

O RTK é distribuído via crates.io (Rust). Instale com:

cargo install rtk

Verifique a instalação:

rtk --version
# Exemplo de saída: rtk 0.42.4

O binário é instalado em ~/.cargo/bin/rtk e precisa estar no PATH. Em meu ambiente, usando o fish shell alterei o arquivo ~/.config/fish/config.fish, incluindo a linha:

fish_add_path ~/.cargo/bin

Requisito de versão

O plugin requer rtk >= 0.23.0. Versões inferiores não funcionarão.

2. Instalar o plugin do OpenCode

Execute o comando de inicialização para OpenCode:

rtk init --opencode

Este comando gera o arquivo do plugin em ~/.config/opencode/plugins/rtk.ts.

Se preferir instalar por projeto (em vez de global):

rtk init --opencode

No diretório do projeto, isso cria o plugin em .opencode/plugins/rtk.ts.

O que o plugin faz

O plugin (rtk.ts) é um delegador leve: toda a lógica de reescrita fica no binário rtk rewrite, que é a fonte única da verdade.

// Para cada comando bash executado pelo OpenCode:
// 1. Intercepta antes da execução
// 2. Chama "rtk rewrite <comando>"
// 3. Se o resultado for diferente, substitui o comando original

3. Instalar o hook global (evitar warning)

Após instalar o plugin, você ainda verá este warning ao executar comandos como rtk gain:

[warn] No hook installed — run `rtk init -g` for automatic token savings

Isso acontece porque o RTK também precisa de um hook no Claude Code (ou agente equivalente) para rastrear automaticamente a economia de tokens em todos os comandos bash — não apenas nos explicitamente prefixados com rtk.

Para resolver, execute:

rtk init -g

Este comando:

• Registra o hook global rtk hook claude
• Cria/atualiza ~/.claude/RTK.md com as instruções do RTK
• Adiciona @RTK.md ao ~/.claude/CLAUDE.md
• Tenta aplicar patch em ~/.claude/settings.json (se o prompt for interativo)

Se o patch do settings.json falhar (modo não-interativo), crie o arquivo manualmente:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "rtk hook claude"
      }]
    }]
  }
}

Reinicie o Claude Code / OpenCode após a configuração.

4. Verificar a instalação

Reinicie o OpenCode. O plugin deve carregar automaticamente.

Para testar, peça ao OpenCode algo como “liste os arquivos do diretório atual”. O comando ls será reescrito para rtk ls, produzindo uma saída compacta e otimizada.

5. Ver economia de tokens

O RTK mantém um histórico de economia de tokens. Consulte com:

rtk gain

Para um gráfico ASCII diário:

rtk gain --graph

Comandos disponíveis no RTK

Lista completa: rtk --help

Estrutura final de arquivos

~/.config/opencode/
├── opencode.json          # Configuração principal
├── opencode.jsonc         # Opcional (comentários)
├── package.json           # Dependências: @opencode-ai/plugin
├── plugins/
│   └── rtk.ts             # Plugin RTK (gerado por "rtk init --opencode")
├── node_modules/
│   └── ...
└── .gitignore

~/.claude/
├── CLAUDE.md              # Referência: @RTK.md
├── RTK.md                 # Instruções do RTK (gerado por "rtk init -g")
└── settings.json          # Hook: "rtk hook claude" no PreToolUse

~/.cargo/bin/
└── rtk                    # Binário RTK (instalado via "cargo install rtk")

Troubleshooting

Plugin não carrega / mensagem “rtk binary not found in PATH”

• Verifique se o RTK está instalado: rtk --version
• Confirme que ~/.cargo/bin está no PATH: echo $PATH | grep -o '.cargo/bin'
• Se não estiver, adicione ao .bashrc ou .zshrc:

  export PATH="$HOME/.cargo/bin:$PATH"
  

RTK não está reescrevendo comandos

• Verifique a versão mínima: rtk --version (precisa ser >= 0.23.0)
• Confirme que o arquivo do plugin existe: ls ~/.config/opencode/plugins/rtk.ts
• Reinicie o OpenCode

Warning: “No hook installed — run rtk init -g”

Este warning aparece ao executar comandos como rtk gain quando apenas o plugin (--opencode) foi instalado, mas o hook global do Claude Code está ausente.

Solução: execute rtk init -g e configure o ~/.claude/settings.json conforme o passo 3 deste guia.

Atualizar o RTK

cargo install rtk --force

Desinstalar

# Remover o plugin
rm ~/.config/opencode/plugins/rtk.ts

# Remover o binário (opcional)
cargo uninstall rtk

Amostra de “contabilidade”

paulo@null ~/g/paulohrpinheiro.xyz (main)> rtk gain --graph
RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════

Total commands:    767
Input tokens:      782.2K
Output tokens:     128.6K
Tokens saved:      654.7K (83.7%)
Total exec time:   18m50s (avg 1.5s)
Efficiency meter: ████████████████████░░░░ 83.7%

By Command
────────────────────────────────────────────────────────────────────────
  #  Command                   Count   Saved    Avg%    Time  Impact    
────────────────────────────────────────────────────────────────────────
 1.  rtk grep                     95  392.6K   49.1%     2ms  ██████████
 2.  rtk go test ./...            15  149.6K   99.6%   533ms  ████░░░░░░
 3.  rtk read                     12   38.2K   53.7%     0ms  █░░░░░░░░░
 4.  rtk ls -la /data/BLA/...      2   28.7K   53.0%    12ms  █░░░░░░░░░
 5.  rtk git commit               58    5.8K   89.3%    10ms  ░░░░░░░░░░
 6.  rtk ls -la public/ima...      1    4.0K   55.7%     6ms  ░░░░░░░░░░
 7.  rtk ls -la /data/BLA/...      2    2.5K   68.4%     4ms  ░░░░░░░░░░
 8.  rtk:toml make e2e             1    2.2K   82.1%   22.0s  ░░░░░░░░░░
 9.  rtk git status               23    2.0K   66.5%     5ms  ░░░░░░░░░░
10.  rtk go test -run Test...      1    2.0K   94.9%   321ms  ░░░░░░░░░░
────────────────────────────────────────────────────────────────────────

Daily Savings (last 30 days)
──────────────────────────────────────────────────────────
06-22 │████████                                 70.2K
06-23 │                                         680
06-24 │                                         269
06-25 │███                                      33.8K
06-26 │█                                        10.5K
06-27 │                                         3.5K
06-28 │                                         2.2K
06-29 │███                                      29.2K
06-30 │█████████████████                        152.5K
07-02 │████████████████████████████████████████ 350.4K
07-03 │                                         1.2K
07-04 │                                         247

Referências

• RTK CLI (crates.io)
• OpenCode Plugin Guide
• fish shell