RTK

https://github.com/rtk-ai/rtk
Admin
RTK (Rust Token Killer) is a high-performance CLI proxy that filters and compresses command outputs...
Tokens:336,827
Snippets:2,409
Trust Score:7.9
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### First-Time User Setup

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install RTK via cargo, initialize with prompts, and verify. Answer 'y' when prompted to patch settings.json; a backup is created automatically. Restart Claude Code after setup.

```bash
# 1. Install RTK
cargo install --git https://github.com/rtk-ai/rtk rtk
rtk gain  # Verify (must show the savings dashboard)

# 2. Setup with prompts
rtk init -g
# → Answer 'y' when prompted to patch settings.json
# → Creates backup automatically

# 3. Restart Claude Code
# 4. Test: git status (should use rtk)
```

--------------------------------

### Temporary Trial Setup and Removal

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install the hook with --auto-patch for a trial. Later, remove everything with --uninstall and restore the backup if needed.

```bash
# Install hook
rtk init -g --auto-patch

# Later: remove everything
rtk init -g --uninstall

# Restore backup if needed
cp ~/.claude/settings.json.bak ~/.claude/settings.json
```

--------------------------------

### Quick start commands for rtk llm-proxy

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/proxy/overview.md

Lists the main rtk llm-proxy subcommands: setup, start, status, stats, and stop. Run setup first to verify the daemon and see which agents can use it.

```bash
rtk llm-proxy setup     # check the daemon is present, list agents it can serve
rtk llm-proxy start     # launch it in the background (no-op if already up)
rtk llm-proxy status    # is it running and reachable?
rtk llm-proxy stats     # usage and savings from the running daemon
rtk llm-proxy stop      # ask it to shut down
```

--------------------------------

### CI/CD or Automation Setup

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Non-interactive setup with --auto-patch for automation. Verify the hook is installed using rtk init --show and grep for 'Hook:'.

```bash
# Non-interactive setup (no prompts)
rtk init -g --auto-patch

# Verify in scripts
rtk init --show | grep "Hook:"
```

--------------------------------

### Manual Installation from Git

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install RTK from the rtk-ai repository using cargo. Always verify after installation with `rtk gain`.

```bash
# From rtk-ai repository (NOT reachingforthejack!)
cargo install --git https://github.com/rtk-ai/rtk rtk

# ALWAYS VERIFY after installation
rtk gain  # MUST show the savings dashboard, not "command not found"
```

--------------------------------

### Quick Install (Windows)

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install RTK on Windows using winget.

```powershell
winget install rtk-ai.rtk
```

--------------------------------

### Conservative User Manual Setup

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Get manual instructions without patching using --no-patch. Review the printed JSON snippet, manually edit ~/.claude/settings.json, and restart Claude Code.

```bash
# Get manual instructions without patching
rtk init -g --no-patch

# Review printed JSON snippet
# Manually edit ~/.claude/settings.json
# Restart Claude Code
```

--------------------------------

### Verify RTK Installation

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Check the installed RTK version and view the token savings dashboard.

```bash
rtk --version   # rtk x.y.z
rtk gain        # shows token savings dashboard
```

--------------------------------

### Local Project Setup with rtk init

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Alternative setup for a single project without a hook. Adds the RTK block to ./CLAUDE.md and a .rtk/filters.toml template. Instructions are loaded only for this project.

```bash
cd /path/to/your/project
rtk init  # Adds the RTK block to ./CLAUDE.md and a .rtk/filters.toml template
```

--------------------------------

### Quick install via curl (Linux and macOS)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Installs RTK to ~/.local/bin. Add it to your PATH if needed.

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
```

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
```

--------------------------------

### Quick Install (Linux/macOS)

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install RTK via the official install script. After installation, verify the correct RTK is installed by running `rtk gain`.

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
```

```bash
rtk gain  # Must show the savings dashboard (not "command not found")
```

--------------------------------

### Pre-Installation Check: Verify RTK is installed and correct

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Run these commands to check if RTK is already installed and confirm it is the Token Killer (not Type Kit). If `rtk gain` works, the correct RTK is installed and you should skip installation.

```bash
# Check if RTK is installed
rtk --version

# CRITICAL: Verify it's the Token Killer (not Type Kit)
rtk gain    # Should show the savings dashboard, NOT "command not found"

# Check installation path
which rtk
```

--------------------------------

### Installation Verification Commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Basic tests to verify RTK is working: list files, git status, pnpm list, and vitest.

```bash
# Basic test
rtk ls .

# Test with git
rtk git status

# Test with pnpm
rtk pnpm list

