Migration Guide
Guide for migrating between RTK versions, hook modes, and configuration formats.Version Migrations
Migrating to v0.9.5+ (Hook-First Mode)
v0.9.5 introduced a new hook-first installation mode that reduces context overhead from ~2000 tokens to ~10 tokens.
rtk init -g with the old system (137-line injection):
- 99.5% reduction in context overhead (~2000 tokens → ~10 tokens)
- Automatic command rewriting via hook
- No changes to your workflow
- Backward compatible with existing projects
Migrating from v0.7.x to v0.8.0+
Database Schema Update: RTK automatically migrates the SQLite schema when you run anyrtk command after updating:
rtk gainnow shows total and average execution time--dailybreakdown includes time metrics per day- JSON/CSV exports include
total_time_msandavg_time_msfields
Migrating from v0.15.x to v0.16.0+ (Python & Go Support)
v0.15.0+ added Python (ruff, pytest, pip) and Go (test, build, vet, golangci-lint) support.
Hook Mode Migrations
From Legacy CLAUDE.md to Hook Mode
Current Setup: Full 137-line injection in~/.claude/CLAUDE.md
Migration Steps:
~/.claude/CLAUDE.mdnow has just one line:@RTK.md~/.claude/RTK.mdcreated (10 lines, minimal context)~/.claude/hooks/rtk-rewrite.shinstalled~/.claude/settings.jsonupdated with hook registration
From No Hook to Hook Mode
Current Setup: Usingrtk prefix manually for each command
Migration Steps:
- No need to remember rtk prefix
- 100% adoption (hook applies to all commands)
- Works across all conversations and subagents
From Hook Mode to Manual Mode
If you prefer explicit control:- No automatic command rewriting
- Must use
rtkprefix explicitly - Full context available in CLAUDE.md (~2000 tokens)
Configuration Migrations
Custom Database Location
v0.13.0+ supports custom database paths via environment variable or config file.
Tee Output Recovery (v0.19.0+)
v0.19.0 introduced the tee feature for saving raw output on command failure.
Breaking Changes by Version
v0.24.0 (2026-03-04)
- Added hook integrity verification (SHA-256)
- Git exit codes now properly propagated
- No migration required
v0.22.0 (2026-02-18)
- Added
rtk wccommand - No breaking changes
v0.20.0 (2026-02-16)
- Hook audit mode added
- Install location changed from
/usr/local/binto~/.local/bin - Action Required: Update PATH if using manual installation
v0.15.0 (2026-02-12)
- Python and Go support added
- Cargo test output aggregated to single line
- No breaking changes for existing commands
v0.10.0 (2026-02-07)
- Hook-first installation introduced
- Legacy full injection still supported via
--claude-mdflag - Migration Recommended: Re-run
rtk init -gto reduce context overhead
v0.8.0 (2026-02-02)
- Execution time tracking added to database
- Database Migration: Automatic on first run
- Historical data shows 0ms for pre-v0.8.0 commands
Uninstall and Reinstall
Complete RTK Removal
Fresh Installation
Troubleshooting Migration Issues
Migration failed: settings.json invalid
Migration failed: settings.json invalid
Problem:
rtk init -g reports settings.json is invalid JSON.Solution:Database migration failed
Database migration failed
Problem: Error when running
rtk gain after update.Solution:Hook not working after migration
Hook not working after migration
Problem: Hook installed but commands not using rtk.Solution:
Need Help?
If you encounter issues during migration: Run the diagnostic script:- GitHub: https://github.com/rtk-ai/rtk/issues
- Email: contact@rtk-ai.app
