AI Token Optimization with RTK

Cut AI token waste by hooking RTK into Claude Code to compress command output.

Introduction

30 Second Summary

Every time an AI coding assistant runs a terminal command, it reads every single line of output. Most of that output is filler that eats into the AI's limited memory for your conversation.

In this project, you will set up RTK (Rust Token Killer) to automatically compress terminal output before your AI coding assistant reads it. You'll measure the exact savings with a built-in analytics dashboard.

What You'll Build

You'll watch Claude Code run terminal commands before and after hooking in RTK, see verbose output shrink to a crisp summary, then pull up your personal savings dashboard to prove exactly how many tokens you saved.

By the end of this project, you'll have:

Launch any Claude Code session and watch RTK automatically compress every shell command's output before the AI reads it.
Compare before-and-after output from the same terminal commands to see exactly how much noise RTK strips from the AI's context window.
Pull up a savings dashboard anytime to check your cumulative token savings across every command.
Secret Mission: Unlock RTK's power features including aggressive file reading, ultra-compact mode, and missed-savings discovery.

Are there any prerequisites?

You need a Mac computer with internet access. You also need a Claude subscription (Pro, Max, Team, or Enterprise) or an Anthropic Console account with API credits to use Claude Code.

Before We Start

Before you dive in, take a moment to think about what you're building and why it matters for your AI-powered development workflow. You'll be setting up RTK to work alongside Claude Code, compressing noisy terminal output so your AI coding agent spends its limited context window on what actually matters.

Install Your Toolkit

Before you can start saving tokens, you need three tools working together on your Mac.

Homebrew manages package installations on macOS. Claude Code is the AI coding agent that runs in your terminal. RTK is the proxy that sits between Claude Code and the shell, compressing command output before the AI ever sees it.

In this step, get ready to:

Install Homebrew as your package manager.
Install Claude Code and log into your Claude account.
Install RTK and verify it with the savings dashboard.

Install Homebrew

Homebrew is a package manager for macOS that lets you install tools from the command line. You need it to install RTK later in this step.

Press Cmd+Space to open Spotlight search.
Type Terminal and press Enter to open it.
Check if Homebrew is already installed by running this command:

brew --version

✔️ I see a version number

Homebrew is already installed on your Mac. You can skip ahead to the next substep.

ⓧ Command not found

Homebrew is not installed yet. No worries. Install it by pasting this command into Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What does this command do?

This downloads and runs the official Homebrew installer from GitHub. The script will explain what it plans to do and pause before making changes. You will need to press Enter to confirm, and you may be asked for your Mac password.

Wait for the installation to finish. It may take a few minutes.
When the installer finishes, look for a Next steps section in the Terminal output. It will print one or two commands you need to run to add Homebrew to your PATH. Copy and paste those exact commands into Terminal and press Enter.
Verify Homebrew is working by running:

brew --version

You should see a version number printed in your Terminal.

Still seeing command not found?

The most common cause is skipping the PATH commands from the Next steps section. Scroll up in your Terminal output and look for lines starting with eval or echo. Copy and run them, then try brew --version again.

If you still have trouble, help me troubleshoot my Homebrew installation on macOS.

Install Claude Code

Claude Code is the AI coding agent you will pair RTK with. It runs directly in your terminal and requires a Claude subscription or Anthropic Console account.

Install Claude Code by running the official install script:

curl -fsSL https://claude.ai/install.sh | bash

What does this command do?

This downloads and runs Anthropic's official installer for Claude Code. Native installations auto-update in the background, so you will always have the latest version.

Once the install finishes, launch Claude Code for the first time by running:

claude

What happens on first launch?

Claude Code will prompt you to log in. It opens your browser so you can authenticate with your Claude account (Pro, Max, Team, or Enterprise) or your Anthropic Console account. Follow the prompts in your browser to complete the login, then return to Terminal.

Once logged in, your credentials are stored and you will not need to log in again.

Complete the login in your browser.
Return to Terminal. You should see the Claude Code interface ready for input.
Exit Claude Code for now by pressing Ctrl+C or typing /exit.

Claude Code not launching?

If claude is not recognized, close and reopen your Terminal so your shell picks up the new PATH entry from the installer.

If you see an authentication error, make sure you have an active Claude subscription or Anthropic Console account with API credits. Help me troubleshoot my Claude Code login.

Install RTK

Now that Homebrew and Claude Code are working, you can install RTK. RTK stands for Rust Token Killer. It compresses terminal output so your AI coding agent reads fewer tokens.