# Test with Vitest
rtk vitest
```

--------------------------------

### Manual install on native Windows (rtk init -g)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Manual installation steps for native Windows: download the zip, add rtk.exe to PATH, and run `rtk init -g` to install the native binary hook. Re-run `rtk init -g` to migrate from the legacy `rtk-rewrite.sh` shell hook if you set up before v0.37.2.

```powershell
# 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
```

--------------------------------

### Check if RTK is already installed

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Run these commands to verify RTK is installed. If both work, skip to project initialization.

```bash
rtk --version   # should print: rtk x.y.z
rtk gain        # should show the savings dashboard
```

--------------------------------

### Install via Homebrew (macOS and Linux)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Installs RTK using Homebrew.

```bash
brew install rtk-ai/tap/rtk
```

--------------------------------

### Global Hook-First Setup with rtk init -g

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Recommended setup for all projects. Registers the native rtk hook claude PreToolUse hook, creates ~/.claude/RTK.md, adds @RTK.md reference to ~/.claude/CLAUDE.md, and prompts to patch settings.json. Use --auto-patch to patch without prompting, --no-patch to print manual instructions, and --show to verify the hook is registered.

```bash
rtk init -g
# → Registers the native `rtk hook claude` PreToolUse hook
# → Creates ~/.claude/RTK.md (short awareness file)
# → Adds @RTK.md reference to ~/.claude/CLAUDE.md
# → Prompts: "Patch settings.json? [y/N]"
# → If yes: patches + creates backup (~/.claude/settings.json.bak)

# Automated alternatives:
rtk init -g --auto-patch    # Patch without prompting
rtk init -g --no-patch      # Print manual instructions instead

# Verify installation
rtk init --show  # Check the hook is registered
```

--------------------------------

### Initialize RTK for a single project

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Run `rtk init` to add the RTK block to `./CLAUDE.md` and create a `.rtk/filters.toml` template. This does not install a hook.

```bash
rtk init
```

--------------------------------

### Install via Cargo with explicit Git URL

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Use the explicit Git URL to avoid installing Rust Type Kit instead of Rust Token Killer.

```bash
cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
```

--------------------------------

### Install RTK on WSL (curl | sh)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Install RTK on WSL using the install script and initialize the hook. WSL behaves exactly like Linux.

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
rtk init -g
```

--------------------------------

### Verify RTK installation

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Check that RTK is installed correctly. `rtk --version` prints the version (e.g., `rtk x.y.z`), and `rtk gain` opens the savings dashboard. If `rtk gain` fails but `rtk --version` succeeds, you likely installed Rust Type Kit by mistake.

```bash
rtk --version   # rtk x.y.z
rtk gain        # savings dashboard
```

--------------------------------

### Fish -c wrapper rewrite examples

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Demonstrates that fish -c scripts are read as fish, so fish-specific syntax is left unchanged. The first line is rewritten, the second is not.

```bash
fish -c 'git status; cargo test'      # → fish -c 'rtk git status; rtk cargo test'
fish -c 'git status; and cargo test'  # unchanged
```

--------------------------------

### RTK Init Mode Selection

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Interactive prompt showing the three initialization modes: global hook-first (recommended), global hook-only (minimal), and single-project setup. Choose based on whether you want RTK active across all Claude Code projects or just one.

```text
  Do you want RTK active across ALL Claude Code projects?
  │
  ├─ YES → rtk init -g              (recommended)
  │         Hook + RTK.md (~10 tokens in context)
  │         Commands auto-rewritten transparently
  │
  ├─ YES, minimal → rtk init -g --hook-only
  │         Hook only, nothing added to CLAUDE.md
  │         Zero tokens in context
  │
  └─ NO, single project → rtk init
            RTK block in ./CLAUDE.md + .rtk/filters.toml template
            No hook, no global effect
```

--------------------------------

### Fish script wrap example with wrap_fish_scripts

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Shows a multi-line fish script that can be wrapped for explicit fish execution when wrap_fish_scripts = true under [hooks]. Off by default.

```fish
if test -d src
  git status
end
# → rtk run --shell fish -c 'if test -d src\n  git status\nend'
```

--------------------------------

### Initialize RTK globally with Claude Code hook

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Run `rtk init --global` to install the Claude Code hook, which is registered in `~/.claude/settings.json` and applies to every project.

```bash
rtk init --global
```

--------------------------------

### Example output after adding a pipeline

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/pipelines/commands.md

Example output from `rtk pipeline add` showing the installed file path, required auth export, and confirmation that the pipeline is active and merged with others.

```text
installed: ~/.config/rtk/pipelines/flash.toml
auth needed: export GEMINI_API_KEY=...   (upstream `flash` — task `bulk-read`)
active now, merged with your other pipelines — see `rtk pipeline show`
```

--------------------------------

### Install and initialize RTK for various AI agents

Source: https://github.com/rtk-ai/rtk/blob/develop/README.md

Run these commands to install RTK for your AI tool. Use the appropriate flag for your agent (e.g., --gemini for Gemini CLI, --codex for Codex, --agent cursor for Cursor). The -g flag applies global configuration. After installation, restart your AI tool and test with 'git status'.

```bash
rtk init -g                     # Claude Code / Copilot (default)
```

```bash
rtk init -g --gemini            # Gemini CLI
```

```bash
rtk init -g --codex             # Codex (OpenAI)
```

```bash
rtk init -g --agent cursor      # Cursor
```

```bash
rtk init --agent windsurf    # Windsurf
```

```bash
rtk init --agent cline          # Cline / Roo Code
```

```bash
rtk init --agent kilocode       # Kilo Code
```

```bash
rtk init --agent antigravity    # Google Antigravity
```

```bash
rtk init --agent kimi           # Kimi AI
```

```bash
rtk init -g --agent pi          # Pi
```

```bash
rtk init --agent omp            # Oh My Pi (OMP)
```

```bash
rtk init --agent hermes         # Hermes
```

```bash
rtk init -g --agent droid       # Factory Droid
```

```bash
rtk init --agent trae           # Trae (project: .trae/hooks.json)
```

```bash
rtk init -g --agent trae        # Trae global: ~/.trae and existing ~/.trae-cn
```

--------------------------------

### RTK pnpm commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

RTK compacts dependency trees, shows available updates, and runs silent installations.

```bash
rtk pnpm list     # Compact dependency tree
rtk pnpm outdated # Available updates
rtk pnpm install  # Silent installation
```

--------------------------------

### Initialize Mistral Vibe agent (user-scoped and hook-only)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Installs a pre_tool hook entry (match = "bash", command = "rtk hook vibe", strict = false) into ~/.vibe/hooks.toml. The --hook-only flag skips creating the ~/.vibe/prompts/rtk.md prompt file. Install is global-only because Vibe's hook registry is user-scoped. Re-running the installer is a no-op; the RTK entry is detected by its name = "rtk-rewrite" field and never duplicated.

```bash
rtk init -g --agent vibe                # user-scoped (~/.vibe/hooks.toml)
rtk init -g --agent vibe --hook-only    # skip the ~/.vibe/prompts/rtk.md prompt file
```

--------------------------------

### Initialize RTK for Factory Droid (user-scoped and project-scoped)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init -g --agent droid` for user-scoped installation (`~/.factory/hooks.json`) or `rtk init --agent droid` for project-scoped (`.factory/hooks.json`). Installs a `PreToolUse` hook (matcher `Execute`) into Droid's canonical `hooks.json`, falling back to `settings.json` only when it already has live `PreToolUse` hooks. Respects `$FACTORY_HOME_OVERRIDE`.

```bash
rtk init -g --agent droid    # user-scoped (~/.factory/hooks.json)
rtk init --agent droid       # project-scoped (.factory/hooks.json, commit to share)
```

--------------------------------

### Quoted shell wrapper rewrite example

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Shows how a simple quoted bash -c wrapper is rewritten to use rtk commands. The shell name is preserved.

```bash
bash -c "head foo && grep -R bar ."
# → bash -c "rtk read foo --head-lines 10 && rtk grep -R bar ."
```

--------------------------------

### RTK Configuration TOML Example

Source: https://github.com/rtk-ai/rtk/blob/develop/src/core/README.md

Example configuration file for RTK covering tracking, display, retriever, telemetry, hooks, and limits sections. Includes optional paths and mode-specific settings.

```toml
[tracking]
enabled = true
history_days = 90
database_path = "/custom/path/to/tracking.db"  # Optional

[display]
colors = true
emoji = true
max_width = 120

[retriever]
mode = "sqlite"             # sqlite (default) | tee (legacy files) | disabled
max_entry_bytes = 10485760  # sqlite: 10 MiB per entry
max_entries = 200           # sqlite: FIFO cap
retention_days = 30         # sqlite: 0 disables age eviction
compression = true          # sqlite: gzip blobs (lossless)
# database_path = "/custom/recall.db"
tee_max_files = 20          # tee mode: rotation
tee_max_file_size = 1048576 # tee mode: per-file cap
# tee_directory = "/custom/tee/dir"

[telemetry]
enabled = true

[hooks]
exclude_commands = ["curl", "playwright"]  # Never auto-rewrite these

[limits]
grep_max_results = 200
grep_max_per_file = 25
status_max_files = 15
status_max_untracked = 10
passthrough_max_chars = 2000

```

--------------------------------

### Git passthrough examples

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Any git subcommand not listed is run directly. Examples show rebase, cherry-pick, and tag.

```bash
rtk git rebase main        # Runs git rebase main
```

```bash
rtk git cherry-pick abc    # Runs git cherry-pick abc
```

```bash
rtk git tag v1.0.0         # Runs git tag v1.0.0
```

--------------------------------

### Run unsupported command via passthrough: rtk bypass make install

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Commands RTK doesn't recognize run through passthrough — output is unchanged, usage is tracked.

```bash
rtk bypass make install
```

--------------------------------

### rtk smart example output

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Example invocation and output of rtk smart on a source file, showing the generated summary.

```text
$ rtk smart src/tracking.rs
SQLite-based token tracking system for command executions.
Records input/output tokens, savings %, execution times with 90-day retention.
```

--------------------------------

### Install ripgrep on Windows (winget)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Install ripgrep (`rg`) on Windows via winget. Required by some filters to avoid `Binary 'rg' not found on PATH` warnings.

```powershell
winget install BurntSushi.ripgrep.MSVC
```

--------------------------------

### RTK file commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Use these commands to list files, read a file, and search for patterns with RTK's optimized output.

```bash
rtk ls .              # Compact tree view
rtk read file.rs      # Optimized reading
rtk grep "pattern" .  # Grouped search results
```

--------------------------------

### Initialize RTK for OpenCode and verify installation

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Initialize RTK for OpenCode, restart OpenCode, then verify the plugin is installed. Requires OpenCode 1.18.29 or newer; older versions install nothing and print the found version. Ensure `rtk` is on the PATH OpenCode sees, as the plugin only resolves it from PATH. Set `RTK_DISABLED=1` to confirm behavior.

```bash
rtk init --global --opencode
# restart OpenCode
rtk init --show    # should show "OpenCode: plugin installed"
```

--------------------------------

### Install and manage RTK hook with rtk init

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Commands to install, check, or uninstall the RTK hook and RTK.md. Use --auto-patch for non-interactive CI/CD, --hook-only to skip RTK.md, and --show to verify installation.

```bash
rtk init -g                     # Recommended install (hook + RTK.md)
rtk init -g --auto-patch        # Non-interactive (CI/CD)
rtk init -g --hook-only         # Hook only, without RTK.md
rtk init --show                 # Check the installation
rtk init -g --uninstall         # Uninstall
```

--------------------------------

### Pi: Install Hook (Local and Global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Install RTK hook for Pi with project-local or global scope. Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global). Pi auto-discovers extensions from both paths on startup.

```bash
# Project-local (default)
rtk init --agent pi
```

```bash
# Global — all projects
rtk init --agent pi --global
```

--------------------------------

### rtk gain command examples

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/AUDIT_GUIDE.md

Quick reference for the rtk gain command, covering default view, temporal breakdowns, export formats, combined flags, and reset options.

```bash
# Default summary view
rtk gain

# Temporal breakdowns
rtk gain --daily          # All days since tracking started
rtk gain --weekly         # Aggregated by week
rtk gain --monthly        # Aggregated by month
rtk gain --all            # Show all breakdowns at once

# Export formats
rtk gain --all --format json > savings.json
rtk gain --all --format csv > savings.csv

# Combined flags
rtk gain --graph --history --quota    # Classic view with extras
rtk gain --daily --weekly --monthly   # Multiple breakdowns

# Reset all tracking data
rtk gain --reset          # prompts [y/N] before deleting
rtk gain --reset --yes    # skip prompt (CI/scripts)
```

--------------------------------

### Install RTK via package managers

Source: https://github.com/rtk-ai/rtk/blob/develop/README.md

Install RTK on macOS/Linux with Homebrew, on Windows with winget, or via a curl script. The curl command pipes the install script directly to sh.

```bash
brew install rtk
```

```bash
winget install rtk-ai.rtk
```

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
```

--------------------------------

### Install RTK OSS Edition

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Install the Apache-2.0 licensed RTK binary without the BUSL-1.1 compression engine. Choose this if your policy does not allow a source-available license. Release assets are named rtk-oss-<target>, plus rtk-oss_amd64.deb and rtk-oss.x86_64.rpm. It does not include rtk pipeline, PostToolUse compression, or delegation tasks.

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | RTK_EDITION=oss sh
brew install rtk-ai/tap/rtk-oss
cargo install --git https://github.com/rtk-ai/rtk rtk --no-default-features
```

--------------------------------

### RTK git commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

RTK provides compact status, condensed logs, optimized diff, and confirms git operations with 'ok ✓' messages.

```bash
rtk git status        # Compact status
rtk git log -n 10     # Condensed logs
rtk git diff          # Optimized diff
rtk git add .         # → "ok ✓"
rtk git commit -m "msg"  # → "ok ✓ abc1234"
rtk git push          # → "ok ✓ main"
```

--------------------------------

### Initialize Antigravity agent (workspace and machine-scoped)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Installs an Antigravity plugin bundle. Workspace-scoped install places files in <repo>/.agents/plugins/rtk/, while machine-scoped install uses ~/.gemini/config/plugins/rtk/. The hooks.json maps PreToolUse on run_command to the native rtk hook antigravity binary, and rules/AGENTS.md carries the awareness file selected by awareness.level. Antigravity checks permissions after lifecycle hooks rewrite a command, so ensure permitted commands include rtk (e.g., command(rtk git status) or command(rtk *)).

