RTK — pełna konfiguracja, typowe błędy i kiedy nie zadziała

RTK (Rust Token Killer) to jedno z dwóch narzędzi, które na stałe trzymam w konfiguracji Claude Code. Ale jego limit jest prosty: działa tylko na Bash. Wbudowane Read/Grep/Glob go omijają. Tu opisuję, co dokładnie instaluje rtk init, jak czytać rtk gain i jak obejść trzy błędy, na które trafiłem.

Wracamy do głównego artykułu: Claude Code — jak przestać palić tokeny.

Matryca instalacji dla systemów

RTK oferuje cztery ścieżki instalacji, ale nie każda działa wszędzie tak samo.

Metoda	macOS	Linux	Windows	Zalecane?
brew install rtk	tak	tak (Linuxbrew)	nie	macOS — tak
curl install.sh	tak	tak	nie	Linux — tak
cargo install --git	tak	tak	tak	gdy masz zestaw narzędzi Rusta
cargo install rtk (crates.io)	NIE	NIE	NIE	to inny projekt!

Kolizja nazwy to najczęstszy problem. Na crates.io rtk jest zarezerwowane przez reachingforthejack/rtk (Rust Type Kit) — zupełnie inny projekt. Jeśli zobaczysz “command not found” po cargo install rtk, albo rtk gain zwraca błąd składni, to masz zainstalowany zły plik wykonywalny.

# Weryfikacja:
rtk --version    # powinien pokazać: rtk 0.37.2 (lub wyżej)
rtk gain         # powinien pokazać statystyki, nie pomoc argumentów
which rtk        # sprawdź ścieżkę — /opt/homebrew/bin/rtk, ~/.cargo/bin/rtk itd.

# Jak trafiłeś na zły:
cargo uninstall rtk
cargo install --git https://github.com/rtk-ai/rtk

Windows bez WSL działa w trybie awaryjnym — RTK zainstaluje skrypt bash, ale hook nie będzie automatycznie przepisywać komend. W praktyce na Windowsie większość wartości zyskuje dopiero w WSL2.

Co wrzuca rtk init -g

rtk init -g

Ta jedna komenda robi trzy rzeczy:

1. Dokleja hook do ~/.claude/settings.json (globalnie, wszystkie projekty)
2. Tworzy ~/.claude/RTK.md — skrócona instrukcja, którą Claude czyta co sesja
3. Kopiuje rtk-rewrite.sh do ~/.claude/hooks/

Fragment settings.json, który dostajesz:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/rtk-rewrite.sh"
          }
        ]
      }
    ]
  }
}

Kluczowe: matcher to Bash i tylko Bash. To znaczy, że każde wywołanie narzędzia Bash przez Claude’a przechodzi przez skrypt, który sprawdza czy komenda ma wariant RTK i jeśli tak, przepisuje ją. Read, Grep, Glob, WebFetch, Task omijają ten hook.

Jeśli wolisz tylko hook bez RTK.md:

rtk init -g --hook-only

To dobra opcja, gdy i tak masz już przeciążony globalny CLAUDE.md.

Czego RTK nie dotyka (i dlaczego)

Claude Code często używa swoich wbudowanych narzędzi zamiast Basha:

• Read file.txt — wbudowane, nie Bash
• Grep "pattern" --glob "*.ts" — wbudowane
• Glob "**/*.rs" — wbudowane

Żadne z powyższych nie przechodzi przez RTK. Jeśli twój Claude dużo czyta plików bezpośrednio (a tak domyślnie działa), RTK pomoże tylko tam, gdzie model sam z siebie decyduje użyć Basha (np. git, cargo, docker, kubectl, gh, ls w konkretnych przypadkach).

Praktyczna implikacja: jeśli chcesz żeby cat file.rs poszedł przez RTK, trzeba popchnąć Claude’a do użycia Basha. W praktyce sam z siebie woli Read — więc oszczędność na cat z tabelki RTK trzeba traktować jak pułap teoretyczny, nie wartość, którą zobaczysz w swojej sesji.

rtk gain — jak czytać statystyki

rtk gain

Wyjście wygląda mniej więcej tak:

Total commands intercepted: 142
Total tokens saved: ~48,700
Average reduction: 73%
Top commands by savings:
  git status     × 18    -80%
  cargo test     × 5     -91%
  git diff       × 12    -76%
  ...

Average reduction to średnia ważona per komenda, nie per sesja. Dla całej sesji 80% to zazwyczaj zawyżona liczba — realnie zobaczysz tam może 30-50%, bo RTK łapie tylko część operacji.

