Installation

Pre-Installation Check RequiredAlways verify if RTK is already installed before proceeding:

rtk --version        # Check if installed
rtk gain             # Verify it's the Token Killer (not Type Kit)
which rtk            # Check installation path

If rtk gain works, you already have the correct RTK. Skip to Project Initialization.

Installation Methods

Choose the method that works best for your platform:

Homebrew

Recommended for macOS/LinuxEasiest installation method with automatic updates.

Quick Install Script

Fast one-liner for Linux/macOSDownloads and installs to ~/.local/bin.

Cargo

For Rust developersBuild from source or install from crates.io.

Pre-built Binaries

Manual installationDownload compiled binaries for all platforms.

Homebrew (macOS/Linux)

Install via Homebrew

brew install rtk

Verify installation

rtk --version
# Output: rtk 0.24.0

rtk gain
# Output: No tracking data yet. (this is correct!)

If rtk gain shows token savings stats OR says “No tracking data yet”, you have the correct RTK installed.If you get “command not found”, you have the wrong package.

Quick Install Script (Linux/macOS)

Run the install script

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

This installs RTK to ~/.local/bin/rtk by default.

Add to PATH if needed

If rtk --version fails after installation, add ~/.local/bin to your PATH:

bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify installation

rtk gain  # Must show token stats, not "command not found"

Cargo (from source)

Name Collision on crates.iocargo install rtk from crates.io might install the wrong package (Rust Type Kit instead of Token Killer).Always install from the GitHub repository or verify with rtk gain after installation.

cargo install --git https://github.com/rtk-ai/rtk

cargo install rtk

# CRITICAL: Verify you got the right package
rtk gain  # Must show token stats

Install Rust toolchain (if needed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Install RTK

cargo install --git https://github.com/rtk-ai/rtk

Verify installation

rtk --version
rtk gain

Pre-built Binaries

Download pre-compiled binaries from GitHub Releases:

macOS Intel

rtk-x86_64-apple-darwin.tar.gz

macOS Apple Silicon

rtk-aarch64-apple-darwin.tar.gz

Linux x86_64

rtk-x86_64-unknown-linux-gnu.tar.gz

Linux ARM64

rtk-aarch64-unknown-linux-gnu.tar.gz

Windows x86_64

rtk-x86_64-pc-windows-msvc.zip

Download the appropriate binary

macOS (Intel)

curl -L -o rtk.tar.gz https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-apple-darwin.tar.gz

macOS (Apple Silicon)

curl -L -o rtk.tar.gz https://github.com/rtk-ai/rtk/releases/latest/download/rtk-aarch64-apple-darwin.tar.gz

Linux (x86_64)

curl -L -o rtk.tar.gz https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-unknown-linux-gnu.tar.gz

Extract and install

tar -xzf rtk.tar.gz
mkdir -p ~/.local/bin
mv rtk ~/.local/bin/
chmod +x ~/.local/bin/rtk

Add to PATH (if needed)

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Project Initialization

After installation, initialize RTK for your AI coding assistant:

Global Setup (Recommended)

This installs a hook that automatically rewrites commands across all Claude Code projects:

rtk init --global

What happens during init

Installs hook to ~/.claude/hooks/rtk-rewrite.sh
Creates ~/.claude/RTK.md (10 lines, minimal context)
Adds @RTK.md reference to ~/.claude/CLAUDE.md
Prompts: “Patch settings.json? [y/N]”

Answer the prompt

Patch settings.json? [y/N]: y

This registers the hook in Claude Code’s configuration file.

Verify installation

rtk init --show

Should show:

Hook: ✓ Installed at ~/.claude/hooks/rtk-rewrite.sh (executable)
RTK.md: ✓ Exists at ~/.claude/RTK.md
CLAUDE.md: ✓ Contains @RTK.md reference
settings.json: ✓ Hook registered

Restart Claude Code

The hook only takes effect after restarting Claude Code.

What is settings.json?Claude Code’s configuration file (~/.claude/settings.json) that registers hooks. The RTK hook transparently rewrites commands like git status → rtk git status before execution.RTK creates a backup at ~/.claude/settings.json.bak before making changes.

Alternative: Non-Interactive Setup

# Patch without prompting
rtk init --global --auto-patch

# Print JSON snippet without patching
rtk init --global --no-patch

# Then manually edit ~/.claude/settings.json

# No hook, just creates ./CLAUDE.md
rtk init

Verification

Test that RTK is working correctly:

rtk ls .
# Should show compact tree view

rtk git status
# Should show ultra-compact status

git status
# Should automatically use rtk (after restart)

rtk gain
# Should show "No tracking data yet" or stats

Troubleshooting

Command Not Found

Problem: rtk: command not found after installation Solution:

Check if rtk is in PATH

which rtk
ls ~/.local/bin/rtk
ls ~/.cargo/bin/rtk

Add to PATH

bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Wrong RTK Installed

Problem: rtk gain says “command not found” but rtk --version works Solution: You installed Rust Type Kit instead of Token Killer

# Uninstall wrong rtk
cargo uninstall rtk

# Install correct rtk from GitHub
cargo install --git https://github.com/rtk-ai/rtk

# Verify
rtk gain  # Should work now

Hook Not Working

Problem: Commands still not using RTK after rtk init --global Solution:

Verify hook is registered

rtk init --show

Check settings.json

cat ~/.claude/settings.json | grep rtk-rewrite

Should contain:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/rtk-rewrite.sh"
          }
        ]
      }
    ]
  }
}

