### First-Time User Installation and Setup

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

Installs RTK using Cargo, verifies its functionality, and sets up the project with prompts. Ensure to restart Claude Code after setup.

```bash
# 1. Install RTK
car go install --git https://github.com/rtk-ai/rtk
rtk gain  # Verify (must show token stats)

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

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

### Basic Command Tracking Example

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

Demonstrates how to use `TimedExecution` to start a timer, execute commands, and track their execution details.

```rust
use rtk::tracking::{TimedExecution, Tracker};

fn main() -> anyhow::Result<()> {
    // Start timer
    let timer = TimedExecution::start();

    // Execute command
    let input = execute_original_command()?;
    let output = execute_rtk_command()?;

    // Track execution
    timer.track("ls -la", "rtk ls", &input, &output);

    Ok(())
}
```

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

### Initialize RTK for Global Use (Recommended)

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

Set up RTK globally for all projects, installing a hook and creating a minimal RTK.md file. This is the recommended setup for automatic RTK usage.

```bash
rtk init -g
```

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

### RTK Auto-Rewrite Hook Setup (Recommended)

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

Installs the RTK auto-rewrite hook and RTK.md for seamless command conversion. Use --opencode for OpenCode plugin or --auto-patch for non-interactive setup.

```bash
rtk init -g                 # Install hook + RTK.md (recommended)
rtk init -g --opencode      # OpenCode plugin (instead of Claude Code)
rtk init -g --auto-patch    # Non-interactive (CI/CD)
rtk init -g --hook-only     # Hook only, no RTK.md
rtk init --show             # Verify installation
```

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

### Quick Install RTK (Linux/macOS)

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

Installs RTK using a script from GitHub. Installs to ~/.local/bin and may require adding to PATH.

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

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

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

### Install RTK with Windsurf Support

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

Installs RTK globally and configures it for Windsurf, using project-scoped .windsurfrules.

```bash
rtk init -g --agent windsurf
```

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

### Install RTK with Kilo Code Support

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

Installs RTK with project-scoped .kilocode/rules/rtk-rules.md for Kilo Code.

```bash
rtk init --agent kilocode
```

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

### Install RTK with OpenCode Support

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

Installs RTK globally and configures it for OpenCode, using a Plugin TS with tool.execute.before.

```bash
rtk init -g --opencode
```

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

### Conservative User Manual Setup

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

Provides manual instructions for setup without automatically patching settings.json. Requires manual editing of the settings file.

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

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

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

### Proxy Mode Examples

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

Examples demonstrating the RTK proxy mode for executing commands without filtering but tracking usage metrics.

```bash
rtk proxy git log --oneline -20
rtk proxy npm install express
rtk proxy curl https://api.example.com/data
```

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

### Install RTK Hook for GitHub Copilot (VS Code Chat + CLI)

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

Installs RTK hooks for GitHub Copilot. Supports both project-scoped and user-scoped installations. Project-scoped installs to .github/hooks/, user-scoped to ~/.copilot/hooks/. Both respect $COPILOT_HOME.

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

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

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

### Verify RTK Installation

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

Run these commands to ensure RTK is installed and to view the token savings dashboard.

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

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

### Install RTK with Google Antigravity Support

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

Installs RTK with project-scoped .agents/rules/antigravity-rtk-rules.md for Google Antigravity.

```bash
rtk init --agent antigravity
```

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

### Install RTK Extension for Pi

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

Installs the RTK extension for Pi. Supports both project-local and global installations. Pi auto-discovers extensions from .pi/extensions/ (local) or ~/.pi/agent/extensions/ (global).

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

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

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

### RTK Configuration Example

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

Example TOML configuration for RTK, showing how to exclude commands from rewrite and control output saving.

```toml
[hooks]
exclude_commands = ["curl", "playwright"]  # skip rewrite for these

[tee]
enabled = true          # save raw output on failure (default: true)
mode = "failures"       # "failures", "always", or "never"

