rtk - Rust Token Killer

High-performance CLI proxy to minimize LLM token consumption.

rtk filters and compresses command outputs before they reach your LLM context, saving 60-90% of tokens on common operations.

⚠️ Important: Name Collision Warning

There are TWO different projects named "rtk":

✅ This project (Rust Token Killer) - LLM token optimizer
- Repos: rtk-ai/rtk
- Purpose: Reduce Claude Code token consumption
❌ reachingforthejack/rtk - Rust Type Kit (DIFFERENT PROJECT)
- Purpose: Query Rust codebase and generate types
- DO NOT install this one if you want token optimization

How to verify you have the correct rtk:

rtk --version   # Should show "rtk X.Y.Z"
rtk gain        # Should show token savings stats

If rtk gain doesn't exist, you installed the wrong package. See installation instructions below.

Token Savings (30-min Claude Code Session)

Typical session without rtk: ~150,000 tokens With rtk: ~45,000 tokens → 70% reduction

Operation	Frequency	Standard	rtk	Savings
`ls` / `tree`	10×	2,000	400	-80%
`cat` / `read`	20×	40,000	12,000	-70%
`grep` / `rg`	8×	16,000	3,200	-80%
`git status`	10×	3,000	600	-80%
`git diff`	5×	10,000	2,500	-75%
`git log`	5×	2,500	500	-80%
`git add/commit/push`	8×	1,600	120	-92%
`npm test` / `cargo test`	5×	25,000	2,500	-90%
`docker ps`	3×	900	180	-80%
Total		~101,000	~22,000	-78%

Estimates based on medium-sized TypeScript/Rust projects. Actual savings vary by project size.

Installation

⚠️ Pre-Installation Check (REQUIRED)

ALWAYS verify if rtk is already installed before installing:

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

If already installed and rtk gain works, DO NOT reinstall. Skip to Quick Start.

Quick Install (Linux/macOS)

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

After installation, verify you have the correct rtk:

rtk gain  # Must show token savings stats (not "command not found")

Alternative: Manual Installation

# From rtk-ai upstream (maintained by pszymkowiak)
cargo install --git https://github.com/rtk-ai/rtk

# OR if published to crates.io
cargo install rtk

⚠️ WARNING: cargo install rtk from crates.io might install the wrong package (Type Kit instead of Token Killer). Always verify with rtk gain after installation.

Alternative: Pre-built Binaries

Download from rtk-ai/releases:

macOS: rtk-x86_64-apple-darwin.tar.gz / rtk-aarch64-apple-darwin.tar.gz
Linux: rtk-x86_64-unknown-linux-gnu.tar.gz / rtk-aarch64-unknown-linux-gnu.tar.gz
Windows: rtk-x86_64-pc-windows-msvc.zip

Quick Start

# 1. Verify installation
rtk gain  # Must show token stats, not "command not found"

# 2. Initialize for Claude Code (RECOMMENDED: hook-first mode)
rtk init --global
# → Installs hook + creates slim RTK.md (10 lines, 99.5% token savings)
# → Follow printed instructions to add hook to ~/.claude/settings.json

# 3. Test it works
rtk git status  # Should show ultra-compact output
rtk init --show # Verify hook is installed and executable

# Alternative modes:
# rtk init --global --claude-md  # Legacy: full injection (137 lines)
# rtk init                       # Local project only (./CLAUDE.md)

New in v0.9.5: Hook-first installation eliminates ~2000 tokens from Claude's context while maintaining full RTK functionality through transparent command rewriting.

Global Flags

-u, --ultra-compact    # ASCII icons, inline format (extra token savings)
-v, --verbose          # Increase verbosity (-v, -vv, -vvv)

Commands

Files

rtk ls .                        # Token-optimized directory tree
rtk read file.rs                # Smart file reading
rtk read file.rs -l aggressive  # Signatures only (strips bodies)
rtk smart file.rs               # 2-line heuristic code summary
rtk find "*.rs" .               # Compact find results
rtk grep "pattern" .            # Grouped search results

Git

rtk git status                  # Compact status
rtk git log -n 10               # One-line commits
rtk git diff                    # Condensed diff
rtk git add                     # → "ok ✓"
rtk git commit -m "msg"         # → "ok ✓ abc1234"
rtk git push                    # → "ok ✓ main"
rtk git pull                    # → "ok ✓ 3 files +10 -2"

Commands

rtk test cargo test             # Show failures only (-90% tokens)
rtk err npm run build           # Errors/warnings only
rtk summary <long command>      # Heuristic summary
rtk log app.log                 # Deduplicated logs
rtk gh pr list                   # Compact PR listing
rtk gh pr view 42                # PR details + checks summary
rtk gh issue list                # Compact issue listing
rtk gh run list                  # Workflow run status
rtk wget https://example.com    # Download, strip progress bars
rtk config                       # Show config (--create to generate)

Data & Analytics

rtk json config.json            # Structure without values
rtk deps                        # Dependencies summary
rtk env -f AWS                  # Filtered env vars

# Token Savings Analytics (includes execution time metrics)
rtk gain                        # Summary stats with total exec time
rtk gain --graph                # With ASCII graph of last 30 days
rtk gain --history              # With recent command history (10)
rtk gain --quota --tier 20x     # Monthly quota analysis (pro/5x/20x)

# Temporal Breakdowns (includes time metrics per period)
rtk gain --daily                # Day-by-day with avg execution time
rtk gain --weekly               # Week-by-week breakdown
rtk gain --monthly              # Month-by-month breakdown
rtk gain --all                  # All breakdowns combined

# Export Formats (includes total_time_ms and avg_time_ms fields)
rtk gain --all --format json    # JSON export for APIs/dashboards
rtk gain --all --format csv     # CSV export for Excel/analysis

📖 API Documentation: For programmatic access to tracking data (Rust library usage, CI/CD integration, custom dashboards), see docs/tracking.md.

Discover — Find Missed Savings

Scans your Claude Code session history to find commands where rtk would have saved tokens. Use it to:

Measure what you're missing — see exactly how many tokens you could save
Identify habits — find which commands you keep running without rtk
Spot new opportunities — see unhandled commands that could become rtk features

rtk discover                    # Current project, last 30 days
rtk discover --all              # All Claude Code projects
rtk discover --all --since 7    # Last 7 days across all projects
rtk discover -p aristote        # Filter by project name (substring)
rtk discover --format json      # Machine-readable output

Example output:

RTK Discover -- Savings Opportunities
====================================================
Scanned: 142 sessions (last 30 days), 1786 Bash commands
Already using RTK: 108 commands (6%)

MISSED SAVINGS -- Commands RTK already handles
----------------------------------------------------
Command              Count    RTK Equivalent        Est. Savings
git log                434    rtk git               ~55.9K tokens
cargo test             203    rtk cargo             ~49.9K tokens
ls -la                 107    rtk ls                ~11.8K tokens
gh pr                   80    rtk gh                ~10.4K tokens
----------------------------------------------------
Total: 986 commands -> ~143.9K tokens saveable

TOP UNHANDLED COMMANDS -- open an issue?
----------------------------------------------------
Command              Count    Example
git checkout            84    git checkout feature/my-branch
cargo run               32    cargo run -- gain --help
----------------------------------------------------
-> github.com/rtk-ai/rtk/issues

Containers

rtk docker ps                   # Compact container list
rtk docker images               # Compact image list
rtk docker logs <container>     # Deduplicated logs
rtk kubectl pods                # Compact pod list
rtk kubectl logs <pod>          # Deduplicated logs
rtk kubectl services             # Compact service list

JavaScript / TypeScript Stack

rtk lint                         # ESLint grouped by rule/file
rtk lint biome                   # Supports other linters too
rtk tsc                          # TypeScript errors grouped by file
rtk next build                   # Next.js build compact output
rtk prettier --check .           # Files needing formatting
rtk vitest run                   # Test failures only
rtk playwright test              # E2E results (failures only)
rtk prisma generate              # Schema generation (no ASCII art)
rtk prisma migrate dev --name x  # Migration summary
rtk prisma db-push               # Schema push summary

Examples

Standard vs rtk

Directory listing:

# ls -la (45 lines, ~800 tokens)
drwxr-xr-x  15 user  staff    480 Jan 23 10:00 .
drwxr-xr-x   5 user  staff    160 Jan 23 09:00 ..
-rw-r--r--   1 user  staff   1234 Jan 23 10:00 Cargo.toml
...

# rtk ls (12 lines, ~150 tokens)
📁 my-project/
├── src/ (8 files)
│   ├── main.rs
│   └── lib.rs
├── Cargo.toml
└── README.md

Git operations:

# git push (15 lines, ~200 tokens)
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
...

# rtk git push (1 line, ~10 tokens)
ok ✓ main

Test output:

# cargo test (200+ lines on failure)
running 15 tests
test utils::test_parse ... ok
test utils::test_format ... ok
...

# rtk test cargo test (only failures, ~20 lines)
FAILED: 2/15 tests
  ✗ test_edge_case: assertion failed at src/lib.rs:42
  ✗ test_overflow: panic at src/utils.rs:18

How It Works

Smart Filtering: Removes noise (comments, whitespace, boilerplate)
Grouping: Aggregates similar items (files by directory, errors by type)
Truncation: Keeps relevant context, cuts redundancy
Deduplication: Collapses repeated log lines with counts

Configuration

Installation Modes

