Skip to main content

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.
If you previously used rtk init -g with the old system (137-line injection):
Benefits of migration:
  • 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
Rollback if needed:

Migrating from v0.7.x to v0.8.0+

v0.8.0 introduced execution time tracking. Historical commands will show 0ms execution time.
Database Schema Update: RTK automatically migrates the SQLite schema when you run any rtk command after updating:
New Features:
  • rtk gain now shows total and average execution time
  • --daily breakdown includes time metrics per day
  • JSON/CSV exports include total_time_ms and avg_time_ms fields

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.
New Commands Available:
Hook Auto-Rewrite: If you’re using the auto-rewrite hook, update it:

Hook Mode Migrations

From Legacy CLAUDE.md to Hook Mode

Current Setup: Full 137-line injection in ~/.claude/CLAUDE.md Migration Steps:
What Changed:
  • ~/.claude/CLAUDE.md now has just one line: @RTK.md
  • ~/.claude/RTK.md created (10 lines, minimal context)
  • ~/.claude/hooks/rtk-rewrite.sh installed
  • ~/.claude/settings.json updated with hook registration
Rollback:

From No Hook to Hook Mode

Current Setup: Using rtk prefix manually for each command Migration Steps:
Benefits:
  • 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:
What Changed:
  • No automatic command rewriting
  • Must use rtk prefix 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.
Migration Steps:

Tee Output Recovery (v0.19.0+)

v0.19.0 introduced the tee feature for saving raw output on command failure.
Enable/Configure Tee:
Environment Overrides:

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 wc command
  • No breaking changes

v0.20.0 (2026-02-16)

  • Hook audit mode added
  • Install location changed from /usr/local/bin to ~/.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-md flag
  • Migration Recommended: Re-run rtk init -g to 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

Problem: rtk init -g reports settings.json is invalid JSON.Solution:
Problem: Error when running rtk gain after update.Solution:
Problem: Hook installed but commands not using rtk.Solution:

Need Help?

If you encounter issues during migration: Run the diagnostic script:
Report issues: Restore from backup: