|
| 1 | +# RTK Installation Guide - For AI Coding Assistants |
| 2 | + |
| 3 | +## Pre-Installation Check (REQUIRED) |
| 4 | + |
| 5 | +**AI assistants should ALWAYS verify if RTK is already installed before attempting installation.** |
| 6 | + |
| 7 | +```bash |
| 8 | +# Check if RTK is installed |
| 9 | +rtk --version |
| 10 | + |
| 11 | +# Check installation path |
| 12 | +which rtk |
| 13 | +``` |
| 14 | + |
| 15 | +If RTK is already installed and working, **DO NOT reinstall**. Skip directly to "Project Initialization" section. |
| 16 | + |
| 17 | +## Installation (only if RTK not available) |
| 18 | + |
| 19 | +### Option 1: Install from fork (RECOMMENDED currently) |
| 20 | + |
| 21 | +This fork includes critical fixes and pnpm/Vitest support not yet merged upstream. |
| 22 | + |
| 23 | +```bash |
| 24 | +# Clone the fork |
| 25 | +git clone https://github.com/FlorianBruniaux/rtk.git |
| 26 | +cd rtk |
| 27 | + |
| 28 | +# Check branch (should be master or feat/vitest-support) |
| 29 | +git branch |
| 30 | + |
| 31 | +# Compile and install |
| 32 | +cargo install --path . --force |
| 33 | + |
| 34 | +# Verify installation |
| 35 | +rtk --version |
| 36 | +``` |
| 37 | + |
| 38 | +### Option 2: Install from upstream (when PRs are merged) |
| 39 | + |
| 40 | +```bash |
| 41 | +cargo install rtk |
| 42 | +``` |
| 43 | + |
| 44 | +## Project Initialization |
| 45 | + |
| 46 | +**For each project where you want to use RTK:** |
| 47 | + |
| 48 | +```bash |
| 49 | +# Navigate to project directory |
| 50 | +cd /path/to/your/project |
| 51 | + |
| 52 | +# Initialize RTK for this project (creates ./CLAUDE.md) |
| 53 | +rtk init |
| 54 | + |
| 55 | +# OR initialize globally (creates ~/CLAUDE.md for all projects) |
| 56 | +rtk init --global |
| 57 | +``` |
| 58 | + |
| 59 | +## Installation Verification |
| 60 | + |
| 61 | +```bash |
| 62 | +# Basic test |
| 63 | +rtk ls . |
| 64 | + |
| 65 | +# Test with git |
| 66 | +rtk git status |
| 67 | + |
| 68 | +# Test with pnpm (fork only) |
| 69 | +rtk pnpm list |
| 70 | + |
| 71 | +# Test with Vitest (feat/vitest-support branch only) |
| 72 | +rtk vitest run |
| 73 | +``` |
| 74 | + |
| 75 | +## Essential Commands |
| 76 | + |
| 77 | +### Files |
| 78 | +```bash |
| 79 | +rtk ls . # Compact tree view |
| 80 | +rtk read file.rs # Optimized reading |
| 81 | +rtk grep "pattern" . # Grouped search results |
| 82 | +``` |
| 83 | + |
| 84 | +### Git |
| 85 | +```bash |
| 86 | +rtk git status # Compact status |
| 87 | +rtk git log -n 10 # Condensed logs |
| 88 | +rtk git diff # Optimized diff |
| 89 | +rtk git add . # → "ok ✓" |
| 90 | +rtk git commit -m "msg" # → "ok ✓ abc1234" |
| 91 | +rtk git push # → "ok ✓ main" |
| 92 | +``` |
| 93 | + |
| 94 | +### Pnpm (fork only) |
| 95 | +```bash |
| 96 | +rtk pnpm list # Dependency tree (-70% tokens) |
| 97 | +rtk pnpm outdated # Available updates (-80-90%) |
| 98 | +rtk pnpm install pkg # Silent installation |
| 99 | +``` |
| 100 | + |
| 101 | +### Tests |
| 102 | +```bash |
| 103 | +rtk test cargo test # Failures only (-90%) |
| 104 | +rtk vitest run # Filtered Vitest output (-99.6%) |
| 105 | +``` |
| 106 | + |
| 107 | +### Statistics |
| 108 | +```bash |
| 109 | +rtk gain # Token savings |
| 110 | +rtk gain --graph # With ASCII graph |
| 111 | +rtk gain --history # With command history |
| 112 | +``` |
| 113 | + |
| 114 | +## Validated Token Savings |
| 115 | + |
| 116 | +### Production T3 Stack Project |
| 117 | +| Operation | Standard | RTK | Reduction | |
| 118 | +|-----------|----------|-----|-----------| |
| 119 | +| `vitest run` | 102,199 chars | 377 chars | **-99.6%** | |
| 120 | +| `git status` | 529 chars | 217 chars | **-59%** | |
| 121 | +| `pnpm list` | ~8,000 tokens | ~2,400 | **-70%** | |
| 122 | +| `pnpm outdated` | ~12,000 tokens | ~1,200-2,400 | **-80-90%** | |
| 123 | + |
| 124 | +### Typical Claude Code Session (30 min) |
| 125 | +- **Without RTK**: ~150,000 tokens |
| 126 | +- **With RTK**: ~45,000 tokens |
| 127 | +- **Savings**: **70% reduction** |
| 128 | + |
| 129 | +## Troubleshooting |
| 130 | + |
| 131 | +### RTK command not found after installation |
| 132 | +```bash |
| 133 | +# Check PATH |
| 134 | +echo $PATH | grep -o '[^:]*\.cargo[^:]*' |
| 135 | + |
| 136 | +# Add to PATH if needed (~/.bashrc or ~/.zshrc) |
| 137 | +export PATH="$HOME/.cargo/bin:$PATH" |
| 138 | + |
| 139 | +# Reload shell |
| 140 | +source ~/.bashrc # or source ~/.zshrc |
| 141 | +``` |
| 142 | + |
| 143 | +### RTK command not available (e.g., vitest) |
| 144 | +```bash |
| 145 | +# Check branch |
| 146 | +cd /path/to/rtk |
| 147 | +git branch |
| 148 | + |
| 149 | +# Switch to feat/vitest-support if needed |
| 150 | +git checkout feat/vitest-support |
| 151 | + |
| 152 | +# Reinstall |
| 153 | +cargo install --path . --force |
| 154 | +``` |
| 155 | + |
| 156 | +### Compilation error |
| 157 | +```bash |
| 158 | +# Update Rust |
| 159 | +rustup update stable |
| 160 | + |
| 161 | +# Clean and recompile |
| 162 | +cargo clean |
| 163 | +cargo build --release |
| 164 | +cargo install --path . --force |
| 165 | +``` |
| 166 | + |
| 167 | +## Support and Contributing |
| 168 | + |
| 169 | +- **Issues**: https://github.com/pszymkowiak/rtk/issues (upstream) |
| 170 | +- **Fork issues**: https://github.com/FlorianBruniaux/rtk/issues |
| 171 | +- **Pull Requests**: Create on fork then propose upstream |
| 172 | + |
| 173 | +## AI Assistant Checklist |
| 174 | + |
| 175 | +Before each session: |
| 176 | + |
| 177 | +- [ ] Verify RTK is installed: `rtk --version` |
| 178 | +- [ ] If not installed → follow "Install from fork" |
| 179 | +- [ ] If project not initialized → `rtk init` |
| 180 | +- [ ] Use `rtk` for ALL git/pnpm/test/vitest commands |
| 181 | +- [ ] Check savings: `rtk gain` |
| 182 | + |
| 183 | +**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). |
0 commit comments