Install RTK using Homebrew by running:

brew install rtk-ai/tap/rtk

Why this specific tap?

The rtk-ai/tap/rtk path installs RTK from its official Homebrew tap. A different, unrelated project called "Rust Type Kit" also uses the name rtk on other package registries. Using the full tap path ensures you get the right tool.

Verify RTK installed correctly by checking the version:

rtk --version

You should see a version number printed in your Terminal.

Before you check the savings dashboard, what do you think it will show? You have not used RTK yet. Take a guess, then run:

rtk gain

The dashboard shows all zeros across the board. That is exactly right. You have not processed any commands through RTK yet, so there are no savings to report.

rtk gain showing an error?

If rtk gain fails or shows unexpected output, you may have the wrong package installed. A different project called "Rust Type Kit" also uses the name rtk. Uninstall it with cargo uninstall rtk and then reinstall using the Homebrew command above.

If you are still having trouble, help me troubleshoot my RTK installation.

Your toolkit is locked and loaded. Next up, you will create a test project using Claude Code so you have real files and Git history to work with.

Create a Test Project with Claude Code

Your toolkit is ready to go. Homebrew, Claude Code, and RTK are all installed and verified.

To see RTK in action later, you first need a real project with files and Git history that generates noisy terminal output. In this step, you'll use Claude Code for the first time to scaffold a sample web project.

In this step, get ready to:

Create a project directory and initialize it as a Git repository.
Use Claude Code to generate a sample web project with multiple files.
Build a Git commit history with at least 3 commits.

Create the project directory and initialize Git

Create your project directory, navigate into it, and initialize Git by running these commands:

mkdir ~/rtk-test-project && cd ~/rtk-test-project && git init

You should see a message from Git confirming that an empty repository was initialized.

Don't see the confirmation?

If you see a prompt asking to install developer tools or command line tools, click Install and wait for the installation to finish. Then run the commands above again.
If you see an error that the directory already exists from a previous attempt, remove it first by running rm -rf ~/rtk-test-project, then try the commands again.
Why can't I initialize a Git repository?

Generate project files with Claude Code

Claude Code is an interactive AI assistant that runs directly in your Terminal. You type prompts, and it creates real files on your computer.

Launch Claude Code inside your project by running:

claude

What will Claude Code look like?

Claude Code takes over your Terminal window with its own interface. You'll see a text prompt where you can type messages to the AI.

Before creating or editing any file, Claude Code will ask for your permission. You can accept individually or allow all edits for the session.

Type this prompt into Claude Code and press Enter:

Create a small sample web project with an index.html, a style.css, a script.js, a README.md, and a src/ subdirectory with at least 3 more files inside it.

Each time Claude Code asks for permission to create a file, accept the request.
Once all the files are created, exit Claude Code by typing /exit and pressing Enter.

You're now back in your regular Terminal inside ~/rtk-test-project.

Confirm the project files exist by running:

ls

You should see index.html, style.css, script.js, README.md, and a src directory listed.

Check inside the src directory by running:

ls src

You should see at least 3 files listed.

Missing some files?

If some files are missing, launch Claude Code again with claude and ask it to create the specific files you need.
If the src directory is empty or missing, ask Claude Code to create it with files inside it. Be specific about the subdirectory name.
Claude Code didn't create all my project files. What should I do?

Commit your files and build Git history

Your project has files, but Git isn't tracking them yet. You need commits so that commands like git log and git status generate real, multi-line output you can compress with RTK later.

Stage all your files and create your first commit by running:

git add -A && git commit -m "Initial project setup"

You should see a summary listing all the files Git just committed.

Git asking for your identity?

If Git displays an error about your identity not being configured, set your name and email by running these commands:

git config --global user.name "[[YOUR_NAME="your name"]]"
git config --global user.email "[[YOUR_EMAIL="your email address"]]"

Then run the commit command again.

Why is Git asking me to configure my identity?

Build more Git history by making two small edits and committing each one. Run these commands:

echo "<!-- Added a comment -->" >> index.html
git add -A && git commit -m "Add comment to index.html"

echo "// Updated script" >> script.js
git add -A && git commit -m "Update script.js"

Why do we need multiple commits?

Commands like git log produce longer output when there are more commits in the history. Each commit adds author info, timestamps, and full hashes to the log.

That verbosity is exactly the kind of noise that RTK compresses. The more history your project has, the more dramatic the before-and-after comparison will be.

Time to verify your project is ready. How many commits do you think are in your Git history right now?

Check your commit history by running:

git log --oneline

You should see 3 commits listed, one per line.

Verify your full set of project files by running:

find . -type f -not -path './.git/*'

You should see at least 8 files listed across your project directories.

Your test project is loaded with files, folders, and Git history. Next up, you'll run some common commands and see just how much noisy output they dump into the AI's reading list.

See How Much Output Claude Code Reads

Your test project is set up with real files, subdirectories, and Git history. That's exactly the kind of project that generates noisy terminal output when you run everyday commands.

Right now, every command Claude Code runs feeds its full, unfiltered output into the AI's context window. Before hooking RTK in, let's see what that noise actually looks like.

In this step, get ready to:

Run file listing commands and observe verbose metadata that an AI doesn't need.
Run Git commands and see the noisy output the AI would read as tokens.
Calculate rough token costs to understand the scale of waste across a coding session.

List your project files and count the noise

Simple commands like ls and find are some of the most common commands an AI coding agent runs. Let's see what their raw output looks like.

In your Terminal, make sure you're in the test project by running:

cd ~/rtk-test-project

List all files with their full details by running:

ls -la

Count the lines. Each line includes permission strings, owner names, file sizes, and timestamps. A human might scan these columns and ignore what they don't need, but an AI reads every character.

Now list every file recursively by running:

find . -type f

Count these lines too. You'll see every file path listed individually, including Git internal files inside the .git/ directory. For a small project with 8-10 files, this command can easily produce 30+ lines of output.

Why does this matter for AI?

AI models break text into chunks called tokens. Each token is roughly 4 characters. Every line of permission strings, timestamps, and file sizes is noise that costs tokens but gives the AI no useful information about your code.

Run Git commands and count the noise

Git commands are some of the biggest noise producers. AI coding agents run them constantly to understand your project's state and history.

Check the current Git status by running:

git status

Notice the header lines, branch name, and boilerplate formatting. The actual information ("nothing to commit, working tree clean") could fit in a few words, but the full output wraps it in several lines of decoration.

Before you run the next command, think about how many lines you'd expect 3 commits to produce in a full Git log. Take a guess.

View the full Git log by running:

git log

Even with just 3 commits, the output spans 15+ lines. Each commit includes a 40-character SHA hash, author name, email address, date, and the commit message on separate lines.

What is a context window?

Every AI model has a fixed-size context window. It's the total amount of text (measured in tokens) the model can consider at once. Your prompts, the AI's responses, system instructions, and all command output compete for space in that window.

That 15-line Git log is roughly 100+ tokens. The more noise fills the window, the less room the AI has for your actual code and prompts.

Calculate the token cost of file reads

Listing files and checking Git status are short commands. What happens when the AI reads entire files?

Read the contents of your README file by running:

cat README.md

Estimate the rough token count by dividing the number of characters by 4. A 2,000-character file is roughly 500 tokens. A 4,000-character file is roughly 1,000 tokens.

How does the noise add up?

A single coding session with Claude Code can involve dozens of commands. Each one dumps 15-30+ lines of verbose output. Multiply that across git status, git log, file reads, directory listings, and more. Thousands of tokens spent on boilerplate the AI never needed.

That's the problem RTK solves. It compresses this output before the AI ever sees it, keeping the useful information and stripping the noise.

You've seen the noise firsthand. Permission strings, full SHA hashes, author metadata, timestamps, boilerplate headers. All of it gets fed straight into the AI's context window as tokens. Next up, you'll hook RTK into Claude Code and watch the same commands produce dramatically compressed results.

Hook RTK into Claude Code

In the previous step, you saw how much noise raw terminal output carries. Permission strings, full commit hashes, timestamps, author info. Every character becomes a token that Claude Code processes and counts against its context window.

RTK's auto-rewrite hook fixes this by intercepting every Bash command Claude Code runs and compressing the output before the AI ever sees it. In this step, you'll install the hook with a single command and watch the same noisy commands produce dramatically shorter results.

In this step, get ready to:

Install RTK's global PreToolUse hook into Claude Code.
Restart Claude Code so the hook takes effect.
Compare the compressed output to the verbose output from the previous step.

Install RTK's global hook

RTK uses a PreToolUse hook to sit between Claude Code and the terminal. Every time Claude Code fires a Bash command, this hook intercepts it, rewrites it to the RTK equivalent, and returns compressed output.

Install RTK's global hook by running this command in your Terminal:

rtk init -g

What does this command do?

The -g flag installs the hook globally, meaning it applies to every Claude Code project on your machine. Without -g, the hook would only apply to the current project.

Behind the scenes, RTK writes a small hook script, patches Claude Code's settings.json to register the hook, and creates a slim RTK.md awareness file.

You'll see a prompt

RTK will ask you to patch settings.json. Type y and press Enter to accept. This is what registers the hook so Claude Code invokes it automatically.

Verify the hook is installed by running:

rtk init --show

You should see a status line confirming the hook is installed and up to date.

Not seeing the hook listed?

Make sure you typed y when RTK asked to patch settings.json. Without that, the hook script exists but Claude Code doesn't know to invoke it.
If you accidentally skipped the prompt, run rtk init -g again and accept the patch this time.
help me troubleshoot the RTK hook installation for Claude Code

Restart Claude Code with the hook active

Claude Code needs a restart to pick up the new hook. The hook only activates when Claude Code launches fresh.

If Claude Code is currently running, exit it by pressing Ctrl+C or typing /exit.
Make sure you're in your test project directory. Switch back to it if needed by running:

cd ~/rtk-test-project

Launch Claude Code inside the project by running:

claude

The Claude Code interface opens in your Terminal. The RTK hook is now active behind the scenes, ready to compress any Bash output.

Claude Code not launching?

If you see a login prompt, follow the browser flow to sign in again. Claude Code sessions can expire.
Make sure you fully exited the previous Claude Code session before relaunching. Running claude while another session is open in the same terminal can cause issues.
help me get Claude Code running again in my terminal

See the compressed output in action

Before you ask Claude Code to run any commands, think back to the raw output you saw in the previous step. What do you think git status will look like now that RTK is compressing it?

In the Claude Code prompt, type this message and press Enter:

Show me the git status, list the files, and read the README.

When Claude Code asks for permission to run commands, accept each one.

Watch the output closely. Commands like git status now get rewritten to rtk git status behind the scenes. The output Claude Code receives is dramatically shorter and more compact than what you saw in the previous step.

How does the rewrite work?

When Claude Code fires a Bash command, the PreToolUse hook intercepts it before execution. The hook calls rtk rewrite to translate the command. For example, git status becomes rtk git status.

RTK then applies four compression strategies: smart filtering removes noise, grouping aggregates similar items, truncation keeps only relevant context, and deduplication collapses repeated lines. The AI gets a crisp summary instead of a wall of text.

What about Claude Code's built-in tools?

The hook only intercepts Bash tool calls. Claude Code's built-in tools (Read, Grep, Glob) bypass the hook entirely because they don't use the Bash shell. If Claude Code uses its Read tool instead of cat to read a file, RTK can't compress that output. You'll explore this gap in the Secret Mission.

Output doesn't look any shorter?

Run rtk init --show in a separate Terminal window to double-check the hook is installed. If it shows the hook is missing, run rtk init -g again.
Make sure you fully exited and relaunched Claude Code after installing the hook. The hook only loads at startup.
If Claude Code used its built-in Read tool instead of cat for the README, that output won't be compressed. Try asking Claude Code to run git status specifically to see RTK's compression on a Bash command.
help me figure out why RTK isn't compressing output in Claude Code

Every Bash command Claude Code runs is now automatically compressed. Next up, you'll measure exactly how many tokens you've saved with RTK's built-in analytics dashboard.

Check Your Token Savings

You saw RTK compress command output right before Claude Code's eyes. The text looked shorter, but by how much exactly?

RTK tracks every command it processes and calculates token savings automatically. In this step, you'll pull up RTK's built-in analytics dashboard to see the precise numbers and prove the compression is working.

In this step, get ready to:

View your total token savings on RTK's dashboard.
Inspect per-command token savings to see which commands benefit most.
Track your savings over time with daily breakdowns and graphs.

View your savings dashboard

Seeing shorter output is one thing. Measuring the exact savings proves RTK is doing its job.

Exit Claude Code if it's still running by pressing Ctrl+C or typing /exit.

Before you run the next command, take a guess: what percentage of tokens do you think RTK saved from the commands Claude Code ran in your last session?

Pull up your savings dashboard by running this command:

rtk gain

You'll see a summary dashboard showing your total commands processed, input tokens, output tokens, tokens saved, and the overall savings percentage.

What do these numbers mean?

The input tokens count shows how many tokens the raw command output would have consumed. The output tokens count shows how many tokens the compressed version actually used.

The difference between them is the tokens saved. Even from a short session, you should see some savings here.

Are these exact token counts?

