Skip to main content

​
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)

1

Install via Homebrew

brew install rtk
2

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)

1

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.
2

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
3

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
1

Install Rust toolchain (if needed)

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

Install RTK

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

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
1

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
2

Extract and install

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

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: This installs a hook that automatically rewrites commands across all Claude Code projects: 
rtk init --global
1

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]”
2

Answer the prompt

Patch settings.json? [y/N]: y
This registers the hook in Claude Code’s configuration file.
3

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
4

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

​
Verification

Test that RTK is working correctly: 
rtk ls .
# Should show compact tree view

​
Troubleshooting

​
Command Not Found

Problem: rtk: command not found after installation Solution:
1

Check if rtk is in PATH

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

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:
1

Verify hook is registered

rtk init --show
2

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"
          }
        ]
      }
    ]
  }
}
3

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