rtk-ai/rtk

High-performance CLI proxy that cuts up to 90% of the bash output your agent reads

Website • Install • Troubleshooting • Architecture • Discord

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

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

RTK intercepts shell commands and compresses their output before your agent reads it.

RTK cuts up to 90% of the bash output your agent reads. That is what RTK measures, and it is not the same as cutting your bill by 90%.

Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. The reduction dilutes at every step.

The token counts RTK reports are estimated as bytes / 4 — RTK ships no tokenizer, so the percentages are reliable but the absolute token numbers are approximate.

Full explanation: How RTK Savings Work

brew install rtk

Easiest way to install on Windows — one command, no PATH setup needed:

winget install rtk-ai.rtk

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 install --git https://github.com/rtk-ai/rtk

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

Windows users: Extract the zip and place rtk.exe somewhere in your PATH (e.g. C:\Users\<you>\.local\bin). Run RTK from Command Prompt, PowerShell, or Windows Terminal — do not double-click the .exe (it will flash and close). The full hook system works natively on Windows (and in WSL). See Windows setup below for details.

rtk --version   # Should show "rtk 0.28.2"
rtk gain        # Should show the savings dashboard

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.

# 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 -g --agent windsurf    # Windsurf
rtk init --agent cline          # Cline / Roo Code
rtk init --agent kilocode       # Kilo Code
rtk init --agent antigravity    # Google Antigravity
rtk init --agent kimi           # Kimi AI
rtk init -g --agent pi          # Pi
rtk init --agent omp            # Oh My Pi (OMP)
rtk init --agent hermes         # Hermes
rtk init -g --agent droid       # Factory Droid
rtk init --agent trae           # Trae (project: .trae/hooks.json)
rtk init -g --agent trae        # Trae global: ~/.trae and existing ~/.trae-cn

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

Hook-based agents rewrite Bash commands (e.g., git status -> rtk git status) before execution. Plugin-based agents, including Hermes, use their plugin API to rewrite commands before execution. The agent receives compact output without needing to call rtk explicitly.

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.

  Without rtk:                                    With rtk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |         full raw output           |            |  compact output      | 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

Does RTK break Claude's prompt cache? No. RTK filters output once per command. The result is stored in history and cached normally on subsequent API calls, so the cache keeps working as expected. Smaller outputs also mean cheaper cache writes and reads. See Troubleshooting for details.

Percentages below are reductions in bash output, not reductions in your bill. See How Savings Work.

rtk ls .                        # Compact 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 (exit 0: identical, 1: different, 2: read error)

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"

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

rtk jest                        # Jest compact (failures only)
rtk vitest                      # Vitest compact (failures only)
rtk playwright test             # E2E results (failures only)
rtk pytest                      # Python tests (-90%)
rtk phpt                        # PHP .phpt tests (run-tests.php, -99%)
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%+)
rtk err <cmd> [args...]         # Direct argv execution, errors/warnings only
rtk test <cmd> [args...]        # Direct argv execution, failures only (-90%)
rtk err --shell fish '<script>' # Explicit shell for shell-specific syntax

rtk lint                        # ESLint grouped by rule/file
rtk lint biome                  # Supports other linters
rtk sqlfluff lint               # SQL linting (JSON, -75%)
rtk sqlfluff lint models/       # Lint a specific directory (pass path after `lint`)
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%+)
rtk mvnd verify                 # Maven Daemon (same filters as rtk mvn)
rtk sbt test                    # ScalaTest output (-90%)
rtk sbt compile                 # Compilation errors only (-75%)
rtk sbt run                     # Strip SBT preamble noise

rtk pnpm list                   # Compact dependency tree
rtk uv run pytest               # Preserve uv env, keep program output
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)

rtk bun install                  # Strip progress and version lines
rtk bun test                     # Failures only (-90%)
rtk bun build                    # Errors only when writing to disk, else passthrough
rtk bunx tsc                     # Smart routing to tsc filter
rtk deno test                    # Failures only (-90%)
rtk deno lint                    # Strip download lines + tee recovery
rtk deno check                   # Strip download lines + tee recovery

rtk aws sts get-caller-identity # One-line identity
rtk aws ec2 describe-instances  # Compact instance list
rtk aws lambda list-functions   # Name/runtime/memory (strips secrets)
rtk aws logs get-log-events     # Timestamped messages only
rtk aws cloudformation describe-stack-events  # Failures first
rtk aws dynamodb scan           # Unwraps type annotations
rtk aws iam list-roles          # Strips policy documents
rtk aws s3 ls                   # Truncated with recall recovery

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
rtk oc get pods                 # OpenShift pod summary
rtk oc get services             # OpenShift service list
rtk oc logs <pod>               # Deduplicated logs

rtk pulumi preview              # Strip header/URL/duration noise
rtk pulumi up                   # Compact apply output
rtk pulumi destroy              # Compact destroy output
rtk pulumi refresh              # Drift summary
rtk pulumi stack                # Stack metadata (strips owner/timestamps)

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>                  # Truncate + save full output
rtk wget <url>                  # Download, strip progress bars
rtk summary <cmd> [args...]     # Direct argv execution + heuristic summary
rtk run <cmd> [args...]         # Raw direct execution (no filtering/tracking)
rtk run -c '<script>'           # Shell string via sh (cmd on Windows)
rtk run --shell fish -c '<script>' # Explicit shell for shell-specific syntax
rtk proxy <command>             # Raw passthrough + tracking

