High-performance CLI proxy that reduces LLM token consumption by 60-90%

Website • Install • Troubleshooting • Architecture • Discord

English • Francais • 中文 • 日本語 • 한국어 • Espanol

---

rtk filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead.

Token Savings (30-min Claude Code Session)

Operation	Frequency	Standard	rtk	Savings
ls / tree	10x	2,000	400	-80%
cat / read	20x	40,000	12,000	-70%
grep / rg	8x	16,000	3,200	-80%
git status	10x	3,000	600	-80%
git diff	5x	10,000	2,500	-75%
git log	5x	2,500	500	-80%
git add/commit/push	8x	1,600	120	-92%
cargo test / npm test	5x	25,000	2,500	-90%
ruff check	3x	3,000	600	-80%
pytest	4x	8,000	800	-90%
go test	3x	6,000	600	-90%
docker ps	3x	900	180	-80%
Total		~118,000	~23,900	-80%

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

Installation

Homebrew (recommended)

brew install rtk

Quick Install (Linux/macOS)

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

Installs to ~/.local/bin. Add to PATH if needed:

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

Cargo

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

Pre-built Binaries

Download from releases:

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

Verify Installation

rtk --version   # Should show "rtk 0.28.2"
rtk gain        # Should show token savings stats

Name collision warning: Another project named "rtk" (Rust Type Kit) exists on crates.io. If rtk gain fails, you have the wrong package. Use cargo install --git above instead.

Quick Start

# 1. Install for your AI tool
rtk init -g                     # Claude Code / Copilot (default)
rtk init -g --gemini            # Gemini CLI
rtk init -g --codex             # Codex (OpenAI)
rtk init -g --agent cursor      # Cursor
rtk init --agent windsurf       # Windsurf
rtk init --agent cline          # Cline / Roo Code

# 2. Restart your AI tool, then test
git status  # Automatically rewritten to rtk git status

The hook transparently rewrites Bash commands (e.g., git status -> rtk git status) before execution. Claude never sees the rewrite, it just gets compressed output.

Important: the hook only runs on Bash tool calls. Claude Code built-in tools like Read, Grep, and Glob do not pass through the Bash hook, so they are not auto-rewritten. To get RTK's compact output for those workflows, use shell commands (cat/head/tail, rg/grep, find) or call rtk read, rtk grep, or rtk find directly.

How It Works

  Without rtk:                                    With rtk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |        ~2,000 tokens (raw)        |            |   ~200 tokens        | filter   |
    +-----------------------------------+            +------- (filtered) ---+----------+

Four strategies applied per command type:

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

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
rtk diff file1 file2            # Condensed diff

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"

GitHub CLI

rtk gh pr list                  # Compact PR listing
rtk gh pr view 42               # PR details + checks
rtk gh issue list               # Compact issue listing
rtk gh run list                 # Workflow run status

Test Runners

rtk test cargo test             # Show failures only (-90%)
rtk err npm run build           # Errors/warnings only
rtk vitest run                  # Vitest compact (failures only)
rtk playwright test             # E2E results (failures only)
rtk pytest                      # Python tests (-90%)
rtk go test                     # Go tests (NDJSON, -90%)
rtk cargo test                  # Cargo tests (-90%)
rtk rake test                   # Ruby minitest (-90%)
rtk rspec                       # RSpec tests (JSON, -60%+)

Build & Lint

rtk lint                        # ESLint grouped by rule/file
rtk lint biome                  # Supports other linters
rtk tsc                         # TypeScript errors grouped by file
rtk next build                  # Next.js build compact
rtk prettier --check .          # Files needing formatting
rtk cargo build                 # Cargo build (-80%)
rtk cargo clippy                # Cargo clippy (-80%)
rtk ruff check                  # Python linting (JSON, -80%)
rtk golangci-lint run           # Go linting (JSON, -85%)
rtk rubocop                     # Ruby linting (JSON, -60%+)

Package Managers

rtk pnpm list                   # Compact dependency tree
rtk pip list                    # Python packages (auto-detect uv)
rtk pip outdated                # Outdated packages
rtk bundle install              # Ruby gems (strip Using lines)
rtk prisma generate             # Schema generation (no ASCII art)

Containers

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

Data & Analytics

rtk json config.json            # Structure without values
rtk deps                        # Dependencies summary
rtk env -f AWS                  # Filtered env vars
rtk log app.log                 # Deduplicated logs
rtk curl <url>                  # Auto-detect JSON + schema
rtk wget <url>                  # Download, strip progress bars
rtk summary <long command>      # Heuristic summary
rtk proxy <command>             # Raw passthrough + tracking