```bash
rtk init --agent antigravity          # workspace-scoped (<repo>/.agents/plugins/rtk/)
rtk init -g --agent antigravity       # machine-scoped (~/.gemini/config/plugins/rtk/)
```

--------------------------------

### GitHub Copilot: Install Hook (Project and Global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Install RTK hook for GitHub Copilot (VS Code Chat + CLI). Project-scoped writes `.github/hooks/rtk-rewrite.json` and updates `.github/copilot-instructions.md`. User-scoped writes to `~/.copilot/hooks/` and `~/.copilot/copilot-instructions.md`, respecting `$COPILOT_HOME` if set.

```bash
rtk init --copilot            # project-scoped (.github/hooks/)
```

```bash
rtk init --global --copilot   # user-scoped (~/.copilot/hooks/, respects $COPILOT_HOME)
```

--------------------------------

### Install Apache-2.0 edition via script or Homebrew

Source: https://github.com/rtk-ai/rtk/blob/develop/README.md

Install the Apache-2.0 edition of RTK using the install script with the RTK_EDITION environment variable set to 'oss', or via Homebrew from the rtk-ai tap. This edition omits the compression engine and is licensed under Apache-2.0 only.

```bash
curl -fsSL .../install.sh | RTK_EDITION=oss sh
```

```bash
brew install rtk-ai/tap/rtk-oss
```

--------------------------------

### Trae: Install Hook (Project and Global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Install RTK hook for Trae with project-scoped or user-scoped options. Global install also updates `~/.trae-cn/hooks.json` if that directory exists. Both modes install the native `rtk hook trae` command as a `PreToolUse` hook for `RunCommand`.

```bash
rtk init --agent trae             # project-scoped (.trae/hooks.json)
```

```bash
rtk init --global --agent trae    # user-scoped (~/.trae/hooks.json)
```

--------------------------------

### Start daemon and launch Claude through it

Source: https://github.com/rtk-ai/rtk/blob/develop/proxy/README.md

Use these commands to start the rtk-proxy daemon if needed, check its status, and view savings. The daemon is a local background process driven by the rtk CLI.

```bash
rtk claude              # start the daemon if needed, then launch Claude through it
```

```bash
rtk llm-proxy status    # is it up
```

```bash
rtk gain                # savings, RTK and proxy side by side
```

--------------------------------

### rtk gain example output

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Illustrative output of `rtk gain` showing token savings summary and top commands.

```text
$ rtk gain
RTK Token Savings Summary
  Total commands:     1,000
  Total input:        2,000,000 tokens
  Total output:       400,000 tokens
  Total saved:        1,600,000 tokens (80%)
  Avg per command:    1,600 tokens saved

Top commands:
  git status    300x  -80%
  cargo test    150x  -90%
  git diff      100x  -75%
```

--------------------------------

### Preview RTK init with Verbose Output

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Combine `--dry-run` with `-v` to also print the full content RTK would write.

```bash
rtk init --global --dry-run -v
```

--------------------------------

### Initialize RTK for Claude Code

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Initialize RTK globally for Claude Code or for a single project. The global option installs a hook that automatically rewrites commands; restart your AI assistant after this step.

```bash
# For Claude Code (global — applies to all projects)
rtk init --global

# For a single project only (CLAUDE.md instructions, no hook)
cd /your/project && rtk init
```

--------------------------------

### rtk cargo install

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Runs cargo install with compact output, removing dependency compilation and keeping only the install result and errors.

```bash
rtk cargo install [args...]
```

--------------------------------

### Verify RTK installation

Source: https://github.com/rtk-ai/rtk/blob/develop/README.md

Check that the installed RTK binary is the correct package. The version command should output a current version, and the gain command should show the savings dashboard rather than 'command not found'.

```bash
rtk --version
```

```bash
rtk gain
```

--------------------------------

### Installation verification commands

Source: https://github.com/rtk-ai/rtk/blob/develop/hooks/copilot/rtk-awareness.md

Run these commands to verify RTK is installed correctly. `rtk --version` should print a version like `rtk X.Y.Z`, `rtk gain` should show a dashboard (not "command not found"), and `which rtk` verifies the correct binary path.

```bash
rtk --version   # Should print: rtk X.Y.Z
rtk gain        # Should show a dashboard (not "command not found")
which rtk       # Verify correct binary path
```

--------------------------------