Command	Scope	Hook	RTK.md	CLAUDE.md	Tokens in Context	Use Case
`rtk init -g`	Global	✅	✅ (10 lines)	@RTK.md	~10	Recommended: All projects, automatic
`rtk init -g --claude-md`	Global	❌	❌	Full (137 lines)	~2000	Legacy compatibility
`rtk init -g --hook-only`	Global	✅	❌	Nothing	0	Minimal setup, hook-only
`rtk init`	Local	❌	❌	Full (137 lines)	~2000	Single project, no hook

rtk init --show         # Show current configuration
rtk init -g             # Install hook + RTK.md (recommended)
rtk init -g --claude-md # Legacy: full injection into CLAUDE.md
rtk init                # Local project: full injection into ./CLAUDE.md

Migration: If you previously used rtk init -g with the old system (137-line injection), simply re-run rtk init -g to automatically migrate to the new hook-first approach.

example of 3 days session:

📊 RTK Token Savings
════════════════════════════════════════

Total commands:    133
Input tokens:      30.5K
Output tokens:     10.7K
Tokens saved:      25.3K (83.0%)

By Command:
────────────────────────────────────────
Command               Count      Saved     Avg%
rtk git status           41      17.4K    82.9%
rtk git push             54       3.4K    91.6%
rtk grep                 15       3.2K    26.5%
rtk ls                   23       1.4K    37.2%

Daily Savings (last 30 days):
────────────────────────────────────────
01-23 │███████████████████                      6.4K
01-24 │██████████████████                       5.9K
01-25 │                                         18
01-26 │████████████████████████████████████████ 13.0K

Auto-Rewrite Hook (Recommended)

The most effective way to use rtk is with the auto-rewrite hook for Claude Code. Instead of relying on CLAUDE.md instructions (which subagents may ignore), this hook transparently intercepts Bash commands and rewrites them to their rtk equivalents before execution.

Result: 100% rtk adoption across all conversations and subagents, zero token overhead in Claude's context.

How It Works

The hook runs as a Claude Code PreToolUse hook. When Claude Code is about to execute a Bash command like git status, the hook rewrites it to rtk git status before the command reaches the shell. Claude Code never sees the rewrite — it's transparent.

Quick Install (Automated)

rtk init -g
# → Installs hook to ~/.claude/hooks/rtk-rewrite.sh (with executable permissions)
# → Creates ~/.claude/RTK.md (10 lines, minimal context footprint)
# → Adds @RTK.md reference to ~/.claude/CLAUDE.md
# → Prints settings.json instructions (manual step required)

# Follow the printed instructions to add hook to ~/.claude/settings.json

Manual Install (Fallback)

If rtk init -g doesn't work for your setup:

# 1. Copy the hook script
mkdir -p ~/.claude/hooks
cp .claude/hooks/rtk-rewrite.sh ~/.claude/hooks/rtk-rewrite.sh
chmod +x ~/.claude/hooks/rtk-rewrite.sh

# 2. Add to ~/.claude/settings.json under hooks.PreToolUse:

Add this entry to the PreToolUse array in ~/.claude/settings.json:

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

Per-Project Install

The hook is included in this repository at .claude/hooks/rtk-rewrite.sh. To use it in another project, copy the hook and add the same settings.json entry using a relative path or project-level .claude/settings.json.

Commands Rewritten

Raw Command	Rewritten To
`git status/diff/log/add/commit/push/pull/branch/fetch/stash`	`rtk git ...`
`gh pr/issue/run`	`rtk gh ...`
`cargo test/build/clippy`	`rtk cargo ...`
`cat <file>`	`rtk read <file>`
`rg/grep <pattern>`	`rtk grep <pattern>`
`ls`	`rtk ls`
`vitest/pnpm test`	`rtk vitest run`
`tsc/pnpm tsc`	`rtk tsc`
`eslint/pnpm lint`	`rtk lint`
`prettier`	`rtk prettier`
`playwright`	`rtk playwright`
`prisma`	`rtk prisma`
`docker ps/images/logs`	`rtk docker ...`
`kubectl get/logs`	`rtk kubectl ...`
`curl`	`rtk curl`
`pnpm list/ls/outdated`	`rtk pnpm ...`

Commands already using rtk, heredocs (<<), and unrecognized commands pass through unchanged.

Alternative: Suggest Hook (Non-Intrusive)

If you prefer Claude Code to suggest rtk usage rather than automatically rewriting commands, use the suggest hook pattern instead. This emits a system reminder when rtk-compatible commands are detected, without modifying the command execution.

Comparison:

Aspect	Auto-Rewrite Hook	Suggest Hook
Strategy	Intercepts and modifies command before execution	Emits system reminder when rtk-compatible command detected
Effect	Claude Code never sees the original command	Claude Code receives hint to use rtk, decides autonomously
Adoption	100% (forced)	~70-85% (depends on Claude Code's adherence to instructions)
Use Case	Production workflows, guaranteed savings	Learning mode, auditing, user preference for explicit control
Overhead	Zero (transparent rewrite)	Minimal (reminder message in context)

When to use suggest over rewrite:

You want to audit which commands Claude Code chooses to run
You're learning rtk patterns and want visibility into the rewrite logic
You prefer Claude Code to make explicit decisions rather than transparent rewrites
You want to preserve exact command execution for debugging

Suggest Hook Setup

1. Create the suggest hook script

mkdir -p ~/.claude/hooks
cp .claude/hooks/rtk-suggest.sh ~/.claude/hooks/rtk-suggest.sh
chmod +x ~/.claude/hooks/rtk-suggest.sh

2. Add to ~/.claude/settings.json

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

The suggest hook detects the same commands as the rewrite hook but outputs a systemMessage instead of updatedInput, informing Claude Code that an rtk alternative exists.

Documentation

TROUBLESHOOTING.md - ⚠️ Fix common issues (wrong rtk installed, missing commands, PATH issues)
INSTALL.md - Detailed installation guide with verification steps
AUDIT_GUIDE.md - Complete guide to token savings analytics, temporal breakdowns, and data export
CLAUDE.md - Claude Code integration instructions and project context
ARCHITECTURE.md - Technical architecture and development guide
SECURITY.md - Security policy, vulnerability reporting, and PR review process

For Maintainers

Security Review Workflow

RTK implements a comprehensive 3-layer security review process for external PRs:

Layer 1: Automated GitHub Action

Every PR triggers .github/workflows/security-check.yml:

Cargo audit: CVE detection in dependencies
Critical files alert: Flags modifications to high-risk files (runner.rs, tracking.rs, Cargo.toml, workflows)
Dangerous pattern scanning: Shell injection, network operations, unsafe code, panic risks
Dependency auditing: Supply chain verification for new crates
Clippy security lints: Enforces Rust safety best practices

Results appear in the PR's GitHub Actions summary.

Layer 2: Claude Code Skill

For comprehensive manual review, maintainers with Claude Code can use:

/rtk-pr-security <PR_NUMBER>

The skill performs:

Critical files analysis: Detects modifications to shell execution, validation, or CI/CD files
Dangerous pattern detection: Identifies shell injection, environment manipulation, exfiltration vectors
Supply chain audit: Verifies new dependencies on crates.io (downloads, maintainer, license)
Semantic analysis: Checks intent vs reality, logic bombs, code quality red flags
Structured report generation: Produces security assessment with risk level and verdict

Skill installation (maintainers only):

# The skill is bundled in the rtk-pr-security directory
# Copy to your Claude skills directory:
cp -r ~/.claude/skills/rtk-pr-security ~/.claude/skills/

The skill includes:

SKILL.md - Workflow automation and usage guide
critical-files.md - RTK-specific file risk tiers with attack scenarios
dangerous-patterns.md - Regex patterns with exploitation examples
checklist.md - Manual review template

Layer 3: Manual Review

For PRs touching critical files or adding dependencies:

2 maintainers required for Cargo.toml, workflows, or Tier 1 files
Isolated testing recommended for high-risk changes
Follow the checklist in SECURITY.md

See SECURITY.md for complete security policy and review guidelines.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

For external contributors: Your PR will undergo automated security review (see SECURITY.md). This protects RTK's shell execution capabilities against injection attacks and supply chain vulnerabilities.

Name		Name	Last commit message	Last commit date
Latest commit History 179 Commits
.claude		.claude
.github/workflows		.github/workflows
Formula		Formula
docs		docs
hooks		hooks
scripts		scripts
src		src
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
TEST_EXEC_TIME.md		TEST_EXEC_TIME.md
install.sh		install.sh
release-please-config.json		release-please-config.json

License

FlorianBruniaux/rtk

Folders and files

Latest commit

History

Repository files navigation

rtk - Rust Token Killer

⚠️ Important: Name Collision Warning

Token Savings (30-min Claude Code Session)

Installation

⚠️ Pre-Installation Check (REQUIRED)

Quick Install (Linux/macOS)

Alternative: Manual Installation

Alternative: Pre-built Binaries

Quick Start

Global Flags

Commands

Files

Git

Commands

Data & Analytics

Discover — Find Missed Savings

Containers

JavaScript / TypeScript Stack

Examples

Standard vs rtk

How It Works

Configuration

Installation Modes

Auto-Rewrite Hook (Recommended)

How It Works

Quick Install (Automated)

Manual Install (Fallback)

Per-Project Install

Commands Rewritten

Alternative: Suggest Hook (Non-Intrusive)

Suggest Hook Setup

Documentation

For Maintainers

Security Review Workflow

Layer 1: Automated GitHub Action

Layer 2: Claude Code Skill

Layer 3: Manual Review

License

Contributing

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages