> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtk-ai/rtk/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install RTK on macOS, Linux, or Windows in under 5 minutes

# Installation

> [!WARNING]
>
> **Pre-Installation Check Required**
>
> Always verify if RTK is already installed before proceeding:
>
> ```bash theme={null}
> 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](#project-initialization).**

## Installation Methods

Choose the method that works best for your platform:

> **Homebrew**
>
> **Recommended for macOS/Linux**
>
> Easiest installation method with automatic updates.

> **Quick Install Script**
>
> **Fast one-liner for Linux/macOS**
>
> Downloads and installs to `~/.local/bin`.

> **Cargo**
>
> **For Rust developers**
>
> Build from source or install from crates.io.

> **Pre-built Binaries**
>
> **Manual installation**
>
> Download compiled binaries for all platforms.

### Homebrew (macOS/Linux)

**1. Install via Homebrew**

```bash theme={null}
brew install rtk
```

**2. Verify installation**

```bash theme={null}
rtk --version
# Output: rtk 0.24.0

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

> [!NOTE]
>
> 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**

```bash theme={null}
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 bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

```bash zsh theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**3. Verify installation**

```bash theme={null}
rtk gain  # Must show token stats, not "command not found"
```

### Cargo (from source)

> [!WARNING]
>
> **Name Collision on crates.io**
>
> `cargo 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.

```bash From GitHub (Recommended) theme={null}
cargo install --git https://github.com/rtk-ai/rtk
```

```bash From crates.io (Verify After!) theme={null}
cargo install rtk

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

**1. Install Rust toolchain (if needed)**

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

**2. Install RTK**

```bash theme={null}
cargo install --git https://github.com/rtk-ai/rtk
```

**3. Verify installation**

```bash theme={null}
rtk --version
rtk gain
```

### Pre-built Binaries

Download pre-compiled binaries from [GitHub Releases](https://github.com/rtk-ai/rtk/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**

```bash macOS (Intel) theme={null}
curl -L -o rtk.tar.gz https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-apple-darwin.tar.gz
```

```bash macOS (Apple Silicon) theme={null}
curl -L -o rtk.tar.gz https://github.com/rtk-ai/rtk/releases/latest/download/rtk-aarch64-apple-darwin.tar.gz
```

```bash Linux (x86_64) theme={null}
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**

```bash theme={null}
tar -xzf rtk.tar.gz
mkdir -p ~/.local/bin
mv rtk ~/.local/bin/
chmod +x ~/.local/bin/rtk
```

**3. Add to PATH (if needed)**

```bash theme={null}
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:

```bash theme={null}
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**

```bash theme={null}
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.

> [!NOTE]
>
> **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

```bash Auto-patch (CI/CD) theme={null}
# Patch without prompting
rtk init --global --auto-patch
```

```bash Manual instructions theme={null}
# Print JSON snippet without patching
rtk init --global --no-patch

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

```bash Local project only theme={null}
# No hook, just creates ./CLAUDE.md
rtk init
```

## Verification

Test that RTK is working correctly:

```bash Basic test theme={null}
rtk ls .
# Should show compact tree view
```

```bash Git test theme={null}
rtk git status
# Should show ultra-compact status
```

```bash Hook test (if installed) theme={null}
git status
# Should automatically use rtk (after restart)
```

```bash Analytics test theme={null}
rtk gain
# Should show "No tracking data yet" or stats
```

## Troubleshooting

### Command Not Found

**Problem:** `rtk: command not found` after installation

**Solution:**

**1. Check if rtk is in PATH**

```bash theme={null}
which rtk
ls ~/.local/bin/rtk
ls ~/.cargo/bin/rtk
```

**2. Add to PATH**

```bash bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

```bash zsh theme={null}
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

```bash theme={null}
# 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**

```bash theme={null}
rtk init --show
```

**2. Check settings.json**

```bash theme={null}
cat ~/.claude/settings.json | grep rtk-rewrite
```

Should contain:

```json theme={null}
{
  "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:**

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
cp ~/.claude/settings.json.bak ~/.claude/settings.json
```

## Next Steps

> **[Quick Start Guide](/quickstart)**
>
> Follow our 5-minute guide to start saving tokens immediately


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.