rtk-ai__rtk/INSTALL.md

RTK Installation Guide - For AI Coding Assistants

⚠️ Name Collision Warning

There are TWO completely different projects named "rtk":

1. ✅ Rust Token Killer (this project) - LLM token optimizer

   • Repos: rtk-ai/rtk
   • Has rtk gain command for token savings stats

2. ❌ Rust Type Kit (reachingforthejack/rtk) - DIFFERENT PROJECT

   • Rust codebase query tool and type generator
   • DO NOT install if you want token optimization

Pre-Installation Check (REQUIRED)

AI assistants should ALWAYS verify if RTK is already installed before attempting installation.

# Check if RTK is installed
rtk --version

# CRITICAL: Verify it's the Token Killer (not Type Kit)
rtk gain    # Should show token savings stats, NOT "command not found"

# Check installation path
which rtk

If rtk gain works, you have the correct RTK installed. DO NOT reinstall. Skip to "Project Initialization".

If rtk gain fails but rtk --version succeeds, you have the wrong RTK (Type Kit). Uninstall and reinstall the correct one (see below).

Installation (only if RTK not available or wrong RTK installed)

Step 0: Uninstall Wrong RTK (if needed)

If you accidentally installed Rust Type Kit:

cargo uninstall rtk

Quick Install (Linux/macOS)

curl -fsSL https://github.com/rtk-ai/rtk/blob/master/install.sh | sh

After installation, verify you have the correct rtk:

rtk gain  # Must show token savings stats (not "command not found")

Alternative: Manual Installation

# From rtk-ai repository (NOT reachingforthejack!)
cargo install --git https://github.com/rtk-ai/rtk

# OR (if published and correct on crates.io)
cargo install rtk

# ALWAYS VERIFY after installation
rtk gain  # MUST show token savings, not "command not found"

⚠️ WARNING: cargo install rtk from crates.io might install the wrong package. Always verify with rtk gain.

Project Initialization

Recommended: Global Hook-First Setup

Best for: All projects, automatic RTK usage

rtk init -g
# → Installs hook to ~/.claude/hooks/rtk-rewrite.sh
# → Creates ~/.claude/RTK.md (10 lines, meta commands only)
# → Adds @RTK.md reference to ~/.claude/CLAUDE.md
# → Prints settings.json instructions

# Follow printed instructions to add hook to ~/.claude/settings.json
# Then restart Claude Code

# Verify installation
rtk init --show  # Check hook is installed and executable

Token savings: ~99.5% reduction (2000 tokens → 10 tokens in context)

Alternative: Local Project Setup

Best for: Single project without hook

cd /path/to/your/project
rtk init  # Creates ./CLAUDE.md with full RTK instructions (137 lines)

Token savings: Instructions loaded only for this project

Upgrading from Previous Version

If you previously used rtk init -g with the old system (137-line injection):

rtk init -g  # Automatically migrates to hook-first mode
# → Removes old 137-line block
# → Installs hook + RTK.md
# → Adds @RTK.md reference

Installation Verification

# Basic test
rtk ls .

# Test with git
rtk git status

# Test with pnpm (fork only)
rtk pnpm list

# Test with Vitest (feat/vitest-support branch only)
rtk vitest run

Essential Commands

Files

rtk ls .              # Compact tree view
rtk read file.rs      # Optimized reading
rtk grep "pattern" .  # Grouped search results

Git

rtk git status        # Compact status
rtk git log -n 10     # Condensed logs
rtk git diff          # Optimized diff
rtk git add .         # → "ok ✓"
rtk git commit -m "msg"  # → "ok ✓ abc1234"
rtk git push          # → "ok ✓ main"

Pnpm (fork only)

rtk pnpm list         # Dependency tree (-70% tokens)
rtk pnpm outdated     # Available updates (-80-90%)
rtk pnpm install pkg  # Silent installation

Tests

rtk test cargo test   # Failures only (-90%)
rtk vitest run        # Filtered Vitest output (-99.6%)

Statistics

rtk gain              # Token savings
rtk gain --graph      # With ASCII graph
rtk gain --history    # With command history

Validated Token Savings

Production T3 Stack Project

Operation	Standard	RTK	Reduction
vitest run	102,199 chars	377 chars	-99.6%
git status	529 chars	217 chars	-59%
pnpm list	~8,000 tokens	~2,400	-70%
pnpm outdated	~12,000 tokens	~1,200-2,400	-80-90%

Typical Claude Code Session (30 min)

• Without RTK: ~150,000 tokens
• With RTK: ~45,000 tokens
• Savings: 70% reduction

Troubleshooting

RTK command not found after installation

# Check PATH
echo $PATH | grep -o '[^:]*\.cargo[^:]*'

# Add to PATH if needed (~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

RTK command not available (e.g., vitest)

# Check branch
cd /path/to/rtk
git branch

# Switch to feat/vitest-support if needed
git checkout feat/vitest-support

# Reinstall
cargo install --path . --force

Compilation error

# Update Rust
rustup update stable

# Clean and recompile
cargo clean
cargo build --release
cargo install --path . --force

Support and Contributing

• Troubleshooting: See TROUBLESHOOTING.md for common issues
• GitHub issues: https://github.com/rtk-ai/rtk/issues
• Pull Requests: https://github.com/rtk-ai/rtk/pulls

⚠️ If you installed the wrong rtk (Type Kit), see TROUBLESHOOTING.md

AI Assistant Checklist

Before each session:

• Verify RTK is installed: rtk --version
• If not installed → follow "Install from fork"
• If project not initialized → rtk init
• Use rtk for ALL git/pnpm/test/vitest commands
• Check savings: rtk gain

Golden Rule: AI coding assistants should ALWAYS use rtk as a proxy for shell commands that generate verbose output (git, pnpm, npm, cargo test, vitest, docker, kubectl).