### Initialize RTK for Windsurf

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init --global --agent windsurf` to create `.windsurfrules` in the current project.

```bash
rtk init --global --agent windsurf    # creates .windsurfrules in current project
```

--------------------------------

### Gemini CLI: Install Hook Globally

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Install RTK hook for Gemini CLI with `--global --gemini`.

```bash
rtk init --global --gemini
```

--------------------------------

### Install OpenClaw plugin

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Installs the RTK plugin for OpenClaw from the `openclaw/` directory. The plugin uses the `before_tool_call` hook and delegates to `rtk rewrite`. RTK keeps the deny gate; OpenClaw owns approval. The plugin runs `rtk rewrite` with `RTK_REWRITE_HOST=openclaw`, so RTK does not prompt for commands matching no rule. Commands containing command substitution or redirect to a file are never rewritten.

```bash
openclaw plugins install ./openclaw
```

--------------------------------

### Start proxy on a different address with --bind

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/proxy/overview.md

Starts the LLM proxy bound to a specific address and port instead of the default 127.0.0.1:8080. The same --bind flag is used by subcommands like stop, status, and stats to manage a proxy running on a non-default address.

```bash
rtk llm-proxy start --bind 127.0.0.1:9090
```

--------------------------------

### Checklist: Initialize the hook for different agents

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Commands to initialize RTK hook for Claude Code, Cursor, and OpenCode.

```bash
rtk init --global    # Claude Code
rtk init --global --agent cursor    # Cursor
rtk init --global --opencode  # OpenCode
```

--------------------------------

### Filtered Command Example (run_filtered)

Source: https://github.com/rtk-ai/rtk/blob/develop/src/cmds/README.md

Recommended pattern for filtered commands using run_filtered with stdout_only and tee. Exit code handling is automatic.

```rust
pub fn run(args: &[String], verbose: u8) -> Result<i32> {
    let mut cmd = resolved_command("mycmd");
    for arg in args { cmd.arg(arg); }
    if verbose > 0 { eprintln!("Running: mycmd {}", args.join(" ")); }

    runner::run_filtered(
        cmd, "mycmd", &display_args(args),
        filter_mycmd_output,
        runner::RunOptions::stdout_only().tee("mycmd"),
    )
}
```

--------------------------------

### Install Apache-2.0 edition via Homebrew

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/editions.md

Homebrew ships the Apache-2.0 edition as a separate formula.

```bash
brew install rtk-ai/tap/rtk-oss
```

--------------------------------

### Using config::limits() for tunable values

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/contributing/CODING_PRACTICES.md

Extract tunable values into named constants via config::limits() so users can adjust them through ~/.config/rtk/config.toml. Example from src/cmds/git/git_cmd.rs.

```rust
let limits = config::limits();
let max_files = limits.status_max_files;
let max_untracked = limits.status_max_untracked;
```

--------------------------------

### rtk pip commands

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/usage/FEATURES.md

Package list, outdated packages, and install. Auto-detects `uv` when available and uses it instead of `pip`.

```bash
rtk pip list              # Package list (auto-detects uv)
```

```bash
rtk pip outdated          # Outdated packages
```

```bash
rtk pip install <pkg>     # Install
```

--------------------------------

### Build the proxy daemon from source

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/proxy/overview.md

Builds the rtk-proxy daemon from a source checkout. Run from the repository root.

```bash
cargo build --release --manifest-path proxy/Cargo.toml
```

--------------------------------

### Fix: uninstall wrong rtk and install correct one

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Uninstalls the Rust Type Kit package and installs Rust Token Killer via the install script, then verifies with `rtk gain`.

```bash
cargo uninstall rtk
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
rtk gain    # should now show token savings stats
```

--------------------------------

### Uninstall Wrong RTK (Rust Type Kit)

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Use this command to uninstall the wrong RTK (Rust Type Kit) if it was accidentally installed.

```bash
cargo uninstall rtk
```

--------------------------------

### Initialize OMP agent (project-local and global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init --agent omp` to create `.omp/extensions/rtk.ts` locally, or add `--global` to create `~/.omp/agent/extensions/rtk.ts`. OMP loads the same extension file as Pi via its `legacy-pi-compat` layer. The global path follows `PI_CODING_AGENT_DIR`. RTK currently targets OMP's default profile and `.omp` project directory; named profiles and custom `PI_CONFIG_DIR` are not auto-detected.

```bash
# Project-local (default)
rtk init --agent omp

# Global — all projects
rtk init --agent omp --global
```

--------------------------------

### Complete Removal (Global Installations Only)

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Uninstall RTK globally. Removes the hook, context file, reference line, and registration. Restart Claude Code after uninstall.

```bash
# Complete removal (global installations only)
rtk init -g --uninstall

# What gets removed:
#   - Hook: the `rtk hook claude` entry (and any legacy ~/.claude/hooks/rtk-rewrite.sh)
#   - Context: ~/.claude/RTK.md
#   - Reference: @RTK.md line from ~/.claude/CLAUDE.md
#   - Registration: RTK hook entry from settings.json

# Restart Claude Code after uninstall
```

--------------------------------

### Check and add Cargo bin to PATH

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Use when the rtk command is not found after installation. Checks if the Cargo bin directory is in PATH, adds it if needed, and reloads the shell.

```bash
# Check PATH
echo $PATH | grep -o '[^:]*\.cargo[^:]*'

# Add to PATH if needed (~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc
```

--------------------------------

### Preview RTK init Changes with --dry-run

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

See exactly what `rtk init` would change without modifying anything. Every would-be file create/update/patch is printed with a `[dry-run] would ...` prefix and a `[dry-run] Nothing written.` footer. Nothing on disk is modified, no settings.json is patched, and the telemetry consent prompt is skipped.

```bash
rtk init --global --dry-run
```

--------------------------------

### Symptom: rtk not found after cargo install

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Shows the error output when rtk is not in PATH.

```bash
$ rtk --version
zsh: command not found: rtk
```

--------------------------------

### Migrate from Old CLAUDE.md Injection

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Automatically migrates from the old 137-line CLAUDE.md injection (pre-0.22) to hook-first mode. Removes the old block, installs hook + RTK.md, and adds @RTK.md reference.

```bash
rtk init -g  # Automatically migrates to hook-first mode
# → Removes old 137-line block
# → Installs hook + RTK.md
# → Adds @RTK.md reference
```

--------------------------------

### Run the diagnostic script

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Executes the installation diagnostic script from the RTK repository root. It verifies RTK installation and PATH, correct version, available features, Claude Code integration, and hook status.

```bash
bash scripts/check-installation.sh
```

--------------------------------

### Create a fixture from real command output

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/contributing/TECHNICAL.md

Use this command to capture real command output into a fixture file for testing. The fixture should be real output, not synthetic data.

```bash
kubectl get pods > tests/fixtures/kubectl_pods_raw.txt
```

--------------------------------

### RTK statistics commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

RTK provides a savings dashboard with optional ASCII graph and command history.

```bash
rtk gain              # Savings dashboard
rtk gain --graph      # With ASCII graph
rtk gain --history    # With command history
```

--------------------------------

### Update RTK to v0.23.1+

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Install the latest RTK from the master branch using cargo, then verify the version is 0.23.1 or later.

```bash
cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
rtk --version    # should be 0.23.1+
```

--------------------------------

### Symptom: rtk gain not a rtk command

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Shows the error output when running `rtk gain` with the wrong package installed.

```bash
$ rtk gain
rtk: 'gain' is not a rtk command. See 'rtk --help'.
```

--------------------------------

### Fix compilation error

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Use when compilation fails. Updates Rust, cleans and rebuilds the project, then reinstalls with --force.

```bash
# Update Rust
rustup update stable

# Clean and recompile
cargo clean
cargo build --release
cargo install --path . --force
```

--------------------------------

### Restore settings.json Backup

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Restore the backup of settings.json created by RTK before changes. Use if you need to revert the hook configuration.

```bash
cp ~/.claude/settings.json.bak ~/.claude/settings.json
```

--------------------------------

### rtk init Workflow Diagram

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/contributing/ARCHITECTURE.md

ASCII diagram showing the initialization flow for `rtk init [--global]`, including checking for existing CLAUDE.md, prompting the user, and writing a template. The template instructs to use the `rtk` prefix for commands and mentions benefits of reduced bash output.

```text
┌────────────────────────────────────────────────────────────────────────┐
│                      rtk init Workflow                                 │
└────────────────────────────────────────────────────────────────────────┘

$ rtk init [--global]
      ↓
Check existing CLAUDE.md:
  • --global? → ~/.config/rtk/CLAUDE.md
  • else      → ./CLAUDE.md
      ↓
      ├─ Exists? → Warn user, ask to overwrite
      └─ Not exists? → Continue
      ↓
Prompt: "Initialize rtk for LLM usage? [y/N]"
      ↓ Yes
Write template:
┌─────────────────────────────────────┐
│ # CLAUDE.md                         │
│                                     │
│ Use `rtk` prefix for commands:      │
│ - rtk git status                    │
│ - rtk lint                          │
│ - rtk test                          │
│                                     │
│ Benefits: ≥20% less bash output     │
└─────────────────────────────────────┘
      ↓
Success: "✓ Initialized rtk for LLM integration"
```

--------------------------------

### Check savings with rtk gain

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/quick-start.md

Run after a few commands to see how much was saved. Output shows total commands, input/output tokens, and saved tokens with percentage.

```bash
rtk gain
```

```text
Total commands : 10
Input tokens   : 50,000
Output tokens  : 5,000
Saved          : 45,000  (90.0%)
```

--------------------------------

### Update RTK to latest release

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Use when the rtk command is not available (e.g., vitest). Forces a reinstall from the git repository and checks the version.

```bash
# Update to the latest release, then check the version
cargo install --git https://github.com/rtk-ai/rtk rtk --force
rtk --version
```

--------------------------------

### Binary Removal Commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

Remove the RTK binary via cargo or package manager. Includes commands for Homebrew, winget, apt, and dnf.

```bash
# If installed via cargo
cargo uninstall rtk

# If installed via package manager
brew uninstall rtk          # macOS Homebrew
winget uninstall rtk-ai.rtk # Windows winget
sudo apt remove rtk         # Debian/Ubuntu
sudo dnf remove rtk         # Fedora/RHEL
```

--------------------------------

### RTK test commands

Source: https://github.com/rtk-ai/rtk/blob/develop/INSTALL.md

RTK filters test output for various frameworks, showing failures only. The generic wrapper `rtk test` shows failures only.

```bash
rtk cargo test      # Filtered Cargo test output
rtk go test         # Filtered Go tests (NDJSON)
rtk jest            # Filtered Jest output
rtk vitest          # Filtered Vitest output
rtk playwright test # Filtered Playwright output
rtk pytest          # Filtered Python tests
rtk rake test       # Filtered Ruby tests
rtk rspec           # Filtered RSpec tests
rtk test <cmd> [args...]  # Generic test wrapper - failures only
```

--------------------------------

### Set proxy for one shell with --env

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/proxy/overview.md

Exports the environment variables needed to route any agent launched from that shell through the proxy. This is the manual equivalent of choosing 'Neither' in the guided setup.

```bash
eval "$(rtk llm-proxy start --env)"
```

--------------------------------

### rtk discover example output

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/analytics/discover.md

Illustrative output showing estimated missed savings. The ~N tokens are estimated bash output bytes divided by 4, not actual billed tokens.

```text
Missed savings analysis (last 7 days)
────────────────────────────────────
Command              Count   Est. lost
cargo test              12     ~48,000 tokens
git log                  8     ~12,000 tokens
pnpm list                3      ~6,000 tokens
────────────────────────────────────
Total missed:           23     ~66,000 tokens

Run `rtk init --global` to capture these automatically.
```

--------------------------------

### Launch agent with rtk claude

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/proxy/overview.md

Starts the daemon if needed, points the harness at it, and execs the real binary. No configuration is persisted. On Unix this is a genuine exec, so signals, stdio, and exit code behave as if launched directly.

```bash
rtk claude
```

--------------------------------

### Initialize RTK for Codex CLI (project and global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init --codex` for project-scoped (`.codex/hooks.json` + `AGENTS.md`) or `rtk init --global --codex` for user-global (`$CODEX_HOME` or `~/.codex/`). Restart Codex after installation; project-scoped hooks must be trusted when Codex prompts. The native `rtk hook codex` processor rewrites supported `Bash` commands via `PreToolUse.updatedInput`.

```bash
rtk init --codex           # project-scoped (.codex/hooks.json + AGENTS.md)
rtk init --global --codex  # user-global ($CODEX_HOME or ~/.codex/)
```

--------------------------------

### Claude Code: Initialize and Verify Hook

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init --global` to install the hook and patch settings.json, then restart Claude Code. Verify with `rtk init --show` to display hook status.

```bash
rtk init --global    # installs hook + patches settings.json
```

```bash
rtk init --show    # shows hook status
```

--------------------------------

### Fix compilation error during installation

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/troubleshooting.md

Update Rust to the latest stable version, clean the build, and reinstall RTK. Requires Rust 1.91 or newer (edition 2024 needs Cargo 1.85+).

```bash
rustup update stable
rustup default stable
cargo clean
cargo build --release
cargo install --path . --force
```

--------------------------------

### Uninstall OMP agent (project-local and global)

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/supported-agents.md

Run `rtk init --uninstall --agent omp` to remove the stock OMP extension locally, or add `--global` for the global file. Removes only the current or known historical stock extension. If the file was modified after install, a normal uninstall aborts with a message; `--dry-run` previews the refusal. Unreadable content causes a normal uninstall to exit nonzero, while `--dry-run` reports it and succeeds. Unrelated content is left in place.

```bash
rtk init --uninstall --agent omp
rtk init --uninstall --agent omp --global
```

--------------------------------

### Uninstall RTK

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/getting-started/installation.md

Remove RTK completely: `rtk init -g --uninstall` removes the hook, RTK.md, and settings.json entry; then uninstall the binary using the appropriate package manager (Cargo, Homebrew, or winget).

```bash
rtk init -g --uninstall    # remove hook, RTK.md, and settings.json entry
cargo uninstall rtk         # remove binary (if installed via Cargo)
brew uninstall rtk          # remove binary (if installed via Homebrew)
winget uninstall rtk-ai.rtk # remove binary (if installed via winget)
```

--------------------------------

### Install Apache-2.0 edition with RTK_EDITION=oss

Source: https://github.com/rtk-ai/rtk/blob/develop/docs/guide/resources/editions.md

Set RTK_EDITION=oss for the install script to install the Apache-2.0 edition.

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | RTK_EDITION=oss sh
```
Tokens:
Raw