RTK estimates tokens as bytes divided by 4. It doesn't ship a full tokenizer, so the absolute token numbers are approximate. The savings percentages are reliable because the same estimation method applies to both the before and after.

Seeing all zeros?

Only commands run after the hook was installed are tracked. Make sure you used Claude Code after running rtk init -g in the previous step.

Verify the hook is active by running rtk init --show. If the hook isn't listed, re-run rtk init -g, restart Claude Code, and ask it to run a few commands before checking again.

Why is my RTK dashboard showing all zeros?

Inspect per-command savings

The summary dashboard gives you the big picture. You can also drill down into individual commands to see which ones benefit most from compression.

View your recent command history by running:

rtk gain --history

Each line shows a specific command RTK processed, how many tokens went in, how many came out, and the percentage saved.

Which commands save the most?

Commands that produce lots of structured, repetitive output tend to compress the best. Think git log with its multi-line commit entries, or ls -la with its permission strings, timestamps, and file sizes.

Short commands that already produce minimal output won't save much. That's expected.

Track savings over time

As you use Claude Code more, your savings accumulate. RTK tracks daily totals so you can watch the trend grow.

See a day-by-day breakdown of your savings by running:

rtk gain --daily

Since you just installed RTK, you'll only see today's data point. Over time, each day adds a new row as your cumulative savings grow.

See an ASCII graph of your savings over the last 30 days by running:

rtk gain --graph

Right now the graph only has one bar. Come back after a few days of using Claude Code and you'll see your savings trend over time.

Does RTK's savings percentage translate to the same drop in my AI bill?

Not directly. RTK compresses Bash command output, which is only one part of the AI's input tokens. Your prompts, system prompts, and conversation history also consume tokens.

RTK reduces the Bash output portion of your token usage. The overall bill reduction is smaller because input tokens include more than just command output, and your bill also counts output tokens from the AI's responses.

Secret mission

Unlock RTK's Power Features

RTK's default compression is just the beginning. In this mission, you'll unlock aggressive file reading that strips function bodies to signatures only, ultra-compact output mode for maximum reduction, and a missed-savings scanner that catches commands slipping past your hook.

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally with no cloud resources, so there are no ongoing costs from RTK.

Resources you used:

RTK binary, installed via Homebrew.
RTK global PreToolUse hook, installed in Claude Code's settings.
RTK local data and config files at ~/Library/Application Support/rtk/.
Test project directory at ~/rtk-test-project.

Keep everything running

No action needed. Choose this if you plan to keep using Claude Code with RTK's automatic compression.

RTK adds less than 10ms overhead per command and runs entirely locally. Your token savings accumulate automatically over time with no downside.
Homebrew and Claude Code also remain installed on your machine. Your Claude Code subscription is a separate, pre-existing cost not created by this project.

Pause - I'll come back to this later

Temporarily adjust RTK's behaviour without removing anything.

To exclude specific commands from RTK's compression, open ~/Library/Application Support/rtk/config.toml and add them to the exclude_commands list under [hooks]:

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

To temporarily remove the hook entirely, run rtk init -g --uninstall in Terminal. Re-enable it later by running rtk init -g.
Your savings data stays intact at ~/Library/Application Support/rtk/ so you can pick up right where you left off.

Delete - I don't want to use this again

Remove all project resources and start fresh.

Remove the RTK hook from Claude Code by running:

rtk init -g --uninstall

Remove the RTK binary by running:

brew uninstall rtk-ai/tap/rtk

Remove RTK's local data and config files by running:

rm -rf ~/Library/Application\ Support/rtk/

Remove the test project by running:

rm -rf ~/rtk-test-project

Confirm everything is removed by running:

ls ~/rtk-test-project

You should see a "No such file or directory" message. Homebrew and Claude Code remain installed for your other projects.

Nice Work!

Nice work! You've just turned your AI coding assistant into a lean, token-efficient machine by hooking RTK into Claude Code on your Mac.

You've learned how to:

Hooked RTK into Claude Code with a single command (rtk init -g), enabling automatic output compression across all your projects.
Compared raw terminal output to RTK-compressed output side by side, seeing firsthand how much token-wasting noise commands like git status and git log produce for an AI's context window.
Measured your token savings using RTK's built-in analytics dashboard (rtk gain), tracking commands processed, tokens saved, and savings percentage over time.
Secret Mission: Explored RTK's power features including aggressive file reading (-l aggressive), ultra-compact mode (-u), and missed-savings discovery (rtk discover).

Ready to quiz yourself?