Token Savings Analytics

rtk gain                        # Summary stats
rtk gain --graph                # ASCII graph (last 30 days)
rtk gain --history              # Recent command history
rtk gain --daily                # Day-by-day breakdown
rtk gain --all --format json    # JSON export for dashboards

rtk discover                    # Find missed savings opportunities
rtk discover --all --since 7    # All projects, last 7 days

rtk session                     # Show RTK adoption across recent sessions

Global Flags

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

Examples

Directory listing:

# ls -la (45 lines, ~800 tokens)        # rtk ls (12 lines, ~150 tokens)
drwxr-xr-x  15 user staff 480 ...       my-project/
-rw-r--r--   1 user staff 1234 ...       +-- src/ (8 files)
...                                      |   +-- main.rs
                                         +-- Cargo.toml

Git operations:

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

Test output:

# cargo test (200+ lines on failure)     # rtk test cargo test (~20 lines)
running 15 tests                          FAILED: 2/15 tests
test utils::test_parse ... ok               test_edge_case: assertion failed
test utils::test_format ... ok              test_overflow: panic at utils.rs:18
...

Auto-Rewrite Hook

The most effective way to use rtk. The hook transparently intercepts Bash commands and rewrites them to rtk equivalents before execution.

Result: 100% rtk adoption across all conversations and subagents, zero token overhead.

Scope note: this only applies to Bash tool calls. Claude Code built-in tools such as Read, Grep, and Glob bypass the hook, so use shell commands or explicit rtk commands when you want RTK filtering there.

Setup

rtk init -g                 # Install hook + RTK.md (recommended)
rtk init -g --opencode      # OpenCode plugin (instead of Claude Code)
rtk init -g --auto-patch    # Non-interactive (CI/CD)
rtk init -g --hook-only     # Hook only, no RTK.md
rtk init --show             # Verify installation

After install, restart Claude Code.

Supported AI Tools

RTK supports 10 AI coding tools. Each integration transparently rewrites shell commands to rtk equivalents for 60-90% token savings.

