2026-01-28 17:00:50 +01:00
# RTK Installation Guide - For AI Coding Assistants
2026-02-02 15:20:39 +01:00
## ⚠️ Name Collision Warning
**There are TWO completely different projects named "rtk": **
1. ✅ **Rust Token Killer ** (this project) - LLM token optimizer
2026-02-02 20:22:25 +01:00
- Repos: `rtk-ai/rtk`
2026-02-02 15:20:39 +01:00
- 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**
2026-01-28 17:00:50 +01:00
## Pre-Installation Check (REQUIRED)
**AI assistants should ALWAYS verify if RTK is already installed before attempting installation. **
``` bash
# Check if RTK is installed
rtk --version
2026-02-02 15:20:39 +01:00
# CRITICAL: Verify it's the Token Killer (not Type Kit)
rtk gain # Should show token savings stats, NOT "command not found"
2026-01-28 17:00:50 +01:00
# Check installation path
which rtk
```
2026-02-02 15:20:39 +01:00
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)
2026-01-28 17:00:50 +01:00
2026-02-02 15:20:39 +01:00
If you accidentally installed Rust Type Kit:
2026-01-28 17:00:50 +01:00
2026-02-02 15:20:39 +01:00
``` bash
cargo uninstall rtk
```
2026-01-28 17:00:50 +01:00
2026-02-02 18:39:18 +01:00
### Quick Install (Linux/macOS)
2026-01-28 17:00:50 +01:00
``` bash
2026-02-12 12:17:37 +01:00
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
2026-02-02 18:39:18 +01:00
```
2026-01-28 17:00:50 +01:00
2026-02-02 18:39:18 +01:00
After installation, **verify you have the correct rtk ** :
``` bash
rtk gain # Must show token savings stats (not "command not found")
2026-01-28 17:00:50 +01:00
```
2026-02-02 18:39:18 +01:00
### Alternative: Manual Installation
2026-01-28 17:00:50 +01:00
``` bash
2026-02-02 15:20:39 +01:00
# From rtk-ai repository (NOT reachingforthejack!)
cargo install --git https://github.com/rtk-ai/rtk
# OR (if published and correct on crates.io)
2026-01-28 17:00:50 +01:00
cargo install rtk
2026-02-02 15:20:39 +01:00
# ALWAYS VERIFY after installation
rtk gain # MUST show token savings, not "command not found"
2026-01-28 17:00:50 +01:00
```
2026-02-02 15:20:39 +01:00
⚠️ **WARNING ** : `cargo install rtk` from crates.io might install the wrong package. Always verify with `rtk gain` .
2026-01-28 17:00:50 +01:00
## Project Initialization
2026-02-22 14:43:45 +01:00
### 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
```
2026-02-07 15:28:39 +01:00
### Recommended: Global Hook-First Setup
**Best for: All projects, automatic RTK usage **
``` bash
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
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
# → Prompts: "Patch settings.json? [y/N]"
# → If yes: patches + creates backup (~/.claude/settings.json.bak)
2026-02-07 15:28:39 +01:00
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
# Automated alternatives:
rtk init -g --auto-patch # Patch without prompting
rtk init -g --no-patch # Print manual instructions instead
2026-02-07 15:28:39 +01:00
# Verify installation
rtk init --show # Check hook is installed and executable
```
**Token savings ** : ~99.5% reduction (2000 tokens → 10 tokens in context)
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
**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.
2026-02-22 14:43:45 +01:00
```
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 ✓" │
│◄──────────────────────────────────────────────────────────────│
```
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
**Backup Safety ** :
RTK backs up existing settings.json before changes. Restore if needed:
``` bash
cp ~/.claude/settings.json.bak ~/.claude/settings.json
```
2026-02-07 15:28:39 +01:00
### Alternative: Local Project Setup
**Best for: Single project without hook **
2026-01-28 17:00:50 +01:00
``` bash
cd /path/to/your/project
2026-02-07 15:28:39 +01:00
rtk init # Creates ./CLAUDE.md with full RTK instructions (137 lines)
```
2026-01-28 17:00:50 +01:00
2026-02-07 15:28:39 +01:00
**Token savings ** : Instructions loaded only for this project
2026-01-28 17:00:50 +01:00
2026-02-07 15:28:39 +01:00
### Upgrading from Previous Version
feat: `rtk rewrite` — single source of truth for LLM hook rewrites (#241)
* feat: add `rtk rewrite` command — single source of truth for hook rewrites
Implements `rtk rewrite <cmd>` as the canonical rewrite engine for all
LLM hook integrations (Claude Code, Gemini CLI, future tools).
- Add `rewrite_prefixes` field to `RtkRule` in discover/registry.rs
- Add public `rewrite_command()` with compound command support (&&, ||, ;, |)
- Add `rewrite_segment()`, `rewrite_compound()`, `strip_word_prefix()` helpers
- Handle already-rtk commands (exit 0, identical output)
- Handle unsupported/ignored commands (exit 1, no output)
- Add 20 unit tests covering all branches and edge cases
- Create `src/rewrite_cmd.rs` thin CLI wrapper
- Register `Commands::Rewrite` in main.rs
- Simplify `.claude/hooks/rtk-rewrite.sh` from 357 → 60 lines
Hooks no longer need duplicate mapping logic — a single
`REWRITTEN=$(rtk rewrite "$CMD") || exit 0` handles everything.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: fix version references and module count for 0.22.2
- README.md, CLAUDE.md, ARCHITECTURE.md: 0.20.1 → 0.22.2
- ARCHITECTURE.md: module count 48 → 51 (added rewrite_cmd + 2 from master)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* ci: update hook coverage check to verify registry (not hook script)
Since PR #241, the hook delegates to `rtk rewrite` — command mappings
live in src/discover/registry.rs, not the bash hook script.
Update the "Verify hook coverage" CI step to:
- Check that the hook calls `rtk rewrite` (new architecture)
- Check that registry.rs has rewrite_prefixes for all Python/Go commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: support single `&` background operator in compound rewrites
Per feedback from @xDelph: AI agents increasingly use `cmd1 & cmd2`
for parallel execution. This commit adds support alongside existing
`&&`, `||`, `;`, and `|` operators.
Changes:
- rewrite_compound: add match arm for single `&` (after `&&` check)
- rewrite_command: add `" & "` to has_compound detection
- init: show "installed/updated" vs "already up to date" so users
know whether rtk init changed the hook on re-run
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: add Python/Go commands to rewrite registry
Add `ruff`, `pytest`, `pip`, `go`, and `golangci-lint` to both
PATTERNS and RULES in registry.rs so the CI coverage check passes
and `rtk rewrite` correctly identifies these commands.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.23.0 in README
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.23.0 in CLAUDE.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version and module count to 0.23.0/52 in ARCHITECTURE.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: address P0 review feedback on rtk-rewrite PR
P0.1 - Replace 218-line bash hook with 58-line thin delegating hook.
All rewrite logic now lives exclusively in `rtk rewrite` (Rust registry).
`rtk init` installs the thin hook via include_str!.
P0.2 - Fix `head -20 file` crash at runtime.
Generic prefix replacement produced `rtk read -20 file` (invalid clap args).
Now translates `head -N file` → `rtk read file --max-lines N` and skips
unsupported head flags (e.g. -c) by returning exit 1.
P0.3 - Add version guard in hook for rtk < 0.23.0.
Prints a warning to stderr instead of silently doing nothing.
Also adds missing registry entries vs old hook:
- gh release, cargo install
- docker run/exec/build, kubectl describe/apply
- tree, diff
474 tests pass, 0 clippy warnings.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* style: cargo fmt
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(discover): extract rules/patterns into rules.rs
Per aeppling review: registry.rs was too large (~1500 lines).
Extract all static data into src/discover/rules.rs:
- RtkRule struct (with pub fields)
- PATTERNS const array
- RULES const array
- IGNORED_PREFIXES and IGNORED_EXACT const arrays
registry.rs now contains only logic + tests.
rules.rs is the single place to add a new command mapping.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.24.0 in README
* docs: update version references to 0.24.0 in CLAUDE.md and ARCHITECTURE.md
* fix(discover): add aws and psql to rewrite registry
rtk aws and rtk psql modules exist since PR #216 but were missing
from the registry rules — rewrite was silently skipping them.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(discover): exhaustive regression tests for rewrite registry
Cover all command categories added in PR #241 and missing from
the previous test suite:
- aws / psql (PR #216 modules, gap detected during non-reg run)
- Python: ruff, pytest, python -m pytest, pip, uv pip
- Go: go test/build/vet, golangci-lint
- JS/TS: vitest, pnpm vitest, prisma, prettier, pnpm list
- Compound operators: || and ; rewrites, 4-segment chains,
mixed supported/unsupported segments, all-unsupported → None
- sudo prefix rewrite, env var prefix rewrite
- find with native flags
- Registry invariants: PATTERNS/RULES aligned, all rules valid,
all patterns are valid regex
Before: 559 tests. After: 607 tests.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(migration): document breaking change + detect outdated hook in rtk config
CHANGELOG [Unreleased]:
- Migration required: rtk init --global needed after upgrade
- Documents upgrade path and explains no immediate breakage
rtk init --show / rtk config now detects old hook (inline if-else)
vs new thin delegator (rtk rewrite) and prints actionable warning:
⚠️ Hook: ~/.claude/hooks/rtk-rewrite.sh (outdated — inline logic, not thin delegator)
→ Run `rtk init --global` to upgrade to the single source of truth hook
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update hook references for thin delegator (0.24.0)
- ARCHITECTURE.md: fix hook description (shell script → thin delegator)
- INSTALL.md: add upgrade path for old hook users (pre-0.24 breaking change)
- SECURITY.md: add registry.rs + hook files to Tier 1 critical files
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(arch): fix module count 52→55, add aws/psql/rewrite to module map
Adds aws_cmd, psql_cmd (PR #216) and rewrite_cmd (this PR) to the
Complete Module Map table. Updates total from 52 to 55 to match main.rs.
Fixes CI validate-docs.sh module count mismatch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* ci: fix hook coverage check to search rules.rs instead of registry.rs
After the PR #241 refactor, rewrite_prefixes constants moved from
registry.rs to rules.rs. Update grep to search the whole discover/
directory so it finds them in the right file.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-05 14:20:01 +01:00
#### From old 137-line CLAUDE.md injection (pre-0.22)
2026-02-07 15:28:39 +01:00
``` bash
rtk init -g # Automatically migrates to hook-first mode
# → Removes old 137-line block
# → Installs hook + RTK.md
# → Adds @RTK.md reference
2026-01-28 17:00:50 +01:00
```
feat: `rtk rewrite` — single source of truth for LLM hook rewrites (#241)
* feat: add `rtk rewrite` command — single source of truth for hook rewrites
Implements `rtk rewrite <cmd>` as the canonical rewrite engine for all
LLM hook integrations (Claude Code, Gemini CLI, future tools).
- Add `rewrite_prefixes` field to `RtkRule` in discover/registry.rs
- Add public `rewrite_command()` with compound command support (&&, ||, ;, |)
- Add `rewrite_segment()`, `rewrite_compound()`, `strip_word_prefix()` helpers
- Handle already-rtk commands (exit 0, identical output)
- Handle unsupported/ignored commands (exit 1, no output)
- Add 20 unit tests covering all branches and edge cases
- Create `src/rewrite_cmd.rs` thin CLI wrapper
- Register `Commands::Rewrite` in main.rs
- Simplify `.claude/hooks/rtk-rewrite.sh` from 357 → 60 lines
Hooks no longer need duplicate mapping logic — a single
`REWRITTEN=$(rtk rewrite "$CMD") || exit 0` handles everything.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: fix version references and module count for 0.22.2
- README.md, CLAUDE.md, ARCHITECTURE.md: 0.20.1 → 0.22.2
- ARCHITECTURE.md: module count 48 → 51 (added rewrite_cmd + 2 from master)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* ci: update hook coverage check to verify registry (not hook script)
Since PR #241, the hook delegates to `rtk rewrite` — command mappings
live in src/discover/registry.rs, not the bash hook script.
Update the "Verify hook coverage" CI step to:
- Check that the hook calls `rtk rewrite` (new architecture)
- Check that registry.rs has rewrite_prefixes for all Python/Go commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: support single `&` background operator in compound rewrites
Per feedback from @xDelph: AI agents increasingly use `cmd1 & cmd2`
for parallel execution. This commit adds support alongside existing
`&&`, `||`, `;`, and `|` operators.
Changes:
- rewrite_compound: add match arm for single `&` (after `&&` check)
- rewrite_command: add `" & "` to has_compound detection
- init: show "installed/updated" vs "already up to date" so users
know whether rtk init changed the hook on re-run
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: add Python/Go commands to rewrite registry
Add `ruff`, `pytest`, `pip`, `go`, and `golangci-lint` to both
PATTERNS and RULES in registry.rs so the CI coverage check passes
and `rtk rewrite` correctly identifies these commands.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.23.0 in README
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.23.0 in CLAUDE.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version and module count to 0.23.0/52 in ARCHITECTURE.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: address P0 review feedback on rtk-rewrite PR
P0.1 - Replace 218-line bash hook with 58-line thin delegating hook.
All rewrite logic now lives exclusively in `rtk rewrite` (Rust registry).
`rtk init` installs the thin hook via include_str!.
P0.2 - Fix `head -20 file` crash at runtime.
Generic prefix replacement produced `rtk read -20 file` (invalid clap args).
Now translates `head -N file` → `rtk read file --max-lines N` and skips
unsupported head flags (e.g. -c) by returning exit 1.
P0.3 - Add version guard in hook for rtk < 0.23.0.
Prints a warning to stderr instead of silently doing nothing.
Also adds missing registry entries vs old hook:
- gh release, cargo install
- docker run/exec/build, kubectl describe/apply
- tree, diff
474 tests pass, 0 clippy warnings.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* style: cargo fmt
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(discover): extract rules/patterns into rules.rs
Per aeppling review: registry.rs was too large (~1500 lines).
Extract all static data into src/discover/rules.rs:
- RtkRule struct (with pub fields)
- PATTERNS const array
- RULES const array
- IGNORED_PREFIXES and IGNORED_EXACT const arrays
registry.rs now contains only logic + tests.
rules.rs is the single place to add a new command mapping.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update version reference to 0.24.0 in README
* docs: update version references to 0.24.0 in CLAUDE.md and ARCHITECTURE.md
* fix(discover): add aws and psql to rewrite registry
rtk aws and rtk psql modules exist since PR #216 but were missing
from the registry rules — rewrite was silently skipping them.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(discover): exhaustive regression tests for rewrite registry
Cover all command categories added in PR #241 and missing from
the previous test suite:
- aws / psql (PR #216 modules, gap detected during non-reg run)
- Python: ruff, pytest, python -m pytest, pip, uv pip
- Go: go test/build/vet, golangci-lint
- JS/TS: vitest, pnpm vitest, prisma, prettier, pnpm list
- Compound operators: || and ; rewrites, 4-segment chains,
mixed supported/unsupported segments, all-unsupported → None
- sudo prefix rewrite, env var prefix rewrite
- find with native flags
- Registry invariants: PATTERNS/RULES aligned, all rules valid,
all patterns are valid regex
Before: 559 tests. After: 607 tests.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(migration): document breaking change + detect outdated hook in rtk config
CHANGELOG [Unreleased]:
- Migration required: rtk init --global needed after upgrade
- Documents upgrade path and explains no immediate breakage
rtk init --show / rtk config now detects old hook (inline if-else)
vs new thin delegator (rtk rewrite) and prints actionable warning:
⚠️ Hook: ~/.claude/hooks/rtk-rewrite.sh (outdated — inline logic, not thin delegator)
→ Run `rtk init --global` to upgrade to the single source of truth hook
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update hook references for thin delegator (0.24.0)
- ARCHITECTURE.md: fix hook description (shell script → thin delegator)
- INSTALL.md: add upgrade path for old hook users (pre-0.24 breaking change)
- SECURITY.md: add registry.rs + hook files to Tier 1 critical files
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(arch): fix module count 52→55, add aws/psql/rewrite to module map
Adds aws_cmd, psql_cmd (PR #216) and rewrite_cmd (this PR) to the
Complete Module Map table. Updates total from 52 to 55 to match main.rs.
Fixes CI validate-docs.sh module count mismatch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* ci: fix hook coverage check to search rules.rs instead of registry.rs
After the PR #241 refactor, rewrite_prefixes constants moved from
registry.rs to rules.rs. Update grep to search the whole discover/
directory so it finds them in the right file.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-05 14:20:01 +01:00
#### 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.
``` bash
# 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)
```
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
## Common User Flows
### First-Time User (Recommended)
``` bash
# 1. Install RTK
cargo install --git https://github.com/rtk-ai/rtk
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
``` bash
# Non-interactive setup (no prompts)
rtk init -g --auto-patch
# Verify in scripts
rtk init --show | grep "Hook:"
```
### Conservative User (Manual Control)
``` bash
# Get manual instructions without patching
rtk init -g --no-patch
# Review printed JSON snippet
# Manually edit ~/.claude/settings.json
# Restart Claude Code
```
### Temporary Trial
``` bash
# 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
```
2026-01-28 17:00:50 +01:00
## Installation Verification
``` bash
# 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
```
feat(init): auto-patch settings.json for frictionless hook installation
## Summary
Eliminates manual settings.json setup friction by automating hook
registration with safety (backup, atomic writes, idempotency).
## Changes
### Core Features
- **Auto-patch**: Default `rtk init -g` prompts to patch settings.json [y/N]
- **CLI flags**: `--auto-patch` (no prompt), `--no-patch` (manual), `--uninstall` (full cleanup)
- **Safety**: Automatic backup to `settings.json.bak` before modification
- **Idempotency**: Detects existing hook, skips modification
- **Status check**: `rtk init --show` now displays settings.json registration
### Implementation
- New types: `PatchMode` (Ask/Auto/Skip), `PatchResult` (tracking outcomes)
- New functions in `src/init.rs`:
- `hook_already_present()` - Detects RTK hook via substring match
- `insert_hook_entry()` - Deep-merges hook using idiomatic `entry()` API
- `atomic_write()` - Crash-safe writes with tempfile
- `patch_settings_json()` - Main orchestrator
- `uninstall()` - Complete cleanup (hook, RTK.md, settings.json)
- Modified functions: `run()`, `run_default_mode()`, `run_hook_only_mode()`, `show_config()`
### Code Quality Improvements
- Refactored `insert_hook_entry()` to use Rust `entry()` API (no manual unwraps)
- Simplified `hook_already_present()` with iterator chains (3x shorter)
- Improved error messages with file paths and actionable hints
- Fixed string allocation (to_str() vs to_string())
### Dependencies
- Added `preserve_order` feature to `serde_json` (key order preservation)
- Moved `tempfile` to production dependencies (atomic writes)
### Documentation
- **README.md**: Updated Quick Install, added Installation Flags, Uninstalling, Troubleshooting, What Are Hooks sections
- **INSTALL.md**: Updated Recommended Setup, added Common User Flows, Uninstalling sections
- **CHANGELOG.md**: Documented new feature under Unreleased
### Testing
- 11 new unit tests for hook detection, insertion, atomic writes, cleanup
- All 249 tests passing
- Smoke tested: install, idempotency, show, uninstall
## User Impact
**Before**: Users had to manually copy JSON snippet to settings.json
**After**: Single command with prompt, automatic backup, clean uninstall
## Breaking Changes
None. Backwards compatible - manual setup still works via `--no-patch`.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-07 16:12:40 +01:00
## Uninstalling
### Complete Removal (Global Installations Only)
``` bash
# 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
``` bash
# If installed via cargo
cargo uninstall rtk
# If installed via package manager
brew uninstall rtk # macOS Homebrew
sudo apt remove rtk # Debian/Ubuntu
sudo dnf remove rtk # Fedora/RHEL
```
### Restore from Backup (if needed)
``` bash
cp ~/.claude/settings.json.bak ~/.claude/settings.json
```
2026-01-28 17:00:50 +01:00
## Essential Commands
### Files
``` bash
rtk ls . # Compact tree view
rtk read file.rs # Optimized reading
rtk grep "pattern" . # Grouped search results
```
### Git
``` bash
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)
``` bash
rtk pnpm list # Dependency tree (-70% tokens)
rtk pnpm outdated # Available updates (-80-90%)
rtk pnpm install pkg # Silent installation
```
### Tests
``` bash
rtk test cargo test # Failures only (-90%)
rtk vitest run # Filtered Vitest output (-99.6%)
```
### Statistics
``` bash
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
``` bash
# 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)
``` bash
# 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
``` bash
# Update Rust
rustup update stable
# Clean and recompile
cargo clean
cargo build --release
cargo install --path . --force
```
## Support and Contributing
2026-02-12 12:28:37 +01:00
- **Website**: https://www.rtk-ai.app
- **Contact**: contact@rtk -ai.app
2026-02-02 15:20:39 +01:00
- **Troubleshooting**: See [TROUBLESHOOTING.md ](docs/TROUBLESHOOTING.md ) for common issues
2026-02-02 18:39:18 +01:00
- **GitHub issues**: https://github.com/rtk-ai/rtk/issues
- **Pull Requests**: https://github.com/rtk-ai/rtk/pulls
2026-01-28 17:00:50 +01:00
2026-02-02 15:20:39 +01:00
⚠️ **If you installed the wrong rtk (Type Kit) ** , see [TROUBLESHOOTING.md ](docs/TROUBLESHOOTING.md#problem-rtk-gain-command-not-found )
2026-01-28 17:00:50 +01:00
## 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).