rtk run, rtk err, rtk test, and rtk summary preserve positional argument boundaries and do not expand globs, variables, or operators by default. Use -c with rtk run, or --shell <name> with the filtered wrappers, only when a command intentionally requires shell syntax. Pass an explicit shell script as one quoted argument; RTK does not infer the parser from $SHELL because the environment value may differ from the actual command executor.

A program that cannot be run answers the way the shell used to: 127 with a command not found line, 126 for a path that exists but is a directory or is not executable.

Windows note. The cmd /C string these commands used to build also searched the working directory and carried cmd's builtins (echo, dir, type, set, copy, del, …). Direct execution resolves through %PATH% and PATHEXT only, so rtk err dir, rtk summary echo hi, and a tool sitting in the current directory now need the explicit form: rtk run -c 'dir', or rtk err --shell cmd 'echo hi'. On Unix nothing equivalent is lost — sh does not search ., and echo, test and pwd all exist as real binaries. One more difference on both platforms: the child sees the resolved absolute path in argv[0] where the shell used to pass the spelling as typed, which matters only to multi-call binaries and to tools that print usage from argv[0].

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

-u, --ultra-compact    # ASCII icons, inline format (further output reduction)
-v, --verbose          # Increase verbosity (-v, -vv, -vvv)

Directory listing:

# ls -la (45 lines)                     # rtk ls (12 lines)
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)                    # rtk git push (1 line)
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
...

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, with no per-command context 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.

rtk init -g                 # Install hook + RTK.md (recommended)
rtk init -g --opencode      # Claude setup + OpenCode plugin
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.

By default RTK.md says nothing about RTK itself. Set [awareness] level = "high" in config.toml to let the agent know rtk gain / rtk proxy, or "full" for an agent without hook support (or not yet supported by RTK) so it prefixes rtk itself — see Configuration.

RTK works fully on native Windows. Since v0.37.2 the auto-rewrite hook runs as a native binary command (rtk hook claude) — no Unix shell, bash, or jq required — so commands are rewritten transparently on Command Prompt, PowerShell, and Windows Terminal, just like on Linux and macOS.

Prefer winget if you can — it handles PATH for you.

# 1. Download and extract rtk-x86_64-pc-windows-msvc.zip from releases
# 2. Add rtk.exe to your PATH (e.g. C:\Users\<you>\.local\bin)
# 3. Initialize — installs the native binary hook
rtk init -g

Upgrading from an older install? Before v0.37.2, rtk init -g on native Windows fell back to CLAUDE.md injection and registered no hook. Re-run rtk init -g and answer y when it asks to patch settings.json (or pass --auto-patch) to install the native binary hook.

Prerequisites: some filters shell out to ripgrep (rg). Install it and keep it on your PATH (e.g. winget install BurntSushi.ripgrep.MSVC) to avoid Binary 'rg' not found on PATH warnings.

Important: Do not double-click rtk.exe — it is a CLI tool that prints usage and exits immediately. Always run it from a terminal (Command Prompt, PowerShell, or Windows Terminal).

WSL also works and behaves exactly like Linux:

# Inside WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g

RTK supports 18 AI coding tools. Each integration rewrites shell commands to rtk equivalents, reducing the bash output the agent reads where the agent supports command interception.

For per-agent setup details, override controls, and graceful degradation, see the Supported Agents guide. The Hermes plugin source and tests live in hooks/hermes/; installed Hermes runtime files still live under ~/.hermes/plugins/rtk-rewrite/.

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

[hooks]
exclude_commands = ["curl", "playwright"]  # skip rewrite for these (matches `npx playwright` too)
suppress_hook_warning = false                # suppress the missing-hook warning only

[retriever]
mode = "sqlite"         # sqlite (default) | tee (legacy files) | disabled

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

FAILED: 2/15 tests
[full output: rtk recall 3f9c2a81d4e7]

Legacy [tee] config sections are still honored: they map to mode = "tee" (file-based recovery on failure/truncation), or mode = "disabled" if you had enabled = false. The former mode = "always" keeps its behaviour and maps to tee_on_success = true, which archives successful runs too. The sqlite store stays failure/truncation-driven.

For the full config reference (all sections, env vars, per-project filters), see the Configuration guide.

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

• rtk-ai.app/guide — full user guide (installation, supported agents, what gets optimized, analytics, configuration, troubleshooting)
• INSTALL.md — detailed installation reference
• ARCHITECTURE.md — system design and technical decisions
• CONTRIBUTING.md — contribution guide
• SECURITY.md — security policy

RTK can collect anonymous, aggregate usage metrics once per day. Telemetry is disabled by default and requires explicit opt-in consent (GDPR Art. 6, 7) during rtk init or via rtk telemetry enable. 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:

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.

Manage telemetry:

rtk telemetry status     # Check current consent state
rtk telemetry enable     # Give consent (interactive prompt)
rtk telemetry disable    # Withdraw consent — stops all collection immediately
rtk telemetry forget     # Withdraw consent + delete all local data + request server-side erasure

Override via environment:

export RTK_TELEMETRY_DISABLED=1   # Blocks telemetry regardless of consent

• Patrick Szymkowiak — Founder GitHub · LinkedIn
• Florian Bruniaux — Core contributor GitHub · LinkedIn
• Adrien Eppling — Core contributor GitHub · LinkedIn
• Nicolas Le Cam — Core contributor Github · LinkedIn
• Takayuki Maeda — Core contributor GitHub · LinkedIn

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

Join the community on Discord.

Apache License 2.0 - see LICENSE for details.

See DISCLAIMER.md.