---
title: "RTK: pełna konfiguracja, typowe błędy i kiedy nie zadziała"
description: "RTK daje ~80% redukcji na Bashu, ale tylko tam. Matryca instalacji dla systemów, settings.json po init, jak czytać rtk gain, obejścia najczęstszych błędów."
author: Maciej Olszewski
date: 2026-05-07
tags:
  - claude-code
  - ai
url: "https://inprojects.ai/blog/claude-code-rtk-konfiguracja/"
language: pl
---

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

> RTK daje ~80% redukcji na Bashu, ale tylko tam. Matryca instalacji dla systemów, settings.json po init, jak czytać rtk gain, obejścia najczęstszych błędów.

> RTK (Rust Token Killer) to jedno z dwóch narzędzi, które na stałe trzymam w konfiguracji Claude Code. Ale jego ograniczenie jest proste: 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](https://inprojects.ai/blog/claude-code-oszczedzanie-tokenow/).

## 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 | na macOS tak |
| `curl install.sh` | tak | tak | nie | na Linuksie 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 nazwę `rtk` zajmuje `reachingforthejack/rtk` (Rust Type Kit), zupełnie inny projekt. Jeśli zobaczysz "command not found" po `cargo install rtk`, albo `rtk gain` zwróci błąd składni, masz zainstalowany zły plik wykonywalny.

```bash
# 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. Na Windowsie RTK ma sens dopiero w WSL2.

## Co wrzuca `rtk init -g`

```bash
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óconą instrukcję, którą Claude czyta w każdej sesji
3. Kopiuje `rtk-rewrite.sh` do `~/.claude/hooks/`

Fragment `settings.json`, który dostajesz:

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

Najważniejsze: matcher to `Bash` i tylko `Bash`. 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`:

```bash
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 decyduje się użyć Basha (np. `git`, `cargo`, `docker`, `kubectl`, `gh`, `ls` w konkretnych przypadkach).

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

## `rtk gain`: jak czytać statystyki

```bash
rtk gain
```

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

```text
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 na komendę, nie na sesję. Dla całej sesji 80% to zazwyczaj liczba zawyżona. Realnie zobaczysz może 30-50%, bo RTK łapie tylko część operacji.

Ciekawsze flagi:

```bash
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 ich nie dostał, bo poszły przez wbudowane narzędzia. To dobry sprawdzian, na ile RTK faktycznie u ciebie działa.

## Trzy błędy, na które trafisz najprędzej

### `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 to wykrywać i wyłączać kolory, ale w kilku wersjach tego nie robi. Efekt: do kontekstu trafiają sekwencje sterujące (`\x1b[32m`, `\x1b[0m`), które same zjadają tokeny. Obejście do czasu poprawki:

```bash
TERM=dumb rtk cat file.rs
```

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

### `rtk rg` zamieniane na `grep` 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:

```bash
rtk proxy rg "pattern"   # przepuszcza bez transformacji
```

## Kiedy RTK nie pomoże wcale

Sesje, w których RTK daje <20% realnej oszczędności:

- **Dużo czytania plików**: Claude woli Read, RTK tego nie łapie
- **Przeszukiwanie kodu**: wbudowane Grep/Glob
- **Zadania UI/frontendu**: głównie edycje, niewiele wywołań narzędzi
- **Dyskusje architektoniczne**: prawie brak Basha

Sesje, w których RTK błyszczy:

- **Debugowanie CI/CD**: dużo `gh run`, `docker logs`, `kubectl`
- **Praca w rytmie TDD**: `cargo test`, `pytest`, `vitest` w pętli
- **Refaktoryzacja wieloplikowa 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 pierwsza lista, RTK nie będzie przełomem.

## Odinstalowanie

Jeśli chcesz wycofać wszystko:

```bash
# 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
```

Sprawdź, czy Claude Code uruchamia się bez błędów hooków:

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

## RTK a Context Mode: kiedy które

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, uruchamianie testów | duże JSON, logi, GitHub API |
| Realna redukcja | 30-50% całej sesji | 60-98% na zadaniach z dużą ilością danych |
| Słabe punkty | kolizja nazwy, błędy `ls`/`cat` | osierocone procesy MCP, XSS #293 |

Prosta zasada: 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](https://inprojects.ai/blog/claude-code-oszczedzanie-tokenow/). Alternatywy i porównanie z Caveman Claude rozkładam w [analizie liczb Cavemana](https://inprojects.ai/blog/claude-code-caveman-liczby/).