rtk-ai__rtk/docs/guide/resources/troubleshooting.md

title, description, sidebar

title	description	sidebar
Troubleshooting	Common RTK issues and how to fix them	order 2

Troubleshooting

rtk gain says "not a rtk command"

Symptom:

$ rtk gain
rtk: 'gain' is not a rtk command. See 'rtk --help'.

Cause: You installed Rust Type Kit (reachingforthejack/rtk) instead of Rust Token Killer (rtk-ai/rtk). They share the same binary name.

Fix:

cargo uninstall rtk
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
rtk gain    # should now show token savings stats

How to tell which rtk you have

If rtk gain...	You have
Shows token savings dashboard	Rust Token Killer ✅
Returns "not a rtk command"	Rust Type Kit ❌

AI assistant not using RTK

Symptom: Claude Code (or another agent) runs cargo test instead of rtk cargo test.

Checklist:

1. Verify RTK is installed:

   rtk --version
   rtk gain
   

2. Initialize the hook:

   rtk init --global    # Claude Code
   rtk init --global --cursor    # Cursor
   rtk init --global --opencode  # OpenCode
   

3. Restart your AI assistant.

4. Verify hook status:

   rtk init --show
   

5. Check settings.json has the hook registered (Claude Code):

   cat ~/.claude/settings.json | grep rtk
   

RTK not found after cargo install

Symptom:

$ rtk --version
zsh: command not found: rtk

Cause: ~/.cargo/bin is not in your PATH.

Fix:

For bash (~/.bashrc) or zsh (~/.zshrc):

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

For fish (~/.config/fish/config.fish):

set -gx PATH $HOME/.cargo/bin $PATH

Then reload:

source ~/.zshrc    # or ~/.bashrc
rtk --version

RTK on Windows

Double-clicking rtk.exe does nothing

Symptom: You double-click rtk.exe, a terminal flashes and closes instantly.

Cause: RTK is a command-line tool. With no arguments, it prints usage and exits. The console window opens and closes before you can read anything.

Fix: Open a terminal first, then run RTK from there:

• Press Win+R, type cmd, press Enter
• Or open PowerShell or Windows Terminal
• Then run: rtk --version

Hook not working (no auto-rewrite)

Symptom: rtk init -g shows "Falling back to --claude-md mode" on Windows.

Cause: The auto-rewrite hook (rtk-rewrite.sh) requires a Unix shell. Native Windows doesn't have one.

Fix: Use WSL for full hook support:

# Inside WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g    # full hook mode works in WSL

On native Windows, RTK falls back to CLAUDE.md injection. Your AI assistant gets RTK instructions but won't auto-rewrite commands. It can still use RTK manually: rtk cargo test, rtk git status, etc.

Node.js tools not found

Symptom:

rtk vitest --run
Error: program not found

Cause: On Windows, Node.js tools are installed as .CMD/.BAT wrappers. Older RTK versions couldn't find them.

Fix: Update to RTK v0.23.1+:

cargo install --git https://github.com/rtk-ai/rtk --branch master
rtk --version    # should be 0.23.1+

Compilation error during installation

rustup update stable
rustup default stable
cargo clean
cargo build --release
cargo install --path . --force

Minimum required Rust version: 1.70+.

OpenCode not using RTK

rtk init --global --opencode
# restart OpenCode
rtk init --show    # should show "OpenCode: plugin installed"

cargo install rtk installs the wrong package

If Rust Type Kit is published to crates.io under the name rtk, cargo install rtk may install the wrong one.

Always use the explicit URL, pinned to the release branch:

cargo install --git https://github.com/rtk-ai/rtk --branch master

Does RTK break Claude's prompt cache?

No. RTK filters command output once, at execution time. The filtered result is written into the conversation history and never changes afterwards, and prompt caching matches on a stable prefix — RTK does not rewrite anything the cache has already seen.

Smaller tool results also make caching cheaper: cache writes bill at 1.25x and cache reads at 0.1x the input rate, so fewer tokens in means less to write once and less to re-read every turn.

To see your own cache write and read volumes next to RTK's savings:

rtk cc-economics

rtk gain reports token savings only; the cache breakdown lives in rtk cc-economics.

Run the diagnostic script

From the RTK repository root:

bash scripts/check-installation.sh

Checks:

• RTK installed and in PATH
• Correct version (Token Killer, not Type Kit)
• Available features
• Claude Code integration
• Hook status

Still stuck?

Open an issue: https://github.com/rtk-ai/rtk/issues