RTK Token Optimizer

---
name: rtk-token-optimizer
description: CLI proxy that reduces LLM token consumption by 60-90% on common dev commands using a single Rust binary
triggers:
  - reduce token usage with rtk
  - install rtk for claude code
  - rtk token savings setup
  - optimize llm context with rtk
  - rtk git status compact output
  - set up rtk hook for ai coding
  - rtk command not working
  - how to use rtk with cursor or windsurf
---

# RTK Token Optimizer

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

RTK is a high-performance CLI proxy written in Rust that intercepts common dev commands (`git`, `ls`, `cargo test`, `pytest`, etc.) and compresses their output before it reaches your LLM context window. A single static binary with zero runtime dependencies adds less than 10ms overhead while cutting token usage by 60–90%.

---

## Installation

### Homebrew (recommended)
```bash
brew install rtk

Quick install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
# Add to PATH if needed:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Cargo (from source)

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

Verify

rtk --version   # rtk 0.28.2
rtk gain        # shows token savings stats

Crates.io collision: A different package called "rtk" exists on crates.io. Always use --git with cargo.

---

Hook Setup (Auto-Rewrite)

The hook transparently rewrites Bash tool calls (e.g., git status → rtk git status) before execution. Claude never sees the rewrite — it just receives compressed output.

rtk init -g                      # Claude Code / Copilot (global, recommended)
rtk init -g --gemini             # Gemini CLI
rtk init -g --codex              # Codex / OpenAI
rtk init -g --agent cursor       # Cursor
rtk init --agent windsurf        # Windsurf (project-scoped)
rtk init --agent cline           # Cline / Roo Code (project-scoped)
rtk init -g --opencode           # OpenCode plugin
rtk init -g --auto-patch         # Non-interactive (CI/CD)
rtk init --show                  # Verify current installation

After installing, restart your AI tool.

Scope: The hook only applies to Bash tool calls. Claude Code built-in tools (Read, Grep, Glob) bypass it. Use shell equivalents (cat, rg, find) or explicit rtk commands for those workflows.

---

Core Commands

Files

rtk ls .                         # Token-optimized directory tree
rtk read src/main.rs             # Smart file reading
rtk read src/main.rs -l aggressive  # Signatures only (strips function bodies)
rtk smart src/main.rs            # 2-line heuristic code summary
rtk find "*.rs" .                # Compact find results
rtk grep "fn parse" src/         # Grouped search results
rtk diff file1.rs file2.rs       # Condensed diff

Git

rtk git status                   # Compact status (~200 tokens vs ~2000)
rtk git log -n 10                # One-line commits
rtk git diff                     # Condensed diff
rtk git add .                    # Output: "ok"
rtk git commit -m "fix: parse"   # Output: "ok abc1234"
rtk git push                     # Output: "ok main"
rtk git pull                     # Output: "ok 3 files +10 -2"

Test Runners

rtk cargo test                   # Rust — failures only (-90%)
rtk test cargo test              # Explicit test wrapper
rtk pytest                       # Python — failures only (-90%)
rtk go test                      # Go — NDJSON compact (-90%)
rtk rspec                        # Ruby — JSON compact (-60%+)
rtk vitest run                   # Vitest — failures only
rtk playwright test              # E2E — failures only
rtk rake test                    # Ruby minitest (-90%)

Build & Lint

rtk cargo build                  # Rust build (-80%)
rtk cargo clippy                 # Clippy warnings grouped (-80%)
rtk tsc                          # TypeScript errors by file
rtk lint                         # ESLint grouped by rule/file
rtk lint biome                   # Biome linter
rtk ruff check                   # Python lint (JSON, -80%)
rtk golangci-lint run            # Go lint (JSON, -85%)
rtk rubocop                      # Ruby lint (JSON, -60%+)
rtk next build                   # Next.js compact build output
rtk prettier --check .           # Files needing formatting only

GitHub CLI

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

Containers & Infra

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

Data & Utilities

rtk json config.json             # Structure without values (schema view)
rtk env -f AWS                   # Filtered env vars (e.g., AWS_*)
rtk log app.log                  # Deduplicated application logs
rtk curl https://api.example.com # Auto-detect JSON + print schema
rtk deps                         # Dependency summary
rtk summary <long command>       # Heuristic summary of any command
rtk proxy <command>              # Raw passthrough + token tracking

Package Managers

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

---

Global Flags

rtk -u <command>                 # --ultra-compact: ASCII icons, inline format
rtk -v <command>                 # --verbose (stack: -v, -vv, -vvv)

---

Token Savings Analytics

rtk gain                         # Summary stats
rtk gain --graph                 # ASCII graph (last 30 days)
rtk gain --history               # Recent command history with savings
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                      # RTK adoption across recent sessions

---

Real-World Usage Patterns

Pattern 1: Rust project CI loop

# Instead of: cargo test 2>&1 (200+ lines on failure)
rtk cargo test
# Output (~20 lines):
# FAILED: 2/15 tests
#   test_edge_case: assertion failed at utils.rs:42
#   test_overflow: panic at utils.rs:18

rtk cargo clippy
# Output: grouped warnings by lint rule, not raw rustc noise

Pattern 2: Python project

rtk pytest                       # Only failing tests + tracebacks
rtk ruff check                   # JSON-parsed, grouped by rule
rtk pip outdated                 # Table of outdated packages only

Pattern 3: Node/TypeScript project

rtk tsc                          # TypeScript errors grouped by file
rtk lint                         # ESLint violations grouped by rule
rtk next build                   # Next.js build, key metrics only
rtk vitest run                   # Failures only, not 300 "✓ pass" lines

Pattern 4: Reading large files intelligently

# Full file (smart truncation)
rtk read src/lib.rs

# Signatures only — ideal for understanding module structure
rtk read src/lib.rs -l aggressive

# 2-line summary heuristic
rtk smart src/lib.rs

Pattern 5: Git workflow in AI sessions

rtk git status                   # ~200 tokens (vs raw ~2000)
rtk git diff HEAD~1              # Condensed patch
rtk git log -n 5                 # 5 one-liners
rtk git add . && rtk git commit -m "feat: add parser"
# Output: "ok" then "ok a3f9c12"

---

Configuration

RTK is configuration-free by default. All tuning is via CLI flags:

Flag	Effect
-u / --ultra-compact	Maximum compression with ASCII icons
-v / -vv / -vvv	Increase verbosity for debugging
-l aggressive	Aggressive level for rtk read (signatures only)

The rtk init command writes hooks to your AI tool's config directory (global -g) or the current project directory (no -g).

---

Troubleshooting

rtk gain fails after cargo install rtk

Wrong package from crates.io. Reinstall from source:

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

Hook not intercepting commands

rtk init --show                  # Check hook installation status
rtk init -g                      # Reinstall hook
# Then restart your AI tool (Claude Code, Cursor, etc.)

Commands not compressed / hook bypassed

Built-in AI tool operations (Read, Grep, Glob in Claude Code) bypass the Bash hook. Use shell equivalents:

# Instead of Claude's Read tool, ask it to run:
rtk read src/main.rs
# Instead of Grep tool:
rtk grep "pattern" src/

PATH not found after quick install

export PATH="$HOME/.local/bin:$PATH"
# Persist it:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Wrong binary architecture (macOS)

Download the correct release asset:

• Apple Silicon: rtk-aarch64-apple-darwin.tar.gz
• Intel Mac: rtk-x86_64-apple-darwin.tar.gz

Verify savings are being tracked

rtk gain --history               # Should show recent commands
rtk session                      # Should show adoption %

If empty, the hook may not be active. Run rtk init --show.

---

How RTK Works Internally

RTK applies four compression strategies per command type:

1. Smart Filtering — removes comments, blank lines, boilerplate (Using gem..., progress bars)
2. Grouping — aggregates similar items (files by directory, errors by lint rule)
3. Truncation — keeps relevant context, discards redundant repetition
4. Deduplication — collapses repeated log lines with occurrence counts

Without RTK:
  Agent → "git status" → shell → git → ~2,000 tokens raw → Agent

With RTK:
  Agent → "git status" → RTK → git → filter/group/truncate → ~200 tokens → Agent

The binary runs in-process before output is returned to the shell, adding <10ms latency.

---

Supported AI Tools Summary

Tool	Command	Scope
Claude Code	rtk init -g	Global
GitHub Copilot	rtk init -g	Global
Cursor	rtk init -g --agent cursor	Global
Gemini CLI	rtk init -g --gemini	Global
Codex	rtk init -g --codex	Global
Windsurf	rtk init --agent windsurf	Project
Cline / Roo Code	rtk init --agent cline	Project
OpenCode	rtk init -g --opencode	Global

---

Quick Reference Card

# Setup
brew install rtk && rtk init -g && <restart AI tool>

# Most used
rtk git status / diff / log / add / commit / push
rtk cargo test / build / clippy
rtk pytest / go test / vitest run
rtk read <file> / rtk ls . / rtk grep <pat> <dir>
rtk tsc / rtk lint / rtk ruff check

# Analytics
rtk gain --graph
rtk discover

# Flags
rtk -u <cmd>   # ultra-compact
rtk -v <cmd>   # verbose/debug