```

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

### CI/CD or Automation Setup

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

Performs a non-interactive setup for CI/CD or automation environments. Verifies the hook is active in scripts.

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

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

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

### Install RTK with Gemini CLI Support

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

Installs RTK globally and configures it for Gemini CLI, using a BeforeTool hook.

```bash
rtk init -g --gemini
```

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

### Manual Install RTK via Cargo

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

Install RTK manually using Cargo, either from the official repository or crates.io. Always verify the installation afterward.

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

# OR (if published and correct on crates.io)
cargo install rtk

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

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

### Install RTK with Pi Support

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

Installs RTK globally and configures it for Pi AI, using a TypeScript extension for tool_call.

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

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

### TOML Configuration Example

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

Illustrates common configuration settings for tracking, display, tee output, telemetry, hooks, and limits within RTK.

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

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

[tee]
enabled = true
mode = "failures"  # failures | always | never
max_files = 20
max_file_size = 1048576
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
```

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

### Gemini CLI Input/Output Examples

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

Input and output examples for the Gemini CLI integration. The first output shows a rewritten command, while the second shows a 'allow' decision with no rewrite.

```json
{
  "tool_name": "run_shell_command",
  "tool_input": { "command": "git status" }
}
```

```json
{
  "decision": "allow",
  "hookSpecificOutput": {
    "tool_input": { "command": "rtk git status" }
  }
}
```

```json
{"decision": "allow"}
```

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

### Install RTK with Cursor Support

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

Installs RTK globally and configures it for Cursor AI, using a PreToolUse hook defined in hooks.json.

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

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

### Install RTK with GitHub Copilot CLI Support

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

Installs RTK globally and configures it for GitHub Copilot CLI, using a PreToolUse hook with deny-with-suggestion.

```bash
rtk init -g --copilot
```

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

### Quick Install RTK via Curl

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

Use this command for a quick installation of RTK on Linux and macOS systems.

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

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

### Install RTK with Codex Support

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

Installs RTK globally and configures it for Codex. Refer to AGENTS.md and RTK.md for detailed instructions.

```bash
rtk init -g --codex
```

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

### Copilot CLI Input/Output Example

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

Example of input and output for the Copilot CLI integration. The input specifies a tool and its arguments, while the output indicates a 'deny' decision with a suggestion for a more optimized RTK command.

```json
{
  "toolName": "bash",
  "toolArgs": "{\"command\": \"git status\"}"
}
```

```json
{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Token savings: use `rtk git status` instead"
}
```

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

### Check RTK Installation and Version

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

Verify if RTK is installed and ensure it's the correct 'Rust Token Killer' version by checking its commands.

```bash
rtk --version
```

```bash
rtk gain    # Should show token savings stats, NOT "command not found"
```

```bash
which rtk
```

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

### Install RTK with Cline / Roo Code Support

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

Installs RTK with project-scoped .clinerules for Cline or Roo Code.

```bash
rtk init --agent cline
```

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

### Install OpenClaw RTK Rewrite Plugin

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

Manually install the plugin by copying files to OpenClaw's extensions directory and restarting the gateway.

```bash
mkdir -p ~/.openclaw/extensions/rtk-rewrite
cp openclaw/index.ts openclaw/openclaw.plugin.json ~/.openclaw/extensions/rtk-rewrite/
```

```bash
openclaw gateway restart
```

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

### Install RTK via Cargo (Explicit Git URL)

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

Install RTK using Cargo, specifying the Git repository to avoid name collisions with other Rust projects. This ensures you install the correct 'Rust Token Killer' package.

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

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

### Uninstalling Rust Type Kit and Installing Rust Token Killer

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

Use this command sequence if you accidentally installed the wrong 'rtk' package. It first removes the conflicting package and then installs the correct one from the official source.

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

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

### Install RTK via Homebrew

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

Install RTK on macOS and Linux using the Homebrew package manager.

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

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

### Initialize Google Antigravity Agent

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

