Extended fork of RTK — CLI proxy that reduces LLM token consumption by 60-90%

Install • Troubleshooting • Architecture • Upstream

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

---

This is an extended fork of rtk-ai/rtk (Rust Token Killer) by Patrick Szymkowiak. All credit for the original project goes to the upstream maintainers. This fork adds extra command filters, broader pattern coverage, and quality-of-life fixes. The binary is still called rtk for full compatibility with existing hooks and workflows.

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

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/dioptx/rtk-plus/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/dioptx/rtk-plus

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-plus 0.27.2"
rtk gain        # Should show token savings stats

Note: The upstream project rtk-ai/rtk is also available via brew install rtk and crates.io. This fork (rtk-plus) is installed separately via the methods above.

Quick Start

# 1. Install hook for Claude Code (recommended)
rtk init --global
# Follow instructions to register in ~/.claude/settings.json

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

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-plus     # Remove binary

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

Upstream

This project is a fork of rtk-ai/rtk (Rust Token Killer) created by Patrick Szymkowiak. All credit for the core architecture, filtering strategies, and CLI design goes to the original project.

What rtk-plus adds

• 17 additional command patterns: make, sqlite3, lsof, ps, du, df, bq, jq, bat/less/more, extended docker compose, docker exec, npm test, pnpm/yarn/bun test, cargo install/nextest, pgrep, pkill
• Broader regex coverage: Extended git, npm, pip, and pytest patterns
• Git argument parsing fix (PR #5): Proper trailing_var_arg for git flags
• Modern JS/TS tooling: pnpm, vitest, Next.js, TypeScript, Playwright, Prisma filters
• Python & Go support: ruff, pytest, pip, go test/build/vet, golangci-lint
• Quote-aware hook rewriting: SSH commands with quoted arguments handled correctly

Upstream compatibility

rtk-plus tracks upstream releases and merges regularly. The binary is named rtk for full backward compatibility with existing hooks, CLAUDE.md references, and settings.json entries.

Contributing

Contributions welcome! See the Contributing Guide for branch naming, PR process, testing requirements, and coding practices.

For upstream contributions, please submit PRs to rtk-ai/rtk.

License

MIT License - see LICENSE for details.

Contact

• Upstream: https://github.com/rtk-ai/rtk
• Fork issues: https://github.com/dioptx/rtk-plus/issues