RTK 101: Cut Your Claude Token Usage by 80%

Every time Claude runs git status, cargo test, or cat on a large file, it reads the full raw output — timestamps, blank lines, progress bars, ASCII art, decorative separators, and all. You’re paying tokens for noise your AI never needed.

RTK is a single Rust binary that sits between your shell and your LLM. It intercepts common dev commands and returns a compressed version of their output — same signal, far fewer tokens. A 30-minute Claude Code session that would consume ~118,000 tokens drops to ~24,000.

This guide gets you running in under five minutes.

Install

Pick the method that fits your setup:

# Homebrew (recommended)
brew install rtk

# curl (Linux / macOS without Homebrew)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

# Cargo (from source)
cargo install --git https://github.com/rtk-ai/rtk

⚠️ Warning: There is another unrelated package called “rtk” on crates.io. If rtk gain fails after cargo install rtk, you installed the wrong one. Use the --git flag shown above instead.

If you used the curl installer, add the binary to your PATH:

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

Verify the install:

rtk --version   # rtk 0.28.x
rtk gain        # Shows token savings stats (empty on first run)

Wire It to Claude Code

This is the step that makes RTK automatic — a hook that transparently rewrites Bash commands before Claude ever sees the output.

rtk init --global

Follow the on-screen instructions to register the hook in ~/.claude/settings.json. Then restart Claude Code.

That’s it. Claude will now run git status and get back a 200-token summary instead of a 2,000-token wall.

💡 Pro tip: The hook only applies to Bash tool calls. Claude Code’s native Read, Grep, and Glob tools bypass it. For those workflows, use shell equivalents (cat, rg, find) or call RTK commands explicitly.

Verify the hook is active:

rtk init --show

What Gets Compressed

You don’t need to change any habits. Once the hook is installed, these rewrites happen silently:

You type	Claude receives
`git status`	Compact summary, ~200 tokens
`git diff`	Condensed diff, ~75% shorter
`git push`	`ok main`
`cargo test`	Failures only, -90%
`npm test`	Failures only, -90%
`ls`	Token-optimized tree
`cat file.rs`	Smart file read
`rg "pattern"`	Grouped search results
`docker ps`	Compact container list

The full rewrite table covers 30+ commands across git, GitHub CLI, test runners, linters, build tools, package managers, and containers.

Useful Commands to Know

Even with the hook active, you can call RTK directly for more control:

# Files
rtk read file.ts                  # Smart file read
rtk read file.ts -l aggressive    # Signatures only (strips function bodies)
rtk ls .                          # Token-optimized directory tree
rtk grep "TODO" .                 # Grouped search results

# Git
rtk git log -n 10                 # One-line commits
rtk git diff                      # Condensed diff

# Tests & builds (failures only)
rtk test cargo test
rtk test npm test
rtk tsc                           # TypeScript errors grouped by file
rtk lint                          # ESLint grouped by rule

# Analytics
rtk gain                          # Token savings summary
rtk gain --graph                  # ASCII graph (last 30 days)
rtk discover                      # Find commands where you're still wasting tokens

Check Your Savings

After a few Claude sessions, run:

rtk gain
rtk gain --graph
rtk gain --history

You’ll see a breakdown by command, day, and project. rtk discover will also surface any commands that are still passing through uncompressed — handy for finding gaps.

FAQ

Does RTK change the actual command output? Could it hide errors? No. RTK filters presentation noise (whitespace, progress bars, decorative output) but preserves all meaningful content — errors, warnings, file paths, line numbers. When a command fails, RTK saves the full unfiltered output and tells Claude where to find it, so nothing is lost.

Does it work with AI tools other than Claude Code? Yes. RTK supports Gemini CLI (rtk init -g --gemini) and OpenCode (rtk init -g --opencode) with separate hook installers for each.

Will it break commands that use the raw output? The hook only applies to Bash tool calls made by the AI agent. Your own terminal sessions are unaffected. RTK also passes through heredocs, pipes, and unrecognized commands unchanged.

What if I want to temporarily disable it? You can exclude specific commands via ~/.config/rtk/config.toml:

[hooks]
exclude_commands = ["curl", "playwright"]

Or uninstall the hook entirely with rtk init -g --uninstall without removing the binary.

I’m on Windows — does it work? Pre-built Windows binaries are available on the releases page (rtk-x86_64-pc-windows-msvc.zip), but the Claude Code hook setup is designed for macOS and Linux. Windows support is partial.

Is there any latency overhead? RTK adds less than 10ms to each command. You won’t notice it.

Sources

RTK on GitHub — official repository and README