Skip to content

INSTALL.md

Latest commit

 

History

History
346 lines (262 loc) · 9.4 KB

INSTALL.md

File metadata and controls

346 lines (262 loc) · 9.4 KB

rtk-plus Installation Guide

rtk-plus is an extended fork of rtk-ai/rtk. The binary is named rtk for backward compatibility.

Pre-Installation Check

# Check if rtk is already installed
rtk --version
rtk gain    # Should show token savings stats
which rtk

If rtk gain works, you already have rtk installed. To upgrade to rtk-plus, uninstall the existing version first.

Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/dioptx/rtk-plus/master/install.sh | sh

Cargo

cargo install --git https://github.com/dioptx/rtk-plus

After installation, verify:

rtk gain  # Must show token savings stats

Project Initialization

Which mode to choose?

  Do you want RTK active across ALL Claude Code projects?
  │
  ├─ YES → rtk init -g              (recommended)
  │         Hook + RTK.md (~10 tokens in context)
  │         Commands auto-rewritten transparently
  │
  ├─ YES, minimal → rtk init -g --hook-only
  │         Hook only, nothing added to CLAUDE.md
  │         Zero tokens in context
  │
  └─ NO, single project → rtk init
            Local CLAUDE.md only (137 lines)
            No hook, no global effect

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
# → Prompts: "Patch settings.json? [y/N]"
# → If yes: patches + creates backup (~/.claude/settings.json.bak)

# Automated alternatives:
rtk init -g --auto-patch    # Patch without prompting
rtk init -g --no-patch      # Print manual instructions instead

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

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

What is settings.json? Claude Code's hook registry. RTK adds a PreToolUse hook that rewrites commands transparently. Without this, Claude won't invoke the hook automatically.

  Claude Code          settings.json        rtk-rewrite.sh        RTK binary
       │                    │                     │                    │
       │  "git status"      │                     │                    │
       │ ──────────────────►│                     │                    │
       │                    │  PreToolUse trigger  │                    │
       │                    │ ───────────────────►│                    │
       │                    │                     │  rewrite command   │
       │                    │                     │  → rtk git status  │
       │                    │◄────────────────────│                    │
       │                    │  updated command     │                    │
       │                    │                                          │
       │  execute: rtk git status                                      │
       │ ─────────────────────────────────────────────────────────────►│
       │                                                               │  filter
       │  "3 modified, 1 untracked ✓"                                  │
       │◄──────────────────────────────────────────────────────────────│

Backup Safety: RTK backs up existing settings.json before changes. Restore if needed:

cp ~/.claude/settings.json.bak ~/.claude/settings.json

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

From old 137-line CLAUDE.md injection (pre-0.22)

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

From old hook with inline logic (pre-0.24) — ⚠️ Breaking Change

RTK 0.24.0 replaced the inline command-detection hook (~200 lines) with a thin delegator that calls rtk rewrite. The binary now contains the rewrite logic, so adding new commands no longer requires a hook update.

The old hook still works but won't benefit from new rules added in future releases.

# Upgrade hook to thin delegator
rtk init --global

# Verify the new hook is active
rtk init --show
# Should show: ✅ Hook: ... (thin delegator, up to date)

Common User Flows

First-Time User (Recommended)

# 1. Install RTK
cargo install --git https://github.com/dioptx/rtk-plus
rtk gain  # Verify (must show token stats)

# 2. Setup with prompts
rtk init -g
# → Answer 'y' when prompted to patch settings.json
# → Creates backup automatically

# 3. Restart Claude Code
# 4. Test: git status (should use rtk)

CI/CD or Automation

# Non-interactive setup (no prompts)
rtk init -g --auto-patch

# Verify in scripts
rtk init --show | grep "Hook:"

Conservative User (Manual Control)

# Get manual instructions without patching
rtk init -g --no-patch

# Review printed JSON snippet
# Manually edit ~/.claude/settings.json
# Restart Claude Code

Temporary Trial

# Install hook
rtk init -g --auto-patch

# Later: remove everything
rtk init -g --uninstall

# Restore backup if needed
cp ~/.claude/settings.json.bak ~/.claude/settings.json

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

Uninstalling

Complete Removal (Global Installations Only)

# Complete removal (global installations only)
rtk init -g --uninstall

# What gets removed:
#   - Hook: ~/.claude/hooks/rtk-rewrite.sh
#   - Context: ~/.claude/RTK.md
#   - Reference: @RTK.md line from ~/.claude/CLAUDE.md
#   - Registration: RTK hook entry from settings.json

# Restart Claude Code after uninstall

For Local Projects: Manually remove RTK block from ./CLAUDE.md

Binary Removal

# If installed via cargo
cargo uninstall rtk-plus

Restore from Backup (if needed)

cp ~/.claude/settings.json.bak ~/.claude/settings.json

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

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).