Skip to content

troubleshooting.md

Latest commit

 

History

History
184 lines (133 loc) · 4.43 KB

troubleshooting.md

File metadata and controls

184 lines (133 loc) · 4.43 KB
Raw
title Troubleshooting
description Common RTK issues and how to fix them
sidebar
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

Claude Code hook not rewriting commands

Symptom: rtk init -g succeeds on Windows, but Claude Code commands are not rewritten automatically.

Cause: Current Windows builds install the Claude Code PreToolUse hook as rtk hook claude. That hook matches Claude Code's Bash tool. If Claude Code is configured to use the PowerShell tool (CLAUDE_CODE_USE_POWERSHELL_TOOL=1), the hook will not see those commands yet.

Fix: Use Claude Code's default Bash tool on native Windows, or use WSL for Linux-like shell integration:

# 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 init -g should write rtk hook claude into Claude Code's settings. It no longer falls back to CLAUDE.md injection. You can still use RTK manually from any terminal: 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
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:

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

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