Florian BRUNIAUX
25438b29ae
Creates the complete user-facing guide for the docs website: Getting started: - quick-start.md: 5-minute walkthrough (init, first commands, rtk gain) - supported-agents.md: Claude Code, Cursor, Copilot, Gemini, Cline, Windsurf, Codex, OpenCode — integration tiers, install commands, graceful degradation Commands (adapted from FEATURES.md, English, --help-first format): - git.md: status/log/diff/show/add/commit/push/pull/branch + gh CLI - cargo.md: test/nextest/build/check/clippy/install + generic test/err wrappers - files.md: ls/read/grep/find/diff/wc/smart with before/after examples - javascript.md: vitest/playwright/tsc/eslint/prettier/next/pnpm/npm/npx/prisma - python.md: pytest/ruff/mypy/pip/deps Reference: - filters/using-filters.md: 8-stage pipeline, lookup priority, TOML DSL reference, Mermaid diagram (adapted from docs/filter-workflow.md) - analytics/gain.md: rtk gain flags, daily/weekly/monthly breakdowns, export formats, token estimation, database management (from docs/AUDIT_GUIDE.md) - configuration.md: full config.toml reference, env vars, tee system, telemetry - troubleshooting.md: common issues and fixes (from docs/TROUBLESHOOTING.md) All pages carry valid frontmatter (title, description, sidebar.order). No existing files modified. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com>
3.0 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Troubleshooting | Common RTK issues and how to fix them |
|
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:
-
Verify RTK is installed:
rtk --version rtk gain -
Initialize the hook:
rtk init --global # Claude Code rtk init --global --cursor # Cursor rtk init --global --opencode # OpenCode -
Restart your AI assistant.
-
Verify hook status:
rtk init --show -
Check
settings.jsonhas 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 not working on Windows
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