# Rtk

> RTK (Rust Token Killer) setup, configuration, and usage. Use when setting up RTK in a project, configuring custom filters, optimizing agent token usage, or troubleshooting RTK hooks and rewrites.

- Skill: `oornnery/rtk` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oornnery/rtk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oornnery/rtk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oornnery (https://skillmd.com/u/oornnery)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oornnery/rtk

---


# RTK

CLI proxy reduces LLM token consumption 60-90% on dev commands. Intercepts command output (git, test runners, linters, build tools), returns only essential info to agent context window.

- Single Rust binary, zero runtime deps
- <10ms overhead per command
- Fail-safe: falls back to raw output if filter breaks
- Preserves exit codes for CI/CD compatibility

## Installation

```bash
brew install rtk          # macOS (Homebrew)
cargo install rtk-ai      # From crates.io
```

Verify correct binary (name collision with another `rtk` package):

```bash
rtk --version    # Should show "rtk 0.31.0" or newer
rtk gain         # Should show token savings (NOT "command not found")
```

## Global Setup

Use `rtk init -g` for hook-based integration. Recommended approach -- transparently rewrites commands with zero manual effort:

```bash
rtk init -g
```

Installs:

- `~/.claude/hooks/rtk-rewrite.sh` — PreToolUse hook rewrites Bash commands through `rtk hook`
- `~/.claude/RTK.md` — slim reference (10 lines, minimal token cost)
- Hook entry in `~/.claude/settings.json`

After setup, all agent Bash commands auto-rewritten. Example: `git status` becomes `rtk git status` transparently.

### Other Agents

```bash
rtk init --agent cursor     # Cursor
rtk init --codex            # Codex CLI (base + variants)
```

Windsurf and Cline use rules files (`.windsurfrules`, `.clinerules`) generated by `rtk init`.

### Uninstall

```bash
rtk init -g --uninstall
```

## How It Works

Hook intercepts PreToolUse Bash events, rewrites commands via `rtk rewrite`, returns compressed output. Strategies: filtering (ANSI, boilerplate), grouping (errors by rule), truncation, deduplication.

## Supported Commands

- **Git**: status ~80%, log ~75-92%, diff ~70%, commit ~90%
- **Tests**: pytest/cargo test ~90%, vitest ~99%
- **Linters**: ruff/eslint ~80-84%, tsc/mypy ~80-83%
- **Builds**: cargo build ~80%, next build ~87%
- **File ops**: ls/tree ~80%, grep/rg ~75%, find/fd ~70%

## Meta Commands

Run directly -- never through proxy:

```bash
rtk gain              # Token savings dashboard
rtk gain --history    # Per-command history with savings %
rtk gain --graph      # Visual savings graph
rtk gain --project    # Scoped to current project
rtk discover          # Scan agent history for missed optimizations
rtk learn             # Detect project patterns, suggest optimizations
rtk session           # Adoption overview
rtk proxy <cmd>       # Run raw command (no filtering), still tracked
rtk rewrite "<cmd>"   # Preview what a command would be rewritten to
rtk config            # Show current configuration
rtk verify            # Integrity check
rtk hook-audit        # Audit hook installations
```

## Configuration

### User Config

`~/.config/rtk/config.toml`:

```toml
[tracking]
history_days = 90

[display]
colors = true
max_width = 120

[filters]
ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv"]

[hooks]
exclude = []          # commands to skip rewriting
```

Use `[hooks] exclude` to bypass rewriting where raw output needed.

### Custom Filters (TOML)

Declarative filter pipelines for commands RTK doesn't cover natively.

**Project-local**: `.rtk/filters.toml` (requires `rtk trust` for security)

**User-global**: `~/.config/rtk/filters.toml`

Example -- compress Terraform plan output:

```toml
[filters.terraform-plan]
command = "terraform"
subcommand = "plan"
strip_ansi = true
strip_lines_matching = ["Refreshing state...", "Reading...", "data\\."]
truncate_lines_at = 200
max_lines = 100
on_empty = "No changes detected"

[[filters.terraform-plan.replace]]
pattern = "Plan: (\\d+) to add"
replacement = "+$1"

[[tests.terraform-plan]]
input = "Refreshing state...\nPlan: 3 to add"
expected = "+3"
```

Pipeline stages (applied sequentially):

1. `strip_ansi` — remove escape codes
2. `replace` — regex substitutions (chainable)
3. `match_output` — short-circuit if pattern matches (with `unless`)
4. `strip_lines_matching` / `keep_lines_matching` — filter lines by regex
5. `truncate_lines_at` — limit line length
6. `head_lines` / `tail_lines` — retain first/last N lines
7. `max_lines` — absolute line cap
8. `on_empty` — fallback message if result empty

### Trust Gating

Project-local `.rtk/filters.toml` requires explicit trust:

```bash
rtk trust             # Trust current project's filters
rtk untrust           # Revoke trust
```

### Debugging

```bash
RTK_TOML_DEBUG=1 rtk <cmd>    # Log matched filters to stderr
RTK_DISABLED=1 <cmd>          # Bypass RTK entirely
RTK_NO_TOML=1 rtk <cmd>      # Bypass TOML filters only
rtk proxy <cmd>               # Run raw, still track usage
```

## File Reading Modes

`rtk read` filter levels: NoFilter (unchanged), MinimalFilter (strips comments/blanks), AggressiveFilter (imports + signatures only). Data formats (JSON, YAML, TOML) bypass aggressive filtering.

## Best Practices

- Use `rtk init -g` for global hook -- most transparent
- Let hook rewrite automatically, don't manually prefix
- Run `rtk gain` regularly, `rtk discover` for missed opportunities
- Use `rtk proxy <cmd>` for full unfiltered output
- Start with defaults; add TOML filters only for project-specific tools
- Include `[[tests]]` in custom filters
- Tee saves raw output on failures to `~/.local/share/rtk/tee/`