rtk-ai__rtk/README.md

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.

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

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/pszymkowiak/rtk/master/install.sh | sh

Homebrew (macOS) - Coming Soon

Cargo

cargo install rtk

Debian/Ubuntu

curl -LO https://github.com/pszymkowiak/rtk/releases/latest/download/rtk_0.2.1-1_amd64.deb
sudo dpkg -i rtk_0.2.1-1_amd64.deb

Fedora/RHEL

curl -LO https://github.com/pszymkowiak/rtk/releases/latest/download/rtk-0.2.1-1.x86_64.rpm
sudo rpm -i rtk-0.2.1-1.x86_64.rpm

Manual Download

Download binaries from 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

# Initialize rtk for Claude Code
rtk init --global    # Add to ~/CLAUDE.md (all projects)
rtk init             # Add to ./CLAUDE.md (this project)

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 find "*.rs" .               # Compact find results
rtk diff file1 file2            # Ultra-condensed diff
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

Data

rtk json config.json            # Structure without values
rtk deps                        # Dependencies summary
rtk env -f AWS                  # Filtered env vars
rtk gain                        # Token savings stats
rtk gain --graph                # With ASCII graph
rtk gain --history              # With command history

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

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

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

Improvements in This Fork

This fork adds critical fixes and modern JavaScript stack support to RTK, validated on production T3 Stack codebases.

🔧 PR #5: Git Argument Parsing Fix (CRITICAL)

Status: Open | Priority: Critical

Fixes a major bug where git flags were rejected as invalid arguments.

Problem:

rtk git log --oneline -20
# Error: unexpected argument '--oneline' found

Solution:

• Fixed Clap argument parsing with trailing_var_arg + allow_hyphen_values
• Auto-detects --merges flag to skip --no-merges injection
• Propagates git exit codes properly (fixes CI/CD false positives)

Now Working:

rtk git log --oneline -20           # Compact commit history
rtk git diff --cached               # Staged changes only
rtk git log --graph --all           # Branch visualization
rtk git status --short              # Ultra-compact status

Impact: All git flags now work correctly, preventing workflow disruptions.

📦 PR #6: pnpm Support for Modern JavaScript Stacks

Status: Open | Target: T3 Stack users

Adds first-class pnpm support with security hardening.

New Commands:

rtk pnpm list              # Dependency tree (70% token reduction)
rtk pnpm outdated          # Update candidates (80-90% reduction)
rtk pnpm install <pkg>     # Silent success confirmation

Token Savings:

Command	Standard Output	rtk Output	Reduction
pnpm list	~8,000 tokens	~2,400	-70%
pnpm outdated	~12,000 tokens	~1,200-2,400	-80-90%
pnpm install	~500 tokens	~10	-98%

Security:

• Package name validation (prevents command injection)
• Proper error propagation (fixes CI/CD reliability)
• Comprehensive test coverage

🐛 Related Upstream Issues

This fork addresses issues reported upstream:

• Issue #2: Git argument parsing bug
• Issue #3: T3 Stack support request (pnpm + Vitest)
• Issue #4: grep/ls filtering improvements

🧪 Testing

Production Validation: All improvements tested on a production T3 Stack codebase:

• Framework: Next.js 15.1.5 + TypeScript
• Package Manager: pnpm 10.0.0
• Test Runner: Vitest
• Repository: 50+ files, 10,000+ lines of code

Test Coverage:

• Unit tests for all new commands
• Integration tests with real pnpm/git outputs
• Security validation for command injection prevention
• CI/CD pipeline validation (exit code propagation)

📥 Installation

Use This Fork (recommended until PRs are merged):

# Clone and build
git clone https://github.com/FlorianBruniaux/rtk.git
cd rtk
cargo build --release

# Install globally
cargo install --path .

# Or use directly
./target/release/rtk --version

Track Upstream Merge Status:

• Watch PR #5 for git fixes
• Watch PR #6 for pnpm support

Switch to Upstream (once merged):

cargo install rtk --force

Configuration

rtk reads from CLAUDE.md files to instruct Claude Code to use rtk automatically:

rtk init --show    # Show current configuration
rtk init           # Create local CLAUDE.md
rtk init --global  # Create ~/CLAUDE.md

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

License

MIT License - see LICENSE for details.

Contributing

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