Restart Claude Code

Hooks require a full restart to take effect.

Settings.json Patching Failed

Problem: rtk init --global fails to patch settings.json Solution:

# Check if settings.json is valid JSON
cat ~/.claude/settings.json | python3 -m json.tool

# If corrupt, restore from backup
cp ~/.claude/settings.json.bak ~/.claude/settings.json

# Or use manual patching
rtk init --global --no-patch
# Then manually edit ~/.claude/settings.json

Platform-Specific Notes

macOS

Homebrew is the recommended installation method
Use Apple Silicon binary (aarch64) on M1/M2/M3 Macs
First run may trigger Gatekeeper - allow in System Preferences → Security

Linux

Quick install script works on all distros
For DEB-based distros (Ubuntu, Debian): Download .deb from releases
For RPM-based distros (Fedora, RHEL): Download .rpm from releases
Ensure ~/.local/bin is in PATH

Windows

Download Windows binary from releases
Extract to a permanent location (e.g., C:\Program Files\rtk)
Add to PATH via System Properties → Environment Variables
RTK has limited Windows testing - report issues on GitHub

Uninstalling

Complete Removal

# Remove global hook and configuration
rtk init --global --uninstall

# Restart Claude Code

# Uninstall binary
cargo uninstall rtk        # If installed via cargo
brew uninstall rtk         # If installed via Homebrew
rm ~/.local/bin/rtk        # If installed manually

Restore Settings.json

If something goes wrong:

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

Next Steps

Quick Start Guide

Follow our 5-minute guide to start saving tokens immediately

​Installation

​Installation Methods

Homebrew

Quick Install Script

Cargo

Pre-built Binaries

​Homebrew (macOS/Linux)

​Quick Install Script (Linux/macOS)

​Cargo (from source)

​Pre-built Binaries

macOS Intel

macOS Apple Silicon

Linux x86_64

Linux ARM64

Windows x86_64

​Project Initialization

​Global Setup (Recommended)

​Alternative: Non-Interactive Setup

​Verification

​Troubleshooting

​Command Not Found

​Wrong RTK Installed

​Hook Not Working

​Settings.json Patching Failed

​Platform-Specific Notes

​macOS

​Linux

​Windows

​Uninstalling

​Complete Removal

​Restore Settings.json

​Next Steps

Quick Start Guide

Installation

Installation Methods

Homebrew (macOS/Linux)

Quick Install Script (Linux/macOS)

Cargo (from source)

Pre-built Binaries

Project Initialization

Global Setup (Recommended)

Alternative: Non-Interactive Setup

Verification

Troubleshooting

Command Not Found

Wrong RTK Installed

Hook Not Working

Settings.json Patching Failed

Platform-Specific Notes

macOS

Linux

Windows

Uninstalling

Complete Removal

Restore Settings.json

Next Steps