Creates `.agents/rules/antigravity-rtk-rules.md` for custom instructions. RTK guides Antigravity to prefer `rtk <cmd>` over raw commands.

```bash
rtk init --agent antigravity    # creates .agents/rules/antigravity-rtk-rules.md in current project
```

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

### Compound Command Rewrite Example

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

Example illustrating how compound commands with '&&' are rewritten, with both sides of the operator being processed by RTK.

```text
cargo fmt --all && cargo test becomes rtk cargo fmt --all && rtk cargo test
```

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

### Install RTK Hook for Gemini CLI

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

Installs the RTK global hook for Gemini CLI integration.

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

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

### Install RTK Plugin for OpenCode

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

Installs the RTK plugin for OpenCode, creating a TypeScript plugin file in ~/.config/opencode/plugins/rtk.ts. Uses the `tool.execute.before` hook.

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

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

### Temporary Trial Installation and Removal

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

Installs the RTK hook with auto-patching for a temporary trial. Includes commands to remove everything later and restore from backup.

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

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

### Verify Installation After Reinstall

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

After potential uninstallation or if unsure about the correct version, verify the RTK installation using version and gain commands.

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

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

### Install RTK via Homebrew or Script

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

Install RTK, a prerequisite for the OpenClaw plugin. Ensure RTK is available in your system's PATH.

```bash
brew install rtk
```

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

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

### Running RTK Installation Diagnostic Script

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

Execute the provided diagnostic script from the RTK repository root to check for common installation problems and verify features.

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

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

### Basic Installation Verification

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

Performs basic verification tests for RTK installation using common commands like `ls`, `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
```

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

### Daily Breakdown Output Example

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

Example of the daily breakdown output format for RTK token savings. Displays metrics like commands, input/output tokens, saved tokens, and savings percentage per day.

```text
📅 Daily Breakdown (3 days)
════════════════════════════════════════════════════════════════
Date            Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────
2026-01-28        89     380.9K      26.7K     355.8K   93.4%
2026-01-29       102     894.5K      32.4K     863.7K   96.6%
2026-01-30         5        749         55        694   92.7%
────────────────────────────────────────────────────────────────
TOTAL            196       1.3M      59.2K       1.2M   95.6%
```

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

### CSV Export Schema Example

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

Provides an example of the CSV format for exporting daily statistics, including command counts, token usage, and timing metrics.

```csv
date,commands,input_tokens,output_tokens,saved_tokens,savings_pct,total_time_ms,avg_time_ms
2026-02-03,42,15420,3842,11578,75.08,8450,201
2026-02-02,38,14230,3557,10673,75.00,7600,200
2026-02-01,45,16890,4223,12667,75.00,9000,200
```

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

### Command Rewrite Example

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

Illustrates the result of the command rewriting process, where original commands are transformed into RTK commands for specific actions. This example shows a compound command being rewritten.

```shell
Result: rtk cargo fmt --all && rtk cargo test 2>&1 | tail -20
```

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

### Install OpenClaw Plugin with RTK

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

Installs the OpenClaw plugin from a local directory. The plugin uses the `before_tool_call` hook and delegates rewrite decisions to `rtk rewrite`.

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

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

### Installing RTK with WSL for Full Hook Support on Windows

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

For full auto-rewrite hook support on Windows, use the Windows Subsystem for Linux (WSL). Install RTK within WSL.

```bash
# Inside WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g    # full hook mode works in WSL
```

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

### Multi-part Pull Request Example

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

Illustrates how to structure large features or refactors into multiple, independently mergeable pull requests.

```git
feat(Part 1): Add data model and tests
feat(Part 2): Add CLI command and integration
feat(Part 3): Update documentation
```

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

### Command Builder Example

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

Demonstrates how to construct a tool command using `Command::new` and arguments, specifically for generating JSON output from a tool like vitest.

```rust
Command::new("vitest").arg("--reporter=json")
```

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

### Install RTK Adapter for Hermes

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

