skills/rtk-ai__rtk
1
0
Fork 0
mirror of https://github.com/rtk-ai/rtk.git synced 2026-09-19 07:33:17 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
rtk-ai__rtk/docs/guide/resources/troubleshooting.md
T
Nicolas Le Cam 7c18567155 chore: migrate to Rust edition 2024 
Bump edition 2021 -> 2024. rust-version stays at 1.91, already well above
the 1.85 floor the edition needs; docs/guide/resources/troubleshooting.md
still claimed 1.70+, which is where a failed `cargo install --git` lands.

Four things the edition forces:

- std::env::{set_var,remove_var} are unsafe in 2024 with no safe std
  replacement. Rather than wrap the test call sites in unsafe -- which the
  crate denies and .semgrep.yml flags -- route them through temp-env, a
  dev-only dependency whose closure API is safe and which restores the
  previous value even when the body panics. The hand-rolled CLAUDE_DIR_LOCK
  and PI_DIR_LOCK guards existed only to serialise those mutations and are
  now redundant; CWD_LOCK and TEST_ENV_LOCK stay, they order more than the
  env var itself.

- unsafe_op_in_unsafe_fn is on by default, so the libc calls in the proxy
  signal handler and in stream.rs's relay handler need explicit unsafe
  blocks, scoped to the libc calls themselves.

- `gen` is a reserved keyword, so the closure by that name in diff_cmd.rs
  becomes make_lines.

- Tightened tail-expression temporary scopes let clippy prove the binding in
  setup_test_env is inlinable, so let_and_return now fires there.

if_let_rescope changes when the scrutinee temporary drops in an if let/else.
The two sites in show_claude_config take cargo fix --edition's match rewrite,
which keeps the 2021 drop timing.

rustfmt.toml is kept rather than dropped: cargo fmt passes --edition from
Cargo.toml, but a bare rustfmt invocation has no crate context and falls
back to edition 2015, which cannot parse the let-chains the next commit
introduces. Pinning it there keeps format-on-save and pre-commit hooks in
agreement with CI.

clippy::collapsible_if is allowed crate-wide for now; the follow-up commit
adopts let-chains and removes the allow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-14 01:26:43 +02:00

4.9 KiB
Raw Permalink Blame History

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.91 (edition 2024 needs Cargo 1.85 or newer).

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

Reference in New Issue View Git Blame Copy Permalink