rtk-ai__rtk/README.md

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, zero dependencies, <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.0"
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 hook for Claude Code (recommended)
rtk init --global
# Follow instructions to register in ~/.claude/settings.json
# Claude Code only by default (use --opencode for OpenCode)

# 2. Restart Claude Code, then test
git status  # Automatically rewritten to rtk git status

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

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%)

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%)

Package Managers

rtk pnpm list                   # Compact dependency tree
rtk pip list                    # Python packages (auto-detect uv)
rtk pip outdated                # Outdated packages
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

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.

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.

OpenCode Plugin (Global)

OpenCode supports plugins that can intercept tool execution. RTK provides a global plugin that mirrors the Claude auto-rewrite behavior by rewriting Bash tool commands to rtk ... before they execute. This plugin is not installed by default.

Note

: This plugin uses OpenCode's tool.execute.before hook. Known limitation: plugin hooks do not intercept subagent tool calls (upstream issue). See OpenCode plugin docs for API details.

Install OpenCode plugin:

rtk init -g --opencode

What it creates:

• ~/.config/opencode/plugins/rtk.ts

Restart Required: Restart OpenCode, then test with git status in a session.

Manual install (fallback):

mkdir -p ~/.config/opencode/plugins
cp hooks/opencode-rtk.ts ~/.config/opencode/plugins/rtk.ts

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
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

Contributing

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

Join the community on Discord.

License

MIT License - see LICENSE for details.