Tool	Install	Method
Claude Code	rtk init -g	PreToolUse hook (bash)
GitHub Copilot (VS Code)	rtk init -g --copilot	PreToolUse hook (rtk hook copilot) — transparent rewrite
GitHub Copilot CLI	rtk init -g --copilot	PreToolUse deny-with-suggestion (CLI limitation)
Cursor	rtk init -g --agent cursor	preToolUse hook (hooks.json)
Gemini CLI	rtk init -g --gemini	BeforeTool hook (rtk hook gemini)
Codex	rtk init -g --codex	AGENTS.md + RTK.md instructions
Windsurf	rtk init --agent windsurf	.windsurfrules (project-scoped)
Cline / Roo Code	rtk init --agent cline	.clinerules (project-scoped)
OpenCode	rtk init -g --opencode	Plugin TS (tool.execute.before)
OpenClaw	openclaw plugins install ./openclaw	Plugin TS (before_tool_call)
Mistral Vibe	Planned (#800)	Blocked on upstream BeforeToolCallback

Claude Code (default)

rtk init -g                 # Install hook + RTK.md
rtk init -g --auto-patch    # Non-interactive (CI/CD)
rtk init --show             # Verify installation
rtk init -g --uninstall     # Remove

GitHub Copilot (VS Code + CLI)

rtk init -g --copilot         # Install hook + instructions

Creates .github/hooks/rtk-rewrite.json (PreToolUse hook) and .github/copilot-instructions.md (prompt-level awareness).

The hook (rtk hook copilot) auto-detects the format:

• VS Code Copilot Chat: transparent rewrite via updatedInput (same as Claude Code)
• Copilot CLI: deny-with-suggestion (CLI does not support updatedInput yet — see copilot-cli#2013)

Cursor

rtk init -g --agent cursor

Creates ~/.cursor/hooks/rtk-rewrite.sh + patches ~/.cursor/hooks.json with preToolUse matcher. Works with both Cursor editor and cursor-agent CLI.

Gemini CLI

rtk init -g --gemini
rtk init -g --gemini --uninstall

Creates ~/.gemini/hooks/rtk-hook-gemini.sh + patches ~/.gemini/settings.json with BeforeTool hook.

Codex (OpenAI)

rtk init -g --codex

Creates ~/.codex/RTK.md + ~/.codex/AGENTS.md with @RTK.md reference. Codex reads these as global instructions.

Windsurf

rtk init --agent windsurf

Creates .windsurfrules in the current project. Cascade reads rules and prefixes commands with rtk.

Cline / Roo Code

rtk init --agent cline

Creates .clinerules in the current project. Cline reads rules and prefixes commands with rtk.

OpenCode

rtk init -g --opencode

Creates ~/.config/opencode/plugins/rtk.ts. Uses tool.execute.before hook.

OpenClaw

openclaw plugins install ./openclaw

Plugin in openclaw/ directory. Uses before_tool_call hook, delegates to rtk rewrite.

Mistral Vibe (planned)

Blocked on upstream BeforeToolCallback support (mistral-vibe#531, PR #533). Tracked in #800.

Commands Rewritten

Raw Command	Rewritten To
git status/diff/log/add/commit/push/pull	rtk git ...
gh pr/issue/run	rtk gh ...
cargo test/build/clippy	rtk cargo ...
cat/head/tail <file>	rtk read <file>
rg/grep <pattern>	rtk grep <pattern>
ls	rtk ls
vitest/jest	rtk vitest run
tsc	rtk tsc
eslint/biome	rtk lint
prettier	rtk prettier
playwright	rtk playwright
prisma	rtk prisma
ruff check/format	rtk ruff ...
pytest	rtk pytest
pip list/install	rtk pip ...
go test/build/vet	rtk go ...
golangci-lint	rtk golangci-lint
rake test / rails test	rtk rake test
rspec / bundle exec rspec	rtk rspec
rubocop / bundle exec rubocop	rtk rubocop
bundle install/update	rtk bundle ...
docker ps/images/logs	rtk docker ...
kubectl get/logs	rtk kubectl ...
curl	rtk curl
pnpm list/outdated	rtk pnpm ...

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

Configuration

Config File

~/.config/rtk/config.toml (macOS: ~/Library/Application Support/rtk/config.toml):

[tracking]
database_path = "/path/to/custom.db"  # default: ~/.local/share/rtk/history.db

[hooks]
exclude_commands = ["curl", "playwright"]  # skip rewrite for these

[tee]
enabled = true          # save raw output on failure (default: true)
mode = "failures"       # "failures", "always", or "never"
max_files = 20          # rotation limit

Tee: Full Output Recovery

When a command fails, RTK saves the full unfiltered output so the LLM can read it without re-executing:

FAILED: 2/15 tests
[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]

Uninstall

rtk init -g --uninstall     # Remove hook, RTK.md, settings.json entry
cargo uninstall rtk          # Remove binary
brew uninstall rtk           # If installed via Homebrew

Documentation

• TROUBLESHOOTING.md - Fix common issues
• INSTALL.md - Detailed installation guide
• ARCHITECTURE.md - Technical architecture
• SECURITY.md - Security policy and PR review process
• AUDIT_GUIDE.md - Token savings analytics guide

Privacy & Telemetry

RTK collects anonymous, aggregate usage metrics once per day, enabled by default. This data helps us build a better product: identifying which commands need filters, which filters need improvement, and how much value RTK delivers. For the full list of fields, data handling, and contributor guidelines, see docs/TELEMETRY.md.

What is collected and why:

Category	Data	Why
Identity	Salted device hash (SHA-256, not reversible)	Count unique installations without tracking individuals
Environment	RTK version, OS, architecture, install method	Know which platforms to support and test
Usage volume	Command count (24h), total commands, tokens saved (24h/30d/total)	Measure adoption and value delivered
Quality	Top 5 passthrough commands (0% savings), parse failure count, commands with <30% savings	Identify missing filters and weak ones to improve
Ecosystem	Command category distribution (e.g. git 45%, cargo 20%, js 15%)	Prioritize filter development for popular ecosystems
Retention	Days since first use, active days in last 30	Understand engagement and detect churn
Adoption	AI agent hook type (claude/gemini/codex), custom TOML filter count	Track integration coverage and DSL adoption
Configuration	Whether config.toml exists, number of excluded commands, project count	Understand user maturity and customization patterns
Features	Usage counts for meta-commands (gain, discover, proxy, verify)	Know which RTK features are valued vs unused
Economics	Estimated USD savings (based on API token pricing)	Quantify the value RTK provides to users

All data is aggregate counts or anonymized command names (first 3 words, no arguments). Top commands report only tool names (e.g. "git", "cargo"), never full command lines.

What is NOT collected: source code, file paths, command arguments, secrets, environment variables, personal data, or repository contents.

Opt-out (any of these):

# Environment variable
export RTK_TELEMETRY_DISABLED=1

# Or in config file (~/.config/rtk/config.toml)
[telemetry]
enabled = false

Contributing

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

Join the community on Discord.

License

MIT License - see LICENSE for details.