RTK CLI: come tagliare l'80% dei token sugli AI agent

Quando un AI agent come Claude Code o Codex lancia git status, cargo test o docker ps, il context window si riempie di output rumoroso: enumerazioni di oggetti, stack trace completi, log duplicati, tabelle ASCII. RTK (Rust Token Killer) è un proxy CLI scritto in Rust che intercetta quei comandi, li filtra e ne restituisce solo l'informazione essenziale — il resto finisce su disco, recuperabile quando serve.

Il risultato, misurato dagli autori del progetto su un tipico progetto TypeScript/Rust di medie dimensioni, è un taglio tra il 60% e il 92% dei token consumati per i comandi più frequenti. In una sessione di sviluppo reale parliamo di decine di migliaia di token risparmiati al giorno, e di context window che resta utilizzabile molto più a lungo.

Che cosa fa RTK, in pratica

RTK non è un wrapper generico: è una collezione di filtri specifici per ognuno dei comandi più usati in un workflow di sviluppo. Per ogni comando applica una o più di queste strategie:

• Smart filtering — rimuove commenti, whitespace, boilerplate, header ripetitivi (per esempio le righe Enumerating objects di Git).
• Grouping — aggrega elementi simili (file per directory, errori per tipo, log duplicati con contatore).
• Truncation — mantiene il contesto rilevante e taglia la ridondanza, conservando però l'output completo su file.
• Deduplication — comprime le righe di log ripetute con un contatore (×142).

Tecnicamente RTK è un singolo binario Rust statico, zero dipendenze di runtime, overhead inferiore ai 10 millisecondi per chiamata. Supporta oltre 100 comandi divisi per categoria:

• File system: rtk ls, rtk read, rtk grep, rtk find, rtk smart.
• Git: rtk git status, rtk git diff, rtk git log, rtk git commit, rtk git push.
• GitHub CLI: rtk gh pr list, rtk gh pr view, rtk gh issue list.
• Test runner: rtk jest, rtk vitest, rtk pytest, rtk cargo test, rtk go test, rtk rspec.
• Linter e build: rtk lint, rtk tsc, rtk next build, rtk cargo build, rtk ruff check.
• Container e cloud: rtk docker ps, rtk kubectl logs, rtk aws ec2 describe-instances.
• Utility: rtk gain (statistiche risparmio), rtk discover, rtk proxy, rtk err.

Quanto si risparmia davvero

I numeri riportati nel README ufficiale derivano da un progetto reale di medie dimensioni (TypeScript + Rust). Ecco i comandi più usati con il relativo taglio di token:

Il risparmio aggregato è circa l'80% del context speso in interazioni con la shell. Su un mese di lavoro intensivo parliamo di milioni di token, e — con i prezzi correnti delle API — di dollari risparmiati in modo trasparente, senza cambiare una riga di codice.

Installazione: 30 secondi

RTK si installa come un singolo binario in ~/.local/bin. Tre opzioni equivalenti, scegli quella più adatta al tuo sistema.

La via più rapida su macOS è Homebrew:

# installa RTK via Homebrew
brew install rtk

Su Linux o WSL funziona meglio lo script ufficiale, che scarica direttamente dal ramo master:

# installa RTK da release ufficiale
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Se preferisci compilare dai sorgenti, basta Cargo:

# build locale dal repository
cargo install --git https://github.com/rtk-ai/rtk

Al termine verifica che il binario sia raggiungibile e funzioni:

# verifica installazione
rtk --version
rtk gain

Se rtk non è in PATH, aggiungi questa riga al tuo ~/.bashrc o ~/.zshrc:

# rendi rtk disponibile in ogni shell
export PATH="$HOME/.local/bin:$PATH"

Un avvertimento importante: esiste un altro crate pubblicato su crates.io con lo stesso nome (Rust Type Kit). Se rtk gain non produce statistiche di risparmio token, hai preso il pacchetto sbagliato. In quel caso disinstallalo e usa cargo install --git come mostrato sopra.

Integrazione con Claude Code e gli altri agent

Qui sta la parte più elegante: RTK non richiede di riscrivere le istruzioni di sistema o di cambiare il prompt del tuo agent. Espone un comando init che installa un hook trasparente sulle chiamate Bash. Quando Claude Code esegue git status, l'hook lo riscrive in rtk git status prima di passarlo alla shell.

Per Claude Code, Copilot, Gemini CLI, Codex e gli altri agent principali basta un comando:

# inizializza hook globale per i principali agent
rtk init -g
rtk init -g --gemini
rtk init -g --codex
rtk init -g --agent cursor
rtk init -g --agent windsurf

Per agent con plugin dedicato come Cline, Kilo Code, Antigravity e Hermes ci sono flag specifici:

# init per agent con regole project-scoped
rtk init --agent cline
rtk init --agent kilocode
rtk init --agent antigravity
rtk init --agent hermes

Supporta complessivamente 14 tra AI agent e IDE — la matrice completa è nel README del progetto. Per OpenClaw esiste un plugin dedicato installabile con openclaw plugins install ./openclaw dalla root del repository.

Limite importante: l'hook intercetta solo le chiamate al tool Bash. I tool nativi di Claude Code come Read, Grep e Glob non passano dall'hook, quindi non vengono riscritti automaticamente. Per ottenere l'output compatto in quei casi devi invocare direttamente rtk read, rtk grep o rtk find.

Il flusso, visto da vicino

Quando l'hook è attivo, ogni comando shell segue questo percorso:

1. L'agent genera una chiamata Bash (es. git status).
2. L'hook PreToolUse riscrive il comando in rtk git status.
3. La shell esegue il comando, che produce output raw (~2.000 token).
4. RTK filtra l'output in tempo reale, mantenendo solo l'essenziale (~200 token).
5. L'agent riceve l'output compatto e prosegue.

L'overhead per il filtro è inferiore ai 10 ms — impercettibile per l'utente, trasparente per l'agent. In caso di errore, RTK salva automaticamente l'output completo non filtrato in ~/.local/share/rtk/tee/<timestamp>_<cmd>.log, così l'LLM può leggere i dettagli senza rieseguire il comando.

Esempi pratici, prima e dopo

Una ls -la tipica produce 45 righe e circa 800 token. Con rtk ls la stessa directory diventa 12 righe compatte:

# output RTK di una directory di progetto
+-- src/ (8 files)
|   +-- main.rs
|   +-- lib.rs
+-- Cargo.toml
+-- README.md

Un git push standard restituisce 15 righe e ~200 token (Enumerating, Counting, Delta compression…). Con rtk git push:

# output compresso di un push Git
ok main

Una suite di test cargo test in fallimento può produrre 200+ righe. Con rtk test cargo test ottieni solo i test rossi:

# riepilogo failure-only
FAILED: 2/15 tests
test utils::test_parse ... ok
test_edge_case: assertion failed
test utils::test_format ... ok
test_overflow: panic at utils.rs:18

Per il wrapping generico su qualsiasi comando, ci sono rtk err <cmd> (filtra solo gli errori) e rtk test <cmd> (filtra solo i fallimenti). Se invece vuoi mantenere l'output raw ma tracciare il risparmio, usa rtk proxy.

Misurare il risparmio con rtk gain

Una volta che l'hook è attivo, ogni chiamata viene conteggiata. Il comando rtk gain mostra le statistiche aggregate:

# statistiche aggregate di risparmio
rtk gain

# grafico ASCII degli ultimi 30 giorni
rtk gain --graph

# cronologia dei comandi recenti
rtk gain --history

# breakdown giornaliero
rtk gain --daily

# export JSON per dashboard
rtk gain --all --format json

rtk discover fa il passo opposto: trova opportunità di risparmio che stai perdendo, ad esempio comandi per cui non esiste ancora un filtro e che vengono passati raw all'agent.

# scopri risparmi mancanti in tutti i progetti
rtk discover --all --since 7

Configurazione mirata

Il file di configurazione globale vive in ~/.config/rtk/config.toml (su macOS: ~/Library/Application Support/rtk/config.toml). Le opzioni più utili riguardano l'esclusione di comandi specifici dal rewriting e la gestione del salvataggio dell'output completo:

# config.toml di esempio
[hooks]
exclude_commands = ["curl", "playwright"]

[tee]
enabled = true
mode = "failures"

La sezione [tee] controlla se e quando salvare l'output non filtrato. Con mode = "failures" (default), il file viene scritto solo quando il comando fallisce — l'LLM può quindi leggere il contesto completo senza rieseguire nulla. Con "always" il file viene sempre salvato; con "never" mai.

Telemetria e privacy

RTK può raccogliere metriche aggregate anonime (una volta al giorno) per aiutare il team a identificare quali filtri servono e quali vanno migliorati. La telemetria è disabilitata di default e richiede consenso esplicito durante rtk init o via rtk telemetry enable. Cosa viene raccolto, in sintesi:

• Identità: hash SHA-256 salato del device (non reversibile).
• Ambiente: versione RTK, OS, architettura, metodo di installazione.
• Volume d'uso: numero di comandi nelle ultime 24h, token risparmiati.
• Qualità: top 5 comandi passthrough, parse failure, comandi con savings < 30%.
• Ecosistema: distribuzione per categoria (git 45%, cargo 20%, js 15%).

Cosa non viene raccolto: codice sorgente, path assoluti, argomenti dei comandi, segreti, environment variable, contenuti del repository. I comandi riportati sono solo nomi di tool (es. "git", "cargo"), mai righe intere. Puoi disattivare la telemetria in qualsiasi momento o richiedere la cancellazione totale:

# gestione completa della telemetria
rtk telemetry status
rtk telemetry disable
rtk telemetry forget

# blocco totale via environment
export RTK_TELEMETRY_DISABLED=1

Windows: cosa cambia

Su Windows nativo (cmd.exe o PowerShell) l'hook automatico di rewriting non funziona, perché richiede una shell Unix. RTK cade quindi in CLAUDE.md injection mode: l'agent riceve le istruzioni RTK ma i comandi non vengono riscritti automaticamente — devi invocare rtk cargo test, rtk git status eccetera in modo esplicito.

La soluzione consigliata dagli stessi autori è WSL: dentro WSL RTK lavora esattamente come su Linux, hook incluso. Per partire:

# installazione RTK dentro WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g

Ricorda di non fare doppio click su rtk.exe: è un tool CLI che stampa l'usage ed esce immediatamente. Sempre da terminale, mai da Esplora Risorse.

Disinstallazione

Se RTK non fa per te, la rimozione è pulita quanto l'installazione. Tre comandi a seconda del metodo usato:

# rimozione hook, regole e settings.json
rtk init -g --uninstall

# rimozione binario
cargo uninstall rtk
brew uninstall rtk

Verdetto: quando ha senso adottarlo

RTK non è un giocattolo: è uno strumento di produttività pensato per chi usa AI agent in modo intensivo e vuole massimizzare il budget di context. I casi d'uso in cui dà il massimo:

• Sessioni lunghe di pair programming con Claude Code, Codex o Cursor, dove il context si satura in fretta.
• Progetti multi-linguaggio (Rust + TypeScript + Python + Go) con molti test runner diversi.
• Workflow DevOps pesanti su Kubernetes, Docker, AWS CLI, Pulumi — RTK copre tutti i comandi più comuni.
• Team che vogliono abbassare il costo per sessione senza toccare i prompt o i modelli usati.

Se invece usi l'agent solo per task brevi e non tiri su Docker né fai test suite grosse, il guadagno sarà marginale. Ma il costo di adozione è praticamente zero: un comando per installarlo, uno per attivarlo, e da quel momento non devi più pensarci.

Approccio pragmatico consigliato: installa RTK, lancia rtk gain dopo una giornata di lavoro reale, e guarda i numeri. Se i token risparmiati superano il costo del setup (qualche minuto), hai la risposta. Il progetto è open source Apache 2.0, sviluppato da Patrick Szymkowiak, Florian Bruniaux e Adrien Eppling, con una community attiva su Discord.

Link utili

• Repository ufficiale su GitHub
• Sito ufficiale e guida completa
• Documento di architettura interna
• Guida di installazione dettagliata
• Policy di sicurezza del progetto
• Community Discord ufficiale