Installs the RTK adapter for Hermes, creating a plugin in ~/.hermes/plugins/rtk-rewrite/. This adapter mutates the Hermes `terminal` tool's `command` before execution and delegates rewrite decisions to Rust via `rtk rewrite`. The plugin fails open, ensuring Hermes runs the original command if RTK is unavailable or encounters errors.

```bash
rtk init --agent hermes
```

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

### Example Command Trace

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

Traces the execution flow of a complex command through the RTK rewrite pipeline, showing each step and its corresponding Rust module.

```text
LLM Agent: "cargo fmt --all && cargo test 2>&1 | tail -20"
  |
  |  Hook shell (hooks/claude/rtk-rewrite.sh)
  |  Reads JSON from agent, extracts command, calls `rtk rewrite "$CMD"`
  |  On failure (jq missing, rtk missing, old version): exit 0 (passthrough)
  |
  v
rewrite_cmd::run(cmd)                              [src/hooks/rewrite_cmd.rs]
  |  1. Load config → hooks.exclude_commands
  |  2. check_command(cmd) → Deny → exit(2)
  |  3. registry::rewrite_command(cmd, excluded)
  |     → None → exit(1)          (no RTK equivalent, passthrough)
  |     → Some + Allow → print, exit(0)
  |     → Some + Ask   → print, exit(3)
  |
  v
rewrite_command(cmd, excluded)                     [src/discover/registry.rs]
  |  Early exits:
  |  - Empty → None
  |  - Contains "<<" or "$((" (heredoc/arithmetic) → None
  |  - Simple "rtk ..." (no operators) → return as-is
  |  - Otherwise → rewrite_compound(cmd, excluded)
  |
  v
rewrite_compound(cmd, excluded)                    [src/discover/registry.rs]
  |
  |  Step 1 — Tokenize (lexer.rs)
  |  tokenize() produces typed tokens with byte offsets:
  |    Arg("cargo") Arg("fmt") Arg("--all")
  |    Operator("&& ")
  |    Arg("cargo") Arg("test") Redirect("2>&1")
  |    Pipe("|")
  |    Arg("tail") Arg("-20")
  |
  |  Step 2 — Split on operators, rewrite each segment
  |  Operator (&&, ||, ;) → rewrite both sides
  |  Pipe (|) → rewrite left side only, keep right side raw
  |             exception: find/fd before pipe → skip rewrite
  |  Shellism (&) → rewrite both sides (background)
  |
  |  Calls rewrite_segment() per segment:
  |    segment 1: "cargo fmt --all"
  |    segment 2: "cargo test 2>&1"
  |    after pipe: "tail -20" kept raw
  |
  v
rewrite_segment(seg, excluded)                     [src/discover/registry.rs]
  |
  |  Step 3 — Strip trailing redirects
  |  strip_trailing_redirects() re-tokenizes the segment:
  |    "cargo test 2>&1" → cmd_part="cargo test", redirect=" 2>&1"
  |  (simple commands like "cargo fmt --all" → no redirect, suffix is "")
  |
  |  Step 4 — Already RTK → return as-is
  |
  |  Step 5 — Special cases (short-circuit before classification)
  |  head -N / --lines=N → rewrite_line_range() → "rtk read file --max-lines N"
  |  tail -N / -n N / --lines N → rewrite_line_range() → "rtk read file --tail-lines N"
  |  head/tail with unsupported flag (-c, -f) → None (skip rewrite)
  |  cat with incompatible flag (-A, -v, -e) → None (skip rewrite)
  |
  |  Step 6 — classify_command(cmd_part) [see below]
  |  → Supported → check excluded list → continue
  |  → Unsupported/Ignored → None (skip rewrite)
  |
  |  Step 7 — Build rewritten command
  |  a. Find matching rule from rules.rs
  |  b. Extract env prefix (ENV_PREFIX regex, second pass — first was in classify)
  |     e.g. "GIT_SSH_COMMAND=\"ssh -o ...\" git push" → prefix="GIT_SSH_COMMAND=..."
  |  c. Guard: RTK_DISABLED=1 in prefix → None
  |  d. Guard: gh with --json/--jq/--template → None
  |  e. Apply rule's rewrite_prefixes: "cargo fmt" → "rtk cargo fmt"
  |  f. Reassemble: env_prefix + rtk_cmd + args + redirect_suffix
  |
  v
classify_command(cmd)                              [src/discover/registry.rs]
  |  1. Check IGNORED_EXACT (cd, echo, fi, done, ...)
  |  2. Check IGNORED_PREFIXES (rtk, mkdir, mv, ...)
  |  3. Strip env prefix with ENV_PREFIX regex (for pattern matching only)
  |  4. Normalize absolute paths: /usr/bin/grep → grep
  |  5. Strip git global opts: git -C /tmp status → git status
  |  6. Guard: cat/head/tail with redirect (>, >>) → Unsupported (write, not read)
  |  7. Match against REGEX_SET (60+ compiled patterns from rules.rs)
  |  8. Extract subcommand → lookup custom savings/status overrides
  |  9. Return Classification::Supported { rtk_equivalent, category, savings, status }
  |
  v
Result: "rtk cargo fmt --all && rtk cargo test 2>&1 | tail -20"
  |
  |  Hook response
  |  Hook wraps result in agent-specific JSON, returns to LLM agent
  |
  v
LLM Agent executes rewritten command
  (bash handles && and |, each rtk invocation is a separate process)

```

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

### Verify Token Counts with Tiktoken

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

Use the 'tiktoken' Python library to get precise token counts for files, as RTK's token estimation is a heuristic. Install 'tiktoken' via pip.

```bash
pip install tiktoken
```

```bash
git status > output.txt
```

```python
import tiktoken
enc = tiktoken.get_encoding('cl100k_base')
print(len(enc.encode(open('output.txt').read())), 'actual tokens')
```

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

### Initialize RTK for Local Project Use

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

Set up RTK for a single project by creating a local CLAUDE.md file with full RTK instructions. This method does not use a global hook.

```bash
cd /path/to/your/project
rtk init
```

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

### Clean and Recompile Project

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

Cleans the project build artifacts, recompiles in release mode, and installs the project locally. Use this to ensure a fresh build.

```bash
cargo clean
cargo build --release
cargo install --path . --force
```

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

### Passthrough Command Example

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

This command demonstrates how RTK executes an unsupported command directly, tracking its usage without filtering the output.

```bash
rtk proxy make install    # runs make install, tracks usage, no filtering
```

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

### Installing RTK from Git Repository

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

To avoid installing the wrong 'rtk' package from crates.io, always use the explicit Git URL for installation.

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

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

### Build and Run Commands with RTK

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

Demonstrates how to use `rtk` to optimize common Cargo build and run commands for token efficiency.

```bash
cargo build
rtk cargo build
cargo build --release
cargo run -- <command>
cargo install --path .
```

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

### RTK Bundle Install Command

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

Install Ruby gems with 'rtk bundle install'. This command strips the 'Using' lines from the output for a cleaner result.

```bash
rtk bundle install
```

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

### RTK Failure Output Example

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

Illustrates the message displayed when a command fails, indicating where the full output is logged for LLM review.

```text
FAILED: 2/15 tests
[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]

```

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

### Create Feature Branch Example

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

Command to create a new feature branch based on the 'develop' branch, following the project's naming convention.

```bash
git checkout develop
git pull origin develop
git checkout -b feat/scope-your-clear-description
```

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

### Verify RTK Installation

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

Check the installed RTK version and ensure the `rtk gain` command functions correctly to confirm the correct package is installed.

```bash
rtk --version
rtk gain
```

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

### TimedExecution Struct and Methods

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

Provides a helper for timing command execution. Use `start` to begin timing and `track` or `track_passthrough` to record execution details.

```rust
pub struct TimedExecution {
    start: Instant,
}

impl TimedExecution {
    /// Start timing a command execution
    pub fn start() -> Self;

    /// Track command with elapsed time
    pub fn track(&self, original_cmd: &str, rtk_cmd: &str, input: &str, output: &str);

    /// Track passthrough commands (timing-only, no token counting)
    pub fn track_passthrough(&self, original_cmd: &str, rtk_cmd: &str);
}
```

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

### Install RTK Hook for Cursor

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

Installs the RTK global hook for Cursor integration. The hook uses Cursor's `preToolUse` with `updated_input` format. Restart Cursor after installation.

```bash
rtk init --global --agent cursor
```

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

### Install RTK Hook for Claude Code

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

Installs the RTK global hook and patches settings.json for Claude Code integration. Restart Claude Code after installation and verify the hook status.

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

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

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

### Initialize RTK (Migrates to hook-first mode)

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

Initializes RTK, automatically migrating to hook-first mode. This removes the old block, installs the hook and RTK.md, and adds an @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
```

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

### Show and Create RTK Configuration

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

Use the `rtk config` command to view the current configuration or create a default configuration file.

```bash
rtk config            # show current configuration
rtk config --create   # create config file with defaults
```

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

### Initialize Windsurf Agent

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

Creates `.windsurfrules` in the current project for custom instructions.

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

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

### RTK Installation Verification Commands

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

Verify that RTK is installed correctly and accessible in your system's PATH.

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

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

### Initialize RTK Globally with No Patch

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

Initialize RTK globally and receive manual instructions for patching settings.json instead of automatic patching.

```bash
rtk init -g --no-patch
```

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

### Tokenization Example

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

Demonstrates how the lexer converts a raw command string into typed tokens, understanding shell quoting and operators. This is crucial for correctly parsing commands with quoted arguments.

```shell
"cargo test 2>&1 && git status"
→ [Arg("cargo"), Arg("test"), Redirect("2>&1"), Operator("&&"), Arg("git"), Arg("status")]
```

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

### Env Prefix Handling Example

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

Shows how environment variable assignments and prefixes like 'sudo' are stripped from the front of commands for classification and then re-appended after rewriting. Handles various quoting and chaining scenarios.

```shell
A="x y" B=1 sudo git status
```

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

### Python Pip Show Command Output Example

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

Illustrates the JSON output from `pip show <pkg>`, which provides metadata for a specific package. Key fields like name, version, and requirements are extracted from this output.

```json
{"name": "...", "version": "...", "requires": [...]}
```

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

### Golangci-lint Run Command Output Example

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

Shows the JSON output format for `golangci-lint run --out-format=json`. This output is parsed to group issues by linter rule and count violations, providing a summary format.

```json
{
  "Issues": [
    {"FromLinter": "errcheck", "Pos": {...}, "Text": "..."}
  ]
}
```

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

### Python/Go Module Overhead Benchmarks

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

Presents benchmark results comparing raw command execution time with RTK-processed time for Python and Go modules. It highlights the overhead introduced and the resulting savings.

```text
┌────────────────────────────────────────────────────────────────────────┐
│              Python/Go Module Overhead Benchmarks                      │
└────────────────────────────────────────────────────────────────────────┘

Command                 Raw Time    rtk Time    Overhead    Savings
─────────────────────────────────────────────────────────────────────────

ruff check              850ms       862ms       +12ms       83%
pytest                  1.2s        1.21s       +10ms       92%
pip list                450ms       458ms       +8ms        78%

go test                 2.1s        2.12s       +20ms       88%
go build (errors)       950ms       961ms       +11ms       80%
golangci-lint           4.5s        4.52s       +20ms       85%

Overhead Sources:
  • JSON parsing: 5-10ms (serde_json)
  • State machine: 3-8ms (regex + state tracking)
  • NDJSON streaming: 8-15ms (line-by-line JSON parse)
```

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

### Preview Initialization Changes with --dry-run

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

Use the --dry-run flag to see what changes RTK would make without modifying any files. Combine with -v to see the full content that would be written.

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

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

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

### Conventional Commit Examples

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

Examples of commit messages following the Conventional Commits specification, used for auto-generating changelogs and version bumps.

```git
feat(kubectl): add pod log filtering
fix(git): preserve merge commit messages in log filter
perf(cargo): lazy-compile clippy regex patterns
feat!(hook): change rewrite config format
```

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

### Module Integration Checklist

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

A checklist for integrating new Python/Go module support, covering output format preferences, failure focus, exit code preservation, virtual environment awareness, error grouping, streaming support, verbosity levels, token tracking, and unit tests.

```text
- [x] **Output Format**: JSON API > NDJSON > State Machine > Text Filters
- [x] **Failure Focus**: Hide passing tests, show failures only
- [x] **Exit Code Preservation**: Propagate tool exit codes for CI/CD
- [x] **Virtual Env Awareness**: Python modules respect active virtualenv
- [x] **Error Grouping**: Group by rule/file for linters (ruff, golangci-lint)
- [x] **Streaming Support**: Handle interleaved NDJSON events (go test)
- [x] **Verbosity Levels**: Support -v/-vv/-vvv for debug output
- [x] **Token Tracking**: Integrate with tracking::track()
- [x] **Unit Tests**: Test parsing logic with representative outputs
```

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

### Go Test Command Output Example (NDJSON)

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

Presents the NDJSON streaming output format for `go test` commands. This format allows for line-by-line JSON parsing to handle interleaved package events and aggregate results.

```json
{"Action": "run", "Package": "pkg1", "Test": "TestAuth"}
{"Action": "fail", "Package": "pkg1", "Test": "TestAuth"}
```

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

### Uninstall RTK via Cargo

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

Remove RTK if it was previously installed using Cargo. This is a necessary step if you accidentally installed the wrong package.

```bash
cargo uninstall rtk
```

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

### Go Build/Vet Command Output Example (Text Filtering)

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

Describes the text filtering strategy for `go build` and `go vet` commands, focusing on extracting error messages with file and line information.

```text
Errors only (compiler diagnostics)
→ Strip warnings, show errors with file:line
```

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

### Monthly Breakdown Output Example

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

Example of the monthly breakdown output format for RTK token savings. Aggregates metrics by calendar month (YYYY-MM).

```text
📆 Monthly Breakdown (1 months)
════════════════════════════════════════════════════════════════
Month         Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────
2026-01        196       1.3M      59.2K       1.2M   95.6%
────────────────────────────────────────────────────────────────
TOTAL          196       1.3M      59.2K       1.2M   95.6%
```

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

### Linting and Quality Checks with RTK

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

Illustrates using `rtk` to optimize commands for code linting and quality checks like formatting and Clippy.

```bash
cargo check
cargo fmt
cargo clippy --all-targets
rtk cargo clippy --all-targets
```

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

### Initialize RTK for a Project

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

Run this command once per project to enable the Claude Code hook. This sets up RTK for project-specific usage.

```bash
rtk init
```

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

### Troubleshooting RTK Installation Compilation Errors

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

If you encounter compilation errors during RTK installation, try updating Rust, cleaning the build, and rebuilding the release version.

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

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

### Load RTK Pi Extension Directly for Testing

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

Load the RTK Pi extension directly using the `pi -e` command for testing purposes without a formal installation.

```bash
pi -e ./hooks/pi/rtk.ts
```

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

### Weekly Breakdown Output Example

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

Example of the weekly breakdown output format for RTK token savings. Aggregates metrics by ISO week (Sunday to Saturday).

```text
📊 Weekly Breakdown (1 weeks)
════════════════════════════════════════════════════════════════════════
Week                      Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────────────
01-26 → 02-01              196       1.3M      59.2K       1.2M   95.6%
────────────────────────────────────────────────────────────────────────
TOTAL                      196       1.3M      59.2K       1.2M   95.6%
```