Ciekawsze flagi:

rtk gain --history --daily    # agregacja dzienna
rtk gain --history --weekly   # agregacja tygodniowa
rtk gain --graph              # ASCII wykres w terminalu

rtk discover analizuje logi sesji Claude Code i pokazuje komendy, które mógł przepisać, ale nie dostał — bo poszły przez wbudowane narzędzia. To dobry test rzeczywistości, na ile RTK faktycznie u ciebie działa.

Trzy błędy, na które warto zwrócić uwagę

rtk ls zwraca pusty ciąg znaków (#1418)

Potwierdzone na Fedora 43, czasem Arch. Obejście: zamiast rtk ls . używaj rtk find . -maxdepth 2 -type f albo po prostu zostaw ls bez RTK.

rtk cat emituje ANSI do strumienia non-TTY (#1409)

Claude Code nie jest prawdziwym TTY. RTK powinien detektować to i wyłączać kolory, ale w kilku wersjach tego nie robi. Efekt: do kontekstu trafiają escape sequence (\x1b[32m, \x1b[0m), które same w sobie zjadają tokeny. Obejście do czasu fixa:

TERM=dumb rtk cat file.rs

albo użyj standardowego cat, dopóki nie ma poprawki.

rtk rg zamieniane na grep i zwiększa użycie tokenów (#1385, #1367)

To najbardziej kontrintuicyjny błąd. RTK w niektórych ścieżkach zamienia rg (ripgrep) na grep, który nie ma inteligentnego grupowania RTK. Efekt: wyjście rośnie zamiast maleć. Jeśli widzisz w rtk gain --history, że rg ma ujemne oszczędności — to właśnie ten przypadek.

Obejście:

rtk proxy rg "pattern"   # passthrough bez transformacji

Kiedy RTK nie pomoże wcale

Sesje, gdzie RTK daje <20% realnej oszczędności:

• Dużo czytania plików — Claude woli Read, RTK nie łapie
• Research w kodzie — Grep/Glob wbudowane
• Zadania UI/frontendu — głównie edycje, niewiele wywołań narzędzi
• Dyskusje architektoniczne — prawie brak Basha

Sesje, gdzie RTK błyszczy:

• CI/CD debugging — dużo gh run, docker logs, kubectl
• Test-driven development — cargo test, pytest, vitest w pętli
• Refactoring wieloplikowy z testami — cargo check po każdej zmianie
• Procesy silnie oparte na Gicie — status, diff, log, show

Jeśli twój profil sesji to głównie lewa kolumna — RTK nie będzie przełomem.

Odinstalowanie

Jeśli chcesz wycofać wszystko:

# Usuń hook z settings.json ręcznie (edytor) albo:
rtk init -g --uninstall

# Usuń binarkę:
brew uninstall rtk
# lub: cargo uninstall rtk
# lub: rm ~/.local/bin/rtk

# Opcjonalnie usuń RTK.md i historię:
rm ~/.claude/RTK.md
rm -rf ~/.claude/rtk/   # cache i historia gain

Zweryfikuj, że Claude Code uruchamia się bez hookowych errorów:

claude --version
# powinno startować czysto, bez komunikatów o missing rtk-rewrite.sh

RTK vs Context Mode — kiedy co

Oba mogą rozwiązać ten sam przypadek użycia (duży wolumen danych z terminala), ale robią to inaczej.

Aspekt	RTK	Context Mode
Licencja	Apache 2.0	Elastic License 2.0 (source-available)
Instalacja	brew / curl / cargo	/plugin install
Zakres hooków	tylko Bash	Bash + Read + Grep + WebFetch + Task
Sandbox	brak — kompresja na miejscu	osobny proces (izolacja)
Typowe zastosowanie	git, cargo, docker, test runnery	duże JSON, logi, GitHub API
Realna redukcja	30-50% całej sesji	60-98% na zadaniach z dużą ilością danych
Krawędzie	kolizja nazwy, błędy ls/cat	osierocone procesy MCP, XSS #293

Reguła kciuka: jeśli 80% twojego bólu to testy i git, weź RTK. Jeśli 80% to pobieranie danych z API i parsowanie logów, weź Context Mode. Oba na raz to konflikt hooków, więc ich nie łącz.

---

Wracając do głównego artykułu: Claude Code — jak przestać palić tokeny. Alternatywy i porównanie z Caveman Claude rozkładam w analizie liczb Cavemana.