# Table of Contents - [RTK Documentation | RTK](#rtk-documentation-rtk) - [Token Savings Analytics | RTK](#token-savings-analytics-rtk) - [Discover and Session | RTK](#discover-and-session-rtk) - [Installation | RTK](#installation-rtk) - [Quick Start | RTK](#quick-start-rtk) - [What RTK Optimizes | RTK](#what-rtk-optimizes-rtk) - [Configuration | RTK](#configuration-rtk) - [Supported Agents | RTK](#supported-agents-rtk) - [Troubleshooting | RTK](#troubleshooting-rtk) - [Telemetry & Privacy | RTK](#telemetry-privacy-rtk) --- # RTK Documentation | RTK [Skip to content](https://www.rtk-ai.app/docs/#_top) RTK Documentation ================= RTK — Rust Token Killer ======================= [Section titled “RTK — Rust Token Killer”](https://www.rtk-ai.app/docs/#rtk--rust-token-killer) RTK is a CLI proxy that sits between your AI assistant and your development tools. It filters command output before it reaches the LLM, keeping only what matters and discarding boilerplate, progress bars, and noise. **Result:** 60-90% fewer tokens consumed per command, without changing how you work. You run `git status` as usual — RTK’s hook intercepts it, filters the output, and the LLM sees a compact 3-line summary instead of 40 lines. How it works ------------ [Section titled “How it works”](https://www.rtk-ai.app/docs/#how-it-works) Your AI assistant runs: git status ↓ Hook intercepts (PreToolUse) ↓ rtk git status (transparent rewrite) ↓ Raw output: 40 lines → Filtered: 3 lines ~800 tokens → ~60 tokens (92% saved) ↓ LLM sees the compact output Zero config changes to your workflow. The hook handles everything automatically. What RTK optimizes ------------------ [Section titled “What RTK optimizes”](https://www.rtk-ai.app/docs/#what-rtk-optimizes) Dozens of commands across all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See [What RTK Optimizes](https://www.rtk-ai.app/guide/resources/what-rtk-covers/) for the full list with savings percentages. Get started ----------- [Section titled “Get started”](https://www.rtk-ai.app/docs/#get-started) 1. **[Installation](https://www.rtk-ai.app/guide/getting-started/installation/) ** — Install RTK and verify you have the right package 2. **[Quick Start](https://www.rtk-ai.app/guide/getting-started/quick-start/) ** — Connect to your AI assistant in 5 minutes 3. **[Supported Agents](https://www.rtk-ai.app/guide/getting-started/supported-agents/) ** — Claude Code, Cursor, Copilot, Gemini, and more Measure your savings -------------------- [Section titled “Measure your savings”](https://www.rtk-ai.app/docs/#measure-your-savings) rtk gain # total savings across all sessionsrtk gain --daily # day-by-day breakdownrtk gain --weekly # weekly aggregation See [Token Savings Analytics](https://www.rtk-ai.app/guide/analytics/gain/) for export formats and analysis workflows. Analyze your usage ------------------ [Section titled “Analyze your usage”](https://www.rtk-ai.app/docs/#analyze-your-usage) rtk discover # find commands that ran without RTK (missed savings)rtk session # RTK adoption rate per Claude Code session See [Discover and Session](https://www.rtk-ai.app/guide/analytics/discover/) for details. Further reading --------------- [Section titled “Further reading”](https://www.rtk-ai.app/docs/#further-reading) * [Configuration](https://www.rtk-ai.app/guide/getting-started/configuration/) — config.toml, global flags, env vars, tee recovery * [Troubleshooting](https://www.rtk-ai.app/guide/resources/troubleshooting/) — common issues and fixes * [Telemetry & Privacy](https://www.rtk-ai.app/guide/resources/telemetry/) — what RTK collects and how to opt out * [ARCHITECTURE.md](https://github.com/rtk-ai/rtk/blob/master/ARCHITECTURE.md) — system design for contributors --- # Token Savings Analytics | RTK [Skip to content](https://www.rtk-ai.app/docs/analytics/gain/#_top) Token Savings Analytics ======================= Token Savings Analytics ======================= [Section titled “Token Savings Analytics”](https://www.rtk-ai.app/docs/analytics/gain/#token-savings-analytics) `rtk gain` shows how many tokens RTK has saved across all your commands, with daily, weekly, and monthly breakdowns. Quick reference --------------- [Section titled “Quick reference”](https://www.rtk-ai.app/docs/analytics/gain/#quick-reference) # Default summaryrtk gain # Temporal breakdownsrtk gain --daily # all days since tracking startedrtk gain --weekly # aggregated by weekrtk gain --monthly # aggregated by monthrtk gain --all # all breakdowns at once # Classic flagsrtk gain --graph # ASCII graph, last 30 daysrtk gain --history # last 10 commandsrtk gain --quota # monthly quota savings estimate (default tier: 20x)rtk gain --quota -t pro # use pro tier token budget for estimate # Exportrtk gain --all --format json > savings.jsonrtk gain --all --format csv > savings.csv Daily breakdown --------------- [Section titled “Daily breakdown”](https://www.rtk-ai.app/docs/analytics/gain/#daily-breakdown) rtk gain --daily 📅 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% * **Cmds**: RTK commands executed * **Input**: Estimated tokens from raw command output * **Output**: Actual tokens after filtering * **Saved**: Input - Output (tokens that never reached the LLM) * **Save%**: Saved / Input × 100 Weekly and monthly breakdowns ----------------------------- [Section titled “Weekly and monthly breakdowns”](https://www.rtk-ai.app/docs/analytics/gain/#weekly-and-monthly-breakdowns) rtk gain --weeklyrtk gain --monthly Same columns as daily, aggregated by Sunday-Saturday week or calendar month. Export formats -------------- [Section titled “Export formats”](https://www.rtk-ai.app/docs/analytics/gain/#export-formats) | Format | Flag | Use case | | --- | --- | --- | | `text` | default | Terminal display | | `json` | `--format json` | Programmatic analysis, dashboards | | `csv` | `--format csv` | Excel, Python/R, Google Sheets | **JSON structure:** { "summary": { "total_commands": 196, "total_input": 1276098, "total_output": 59244, "total_saved": 1220217, "avg_savings_pct": 95.62 }, "daily": [...], "weekly": [...], "monthly": [...]} Typical savings by command -------------------------- [Section titled “Typical savings by command”](https://www.rtk-ai.app/docs/analytics/gain/#typical-savings-by-command) | Command | Typical savings | Mechanism | | --- | --- | --- | | `git status` | 77-93% | Compact stat format | | `eslint` | 84% | Group by rule | | `jest` | 94-99% | Show failures only | | `vitest` | 94-99% | Show failures only | | `find` | 75% | Tree format | | `pnpm list` | 70-90% | Compact dependencies | | `grep` | 70% | Truncate + group | How token estimation works -------------------------- [Section titled “How token estimation works”](https://www.rtk-ai.app/docs/analytics/gain/#how-token-estimation-works) RTK estimates tokens using `text.len() / 4` (4 characters per token average). This is accurate to ±10% compared to actual LLM tokenization — sufficient for trend analysis. Input Tokens = estimate_tokens(raw_command_output)Output Tokens = estimate_tokens(rtk_filtered_output)Saved Tokens = Input - OutputSavings % = (Saved / Input) × 100 Database -------- [Section titled “Database”](https://www.rtk-ai.app/docs/analytics/gain/#database) Savings data is stored locally in SQLite: * **Location**: `~/.local/share/rtk/history.db` (Linux / macOS) * **Retention**: 90 days (automatic cleanup) * **Scope**: Global across all projects and Claude sessions # Inspect raw datasqlite3 ~/.local/share/rtk/history.db \ "SELECT timestamp, rtk_cmd, saved_tokens FROM commands ORDER BY timestamp DESC LIMIT 10" # Backupcp ~/.local/share/rtk/history.db ~/backups/rtk-history-$(date +%Y%m%d).db # Resetrm ~/.local/share/rtk/history.db # recreated on next command Analysis workflows ------------------ [Section titled “Analysis workflows”](https://www.rtk-ai.app/docs/analytics/gain/#analysis-workflows) # Weekly progress: generate a CSV report every Mondayrtk gain --weekly --format csv > reports/week-$(date +%Y-%W).csv # Monthly budget reviewrtk gain --monthly --format json | jq '.monthly[] | {month, saved_tokens, quota_pct: (.saved_tokens / 6000000 * 100)}' # Cron: daily JSON snapshot for a dashboard0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json **Python/pandas:** import pandas as pdimport subprocess result = subprocess.run(['rtk', 'gain', '--all', '--format', 'csv'], capture_output=True, text=True)lines = result.stdout.split('\n')daily_start = lines.index('# Daily Data') + 2daily_end = lines.index('', daily_start)daily_df = pd.read_csv(pd.StringIO('\n'.join(lines[daily_start:daily_end])))daily_df['date'] = pd.to_datetime(daily_df['date'])daily_df.plot(x='date', y='savings_pct', kind='line') **GitHub Actions (weekly stats):** on: schedule: - cron: '0 0 * * 1'jobs: stats: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: cargo install rtk - run: rtk gain --weekly --format json > stats/week-$(date +%Y-%W).json - run: git add stats/ && git commit -m "Weekly rtk stats" && git push Quota estimate -------------- [Section titled “Quota estimate”](https://www.rtk-ai.app/docs/analytics/gain/#quota-estimate) `--quota` estimates how many tokens RTK has saved relative to your monthly subscription budget, so you can see the cost impact of those savings. rtk gain --quota # uses 20x tier by defaultrtk gain --quota -t pro # Claude Pro plan budgetrtk gain --quota -t 5x # 5× usage plan budgetrtk gain --quota -t 20x # 20× usage plan budget The tiers (`pro`, `5x`, `20x`) correspond to Anthropic Claude API subscription levels, each with a different monthly token allocation. RTK uses those allocations as a denominator to express your savings as a percentage of your budget. Troubleshooting --------------- [Section titled “Troubleshooting”](https://www.rtk-ai.app/docs/analytics/gain/#troubleshooting) **No data showing:** ls -lh ~/.local/share/rtk/history.dbsqlite3 ~/.local/share/rtk/history.db "SELECT COUNT(*) FROM commands"git status # run any tracked command to generate data **Incorrect statistics:** Token estimation is a heuristic. For precise counts, use `tiktoken`: pip install tiktokengit status > output.txtpython -c "import tiktokenenc = tiktoken.get_encoding('cl100k_base')print(len(enc.encode(open('output.txt').read())), 'actual tokens')" --- # Discover and Session | RTK [Skip to content](https://www.rtk-ai.app/docs/analytics/discover/#_top) Discover and Session ==================== Discover and Session ==================== [Section titled “Discover and Session”](https://www.rtk-ai.app/docs/analytics/discover/#discover-and-session) rtk discover — find missed savings ---------------------------------- [Section titled “rtk discover — find missed savings”](https://www.rtk-ai.app/docs/analytics/discover/#rtk-discover--find-missed-savings) `rtk discover` analyzes your Claude Code command history to identify commands that ran without RTK filtering and calculates how many tokens you lost. rtk discover # analyze current project historyrtk discover --all # all projectsrtk discover --all --since 7 # last 7 days, all projects **Example output:** Missed savings analysis (last 7 days)────────────────────────────────────Command Count Est. lostcargo test 12 ~48,000 tokensgit log 8 ~12,000 tokenspnpm list 3 ~6,000 tokens────────────────────────────────────Total missed: 23 ~66,000 tokens Run `rtk init --global` to capture these automatically. If commands appear in the missed list after installing RTK, it usually means the hook isn’t active for that agent. See [Troubleshooting](https://www.rtk-ai.app/guide/resources/troubleshooting/) — “Agent not using RTK”. rtk session — adoption tracking ------------------------------- [Section titled “rtk session — adoption tracking”](https://www.rtk-ai.app/docs/analytics/discover/#rtk-session--adoption-tracking) `rtk session` shows RTK adoption across recent Claude Code sessions: how many shell commands ran through RTK vs. raw. rtk session **Example output:** Recent sessions (last 10)─────────────────────────────────────────────────────Session Total RTK Coverage2026-04-06 14:32 (45 cmds) 45 43 95.6%2026-04-05 09:14 (38 cmds) 38 38 100.0%2026-04-04 16:50 (52 cmds) 52 49 94.2%─────────────────────────────────────────────────────Average coverage: 96.6% Low coverage on a session usually means RTK was disabled (`RTK_DISABLED=1`) or the hook wasn’t active for a specific subagent. --- # Installation | RTK [Skip to content](https://www.rtk-ai.app/docs/getting-started/installation/#_top) Installation ============ Installation ============ [Section titled “Installation”](https://www.rtk-ai.app/docs/getting-started/installation/#installation) Name collision warning ---------------------- [Section titled “Name collision warning”](https://www.rtk-ai.app/docs/getting-started/installation/#name-collision-warning) Two unrelated projects share the name `rtk`. Make sure you install the right one: * **Rust Token Killer** (`rtk-ai/rtk`) — this project, a token-saving CLI proxy * **Rust Type Kit** (`reachingforthejack/rtk`) — a different tool for generating Rust types The easiest way to verify you have the correct one: run `rtk gain`. It should display token savings stats. If it returns “command not found”, you either have the wrong package or RTK is not installed. Check before installing ----------------------- [Section titled “Check before installing”](https://www.rtk-ai.app/docs/getting-started/installation/#check-before-installing) rtk --version # should print: rtk x.y.zrtk gain # should show token savings stats If both commands work, RTK is already installed. Skip to [Project initialization](https://www.rtk-ai.app/docs/getting-started/installation/#project-initialization) . Quick install (Linux and macOS) ------------------------------- [Section titled “Quick install (Linux and macOS)”](https://www.rtk-ai.app/docs/getting-started/installation/#quick-install-linux-and-macos) curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh Homebrew (macOS and Linux) -------------------------- [Section titled “Homebrew (macOS and Linux)”](https://www.rtk-ai.app/docs/getting-started/installation/#homebrew-macos-and-linux) brew install rtk-ai/tap/rtk Cargo ----- [Section titled “Cargo”](https://www.rtk-ai.app/docs/getting-started/installation/#cargo) cargo install --git https://github.com/rtk-ai/rtk rtk Pre-built binaries (Windows, Linux, macOS) ------------------------------------------ [Section titled “Pre-built binaries (Windows, Linux, macOS)”](https://www.rtk-ai.app/docs/getting-started/installation/#pre-built-binaries-windows-linux-macos) Download from [GitHub releases](https://github.com/rtk-ai/rtk/releases) : * macOS: `rtk-x86_64-apple-darwin.tar.gz` / `rtk-aarch64-apple-darwin.tar.gz` * Linux: `rtk-x86_64-unknown-linux-musl.tar.gz` / `rtk-aarch64-unknown-linux-gnu.tar.gz` * Windows: `rtk-x86_64-pc-windows-msvc.zip` **Windows users**: Extract the zip and place `rtk.exe` in a directory on your PATH. Run RTK from Command Prompt, PowerShell, or Windows Terminal — do not double-click the `.exe` (it prints usage and exits immediately). For full hook support, use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) instead. Verify installation ------------------- [Section titled “Verify installation”](https://www.rtk-ai.app/docs/getting-started/installation/#verify-installation) rtk --version # rtk x.y.zrtk gain # token savings dashboard If `rtk gain` fails but `rtk --version` succeeds, you installed Rust Type Kit by mistake. Uninstall it first: cargo uninstall rtk Then reinstall using one of the methods above. Project initialization ---------------------- [Section titled “Project initialization”](https://www.rtk-ai.app/docs/getting-started/installation/#project-initialization) Run once per project to enable the Claude Code hook: rtk init For a global install that patches `settings.json` automatically: rtk init --global Uninstall --------- [Section titled “Uninstall”](https://www.rtk-ai.app/docs/getting-started/installation/#uninstall) rtk init -g --uninstall # remove hook, RTK.md, and settings.json entrycargo uninstall rtk # remove binary (if installed via Cargo)brew uninstall rtk # remove binary (if installed via Homebrew) --- # Quick Start | RTK [Skip to content](https://www.rtk-ai.app/docs/getting-started/quick-start/#_top) Quick Start =========== Quick Start =========== [Section titled “Quick Start”](https://www.rtk-ai.app/docs/getting-started/quick-start/#quick-start) This guide walks you through your first RTK commands after installation. Prerequisites ------------- [Section titled “Prerequisites”](https://www.rtk-ai.app/docs/getting-started/quick-start/#prerequisites) RTK is installed and verified: rtk --version # rtk x.y.zrtk gain # shows token savings dashboard If not, see [Installation](https://www.rtk-ai.app/guide/installation/) . Step 1: Initialize for your AI assistant ---------------------------------------- [Section titled “Step 1: Initialize for your AI assistant”](https://www.rtk-ai.app/docs/getting-started/quick-start/#step-1-initialize-for-your-ai-assistant) # For Claude Code (global — applies to all projects)rtk init --global # For a single project onlycd /your/project && rtk init This installs the hook that automatically rewrites commands. Restart your AI assistant after this step. ### Preview without writing: `--dry-run` [Section titled “Preview without writing: --dry-run”](https://www.rtk-ai.app/docs/getting-started/quick-start/#preview-without-writing---dry-run) To see exactly what `init` would change before it touches anything, add `--dry-run`: rtk init --global --dry-run Every would-be file create/update/patch is printed with a `[dry-run] would ...` prefix, then a `[dry-run] Nothing written.` footer. Nothing on disk is modified, no settings.json is patched, and the telemetry consent prompt is skipped. Combine with `-v` to also print the full content RTK would write: rtk init --global --dry-run -v `--dry-run` works for every init flavour (`--agent cursor`, `--gemini`, `--codex`, `--copilot`, `--uninstall`, …). It cannot be combined with `--show`. Step 2: Use your tools normally ------------------------------- [Section titled “Step 2: Use your tools normally”](https://www.rtk-ai.app/docs/getting-started/quick-start/#step-2-use-your-tools-normally) Once the hook is installed, nothing changes in how you work. Your AI assistant runs commands as usual — the hook intercepts them transparently and rewrites them before execution. For example, when Claude Code runs `cargo test`, the hook rewrites it to `rtk cargo test` before it executes. The LLM receives filtered output with only the failures — not 500 lines of passing tests. You never see or type `rtk`. RTK covers all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See [What RTK Optimizes](https://www.rtk-ai.app/guide/resources/what-rtk-covers/) for the full list. Step 3: Check your savings -------------------------- [Section titled “Step 3: Check your savings”](https://www.rtk-ai.app/docs/getting-started/quick-start/#step-3-check-your-savings) After a few commands, see how much was saved: rtk gain Total commands : 12Input tokens : 45,230Output tokens : 4,890Saved : 40,340 (89.2%) Step 4: Unsupported commands ---------------------------- [Section titled “Step 4: Unsupported commands”](https://www.rtk-ai.app/docs/getting-started/quick-start/#step-4-unsupported-commands) Commands RTK doesn’t recognize run through passthrough — output is unchanged, usage is tracked: rtk proxy make install Next steps ---------- [Section titled “Next steps”](https://www.rtk-ai.app/docs/getting-started/quick-start/#next-steps) * [What RTK Optimizes](https://www.rtk-ai.app/guide/resources/what-rtk-covers/) — all supported commands and savings by ecosystem * [Supported agents](https://www.rtk-ai.app/guide/supported-agents/) — Claude Code, Cursor, Copilot, and more * [Configuration](https://www.rtk-ai.app/guide/configuration/) — customize RTK behavior --- # What RTK Optimizes | RTK [Skip to content](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#_top) What RTK Optimizes ================== What RTK Optimizes ================== [Section titled “What RTK Optimizes”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#what-rtk-optimizes) Once RTK is installed with a hook, these commands are automatically intercepted and filtered. You run them normally — the hook rewrites them transparently before execution. Typical savings: 60-99%. Git --- [Section titled “Git”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#git) | Command | Savings | What changes | | --- | --- | --- | | `git status` | 75-93% | Compact stat format, grouped by state | | `git log` | 80-92% | Hash + author + subject only | | `git diff` | 70% | Context reduced, headers stripped | | `git show` | 70% | Same as diff | | `git stash list` | 75% | Compact one-line per entry | GitHub CLI ---------- [Section titled “GitHub CLI”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#github-cli) | Command | Savings | What changes | | --- | --- | --- | | `gh pr view` | 87% | Removes ASCII art and verbose metadata | | `gh pr checks` | 79% | Status + name only, failures highlighted | | `gh run list` | 82% | Compact workflow run summary | | `gh issue view` | 80% | Body only, no decoration | Graphite (Stacked PRs) ---------------------- [Section titled “Graphite (Stacked PRs)”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#graphite-stacked-prs) | Command | Savings | What changes | | --- | --- | --- | | `gt log` | 75% | Stack summary only | | `gt status` | 70% | Current branch context | Cargo / Rust ------------ [Section titled “Cargo / Rust”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#cargo--rust) | Command | Savings | What changes | | --- | --- | --- | | `cargo test` | 90% | Failures only, passed tests suppressed | | `cargo nextest` | 90% | Same as test | | `cargo build` | 80% | Errors and warnings only | | `cargo check` | 80% | Errors and warnings only | | `cargo clippy` | 80% | Lint warnings grouped by file | JavaScript / TypeScript ----------------------- [Section titled “JavaScript / TypeScript”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#javascript--typescript) | Command | Savings | What changes | | --- | --- | --- | | `jest` | 94-99% | Failures only | | `vitest` | 94-99% | Failures only | | `tsc` | 75% | Type errors grouped by file | | `eslint` | 84% | Violations grouped by rule | | `pnpm list` | 70-90% | Compact dependency tree | | `pnpm outdated` | 70% | Package + current + latest only | | `next build` | 80% | Route summary + errors only | | `prisma migrate` | 75% | Migration status only | | `playwright test` | 90% | Failures + trace links only | Python ------ [Section titled “Python”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#python) | Command | Savings | What changes | | --- | --- | --- | | `pytest` | 80-90% | Failures only | | `ruff check` | 75% | Violations grouped by file | | `mypy` | 75% | Type errors grouped by file | | `pip install` | 70% | Installed packages only, progress stripped | Go -- [Section titled “Go”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#go) | Command | Savings | What changes | | --- | --- | --- | | `go test` | 80-90% | Failures only | | `golangci-lint run` | 75% | Violations grouped by file | | `go build` | 75% | Errors only | Ruby ---- [Section titled “Ruby”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#ruby) | Command | Savings | What changes | | --- | --- | --- | | `rspec` | 80-90% | Failures only | | `rubocop` | 75% | Offenses grouped by file | | `rake` | 70% | Task output, build errors highlighted | .NET ---- [Section titled “.NET”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#net) | Command | Savings | What changes | | --- | --- | --- | | `dotnet build` | 80% | Errors and warnings only | | `dotnet test` | 85-90% | Failures only | | `dotnet format` | 75% | Changed files only | Docker / Kubernetes ------------------- [Section titled “Docker / Kubernetes”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#docker--kubernetes) | Command | Savings | What changes | | --- | --- | --- | | `docker ps` | 65% | Essential columns (name, image, status, port) | | `docker images` | 60% | Name + tag + size only | | `docker logs` | 70% | Deduplicated, last N lines | | `docker compose up` | 75% | Service status, errors highlighted | | `kubectl get pods` | 65% | Name + status + restarts only | | `kubectl logs` | 70% | Deduplicated entries | Files and Search ---------------- [Section titled “Files and Search”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#files-and-search) | Command | Savings | What changes | | --- | --- | --- | | `ls` | 80% | Tree format with file counts | | `find` | 75% | Tree format | | `grep` | 70% | Truncated lines, grouped by file | | `diff` | 65% | Context reduced | | `wc` | 60% | Compact counts | | `cat` / `head` / `tail ` | 60-80% | Smart file reading via `rtk read` | | `rtk smart ` | 85% | 2-line heuristic code summary (signatures only) | Cloud and Data -------------- [Section titled “Cloud and Data”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#cloud-and-data) | Command | Savings | What changes | | --- | --- | --- | | `aws` | 70% | JSON condensed, relevant fields only | | `psql` | 65% | Query results without decoration | | `curl` | 60% | Response body only, headers stripped | Global flags ------------ [Section titled “Global flags”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#global-flags) These flags apply to all RTK commands and can push savings even higher: | Flag | Description | | --- | --- | | `--ultra-compact` | ASCII icons, inline format — extra token reduction on top of normal filtering | | `-v` / `--verbose` | Show filtering details on stderr (`-v`, `-vv`, `-vvv` for increasing detail) | # Ultra-compact: even smaller outputrtk git log --ultra-compact # Debug: see what RTK is doingrtk git status -vvv Commands that are not rewritten ------------------------------- [Section titled “Commands that are not rewritten”](https://www.rtk-ai.app/docs/resources/what-rtk-covers/#commands-that-are-not-rewritten) If a command isn’t in the list above, RTK runs it through passthrough — the output reaches the LLM unchanged. You can explicitly track unsupported commands: rtk proxy make install # runs make install, tracks usage, no filtering To check which commands were missed opportunities: `rtk discover`. --- # Configuration | RTK [Skip to content](https://www.rtk-ai.app/docs/getting-started/configuration/#_top) Configuration ============= Configuration ============= [Section titled “Configuration”](https://www.rtk-ai.app/docs/getting-started/configuration/#configuration) Config file location -------------------- [Section titled “Config file location”](https://www.rtk-ai.app/docs/getting-started/configuration/#config-file-location) | Platform | Path | | --- | --- | | Linux | `~/.config/rtk/config.toml` | | macOS | `~/Library/Application Support/rtk/config.toml` | rtk config # show current configurationrtk config --create # create config file with defaults Full config structure --------------------- [Section titled “Full config structure”](https://www.rtk-ai.app/docs/getting-started/configuration/#full-config-structure) [tracking]enabled = true # enable/disable token trackinghistory_days = 90 # retention in days (auto-cleanup)database_path = "/custom/path/history.db" # optional override [display]colors = true # colored outputemoji = true # use emojis in outputmax_width = 120 # maximum output width [filters]# These apply to file-reading commands (ls, find, grep, cat/rtk read).# Paths matching these patterns are excluded from output, keeping noise low.ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor"]ignore_files = ["*.lock", "*.min.js", "*.min.css"] [tee]enabled = true # save raw output on failuremode = "failures" # "failures" (default), "always", "never"max_files = 20 # rotation: keep last N files# directory = "/custom/tee/path" # optional override [telemetry]enabled = true # anonymous daily ping — see Telemetry & Privacy for full details [hooks]exclude_commands = [] # commands to never auto-rewrite For full details on what is collected, opt-out options, and GDPR rights, see [Telemetry & Privacy](https://www.rtk-ai.app/guide/resources/telemetry/) . Environment variables --------------------- [Section titled “Environment variables”](https://www.rtk-ai.app/docs/getting-started/configuration/#environment-variables) | Variable | Description | | --- | --- | | `RTK_DISABLED=1` | Disable RTK for a single command (`RTK_DISABLED=1 git status`) | | `RTK_TEE_DIR` | Override the tee directory | | `RTK_TELEMETRY_DISABLED=1` | Disable telemetry | | `RTK_HOOK_AUDIT=1` | Enable hook audit logging | | `SKIP_ENV_VALIDATION=1` | Skip env validation (useful with Next.js) | Tee system ---------- [Section titled “Tee system”](https://www.rtk-ai.app/docs/getting-started/configuration/#tee-system) When a command fails, RTK saves the full raw output to a local file and prints the path: FAILED: 2/15 tests[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log] Your AI assistant can then read the file if it needs more detail, without re-running the command. | Setting | Default | Description | | --- | --- | --- | | `tee.enabled` | `true` | Enable/disable | | `tee.mode` | `"failures"` | `"failures"`, `"always"`, `"never"` | | `tee.max_files` | `20` | Rotation: keep last N files | | Min size | 500 bytes | Outputs shorter than this are not saved | | Max file size | 1 MB | Truncated above this | Excluding commands from auto-rewrite ------------------------------------ [Section titled “Excluding commands from auto-rewrite”](https://www.rtk-ai.app/docs/getting-started/configuration/#excluding-commands-from-auto-rewrite) Prevent specific commands from being rewritten by the hook: [hooks]exclude_commands = ["git rebase", "git cherry-pick", "docker exec"] Patterns match against the full command after stripping env prefixes (`sudo`, `VAR=val`), so `"psql"` excludes both `psql -h localhost` and `PGPASSWORD=x psql -h localhost`. Subcommand patterns work too: `"git push"` excludes `git push origin main` but not `git status`. Patterns starting with `^` are treated as regex: [hooks]exclude_commands = ["^curl", "^wget", "git rebase"] Invalid regex patterns fall back to prefix matching. Or for a single invocation: RTK_DISABLED=1 git rebase main Telemetry --------- [Section titled “Telemetry”](https://www.rtk-ai.app/docs/getting-started/configuration/#telemetry) RTK sends one anonymous ping per day (23h interval). No personal data, no file paths, no command content. Data sent: device hash, version, OS, architecture, command count/24h, top commands, savings %. To opt out: # Via environment variableexport RTK_TELEMETRY_DISABLED=1 # Via config.toml[telemetry]enabled = false Per-project filters ------------------- [Section titled “Per-project filters”](https://www.rtk-ai.app/docs/getting-started/configuration/#per-project-filters) Create `.rtk/filters.toml` in your project root to add custom filters or override built-ins. See [`src/filters/README.md`](https://github.com/rtk-ai/rtk/blob/master/src/filters/README.md) for the full TOML DSL reference. --- # Supported Agents | RTK [Skip to content](https://www.rtk-ai.app/docs/getting-started/supported-agents/#_top) Supported Agents ================ Supported Agents ================ [Section titled “Supported Agents”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#supported-agents) RTK supports all major AI coding agents across 3 integration tiers. Mistral Vibe support is planned. How it works ------------ [Section titled “How it works”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#how-it-works) Each agent integration intercepts CLI commands before execution and rewrites them to their RTK equivalent. The agent runs `rtk cargo test` instead of `cargo test`, sees filtered output, and uses up to 90% fewer tokens — without any change to your workflow. All rewrite logic lives in the RTK binary (`rtk rewrite`). Agent hooks are thin delegates that parse the agent-specific JSON format and call `rtk rewrite` for the actual decision. Agent runs "cargo test" -> Hook intercepts (PreToolUse / plugin event) -> Calls rtk rewrite "cargo test" -> Returns "rtk cargo test" -> Agent executes filtered command -> LLM sees 90% fewer tokens Supported agents ---------------- [Section titled “Supported agents”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#supported-agents-1) | Agent | Integration tier | Can rewrite transparently? | | --- | --- | --- | | Claude Code | Shell hook (`PreToolUse`) | Yes | | VS Code Copilot Chat | Shell hook (`PreToolUse`) | Yes | | GitHub Copilot CLI | Shell hook (`preToolUse` `modifiedArgs`) | Yes | | Cursor | Shell hook (`preToolUse`) | Yes | | Gemini CLI | Rust binary (`BeforeTool`) | Yes | | OpenCode | TypeScript plugin (`tool.execute.before`) | Yes | | OpenClaw | TypeScript plugin (`before_tool_call`) | Yes | | Pi | TypeScript extension (`tool_call` event) | Yes | | Hermes | Python plugin (`terminal` command mutation) | Yes | | Cline / Roo Code | Rules file (prompt-level) | N/A | | Windsurf | Rules file (prompt-level) | N/A | | Codex CLI | AGENTS.md instructions | N/A | | Kilo Code | Rules file (prompt-level) | N/A | | Google Antigravity | Rules file (prompt-level) | N/A | | Mistral Vibe | Planned ([#800](https://github.com/rtk-ai/rtk/issues/800)
) | Pending upstream | Installation by agent --------------------- [Section titled “Installation by agent”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#installation-by-agent) ### Claude Code [Section titled “Claude Code”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#claude-code) rtk init --global # installs hook + patches settings.json Restart Claude Code. Verify: rtk init --show # shows hook status ### Cursor [Section titled “Cursor”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#cursor) rtk init --global --agent cursor Restart Cursor. The hook uses `preToolUse` with Cursor’s `updated_input` format. ### GitHub Copilot (VS Code Chat + CLI) [Section titled “GitHub Copilot (VS Code Chat + CLI)”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#github-copilot-vs-code-chat--cli) rtk init --copilot # project-scoped (.github/hooks/)rtk init --global --copilot # user-scoped (~/.copilot/hooks/, respects $COPILOT_HOME) Project-scoped writes `.github/hooks/rtk-rewrite.json` (both hosts get transparent rewrite — VS Code Chat via `updatedInput`, Copilot CLI via `modifiedArgs`) plus the RTK block in `.github/copilot-instructions.md`. User-scoped writes the same hook config to `~/.copilot/hooks/rtk-rewrite.json` and the RTK block to `~/.copilot/copilot-instructions.md` (both respect `$COPILOT_HOME` if set). Uninstall: rtk init --uninstall --copilotrtk init --uninstall --global --copilot Removes only RTK’s hook file (and, for project, the RTK block in `copilot-instructions.md`). Other files in `.github/hooks/` or `~/.copilot/hooks/` and your own instruction content are untouched. ### Gemini CLI [Section titled “Gemini CLI”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#gemini-cli) rtk init --global --gemini ### OpenCode [Section titled “OpenCode”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#opencode) rtk init --global --opencode Creates `~/.config/opencode/plugins/rtk.ts`. Uses the `tool.execute.before` hook. ### Pi [Section titled “Pi”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#pi) # Project-local (default)rtk init --agent pi # Global — all projectsrtk init --agent pi --global Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global). Pi auto-discovers extensions from both paths on startup. Uninstall: rtk init --uninstall --agent pirtk init --uninstall --agent pi --global Removes only the installed Pi extension file. ### OpenClaw [Section titled “OpenClaw”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#openclaw) openclaw plugins install ./openclaw Plugin in the `openclaw/` directory. Uses the `before_tool_call` hook, delegates to `rtk rewrite`. ### Hermes [Section titled “Hermes”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#hermes) rtk init --agent hermes Creates `~/.hermes/plugins/rtk-rewrite/` and enables it through `plugins.enabled` in the Hermes config. Hermes loads Python plugins, so the plugin entrypoint is Python, but it is only a thin adapter. It mutates the Hermes `terminal` tool `command` before execution and delegates all rewrite decisions to Rust through `rtk rewrite`. The repository source and tests for that adapter live in `hooks/hermes/`; only installed runtime files use the `~/.hermes/plugins/rtk-rewrite/` path. The plugin fails open. If `rtk` is missing at load time, the hook is not registered. If `rtk rewrite` errors, the tool is not `terminal`, the payload has no string `command`, or the plugin raises an exception, Hermes runs the original command unchanged. The same `rtk rewrite` limitations apply: already-prefixed `rtk` commands, compound shell commands, heredocs, and commands without filters are not rewritten. ### Cline / Roo Code [Section titled “Cline / Roo Code”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#cline--roo-code) rtk init --agent cline # creates .clinerules in current project Cline reads `.clinerules` as custom instructions. RTK adds guidance telling Cline to prefer `rtk ` over raw commands. ### Windsurf [Section titled “Windsurf”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#windsurf) rtk init --global --agent windsurf # creates .windsurfrules in current project ### Codex CLI [Section titled “Codex CLI”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#codex-cli) rtk init --codex # project-scoped (AGENTS.md)rtk init --global --codex # user-global (~/.codex/AGENTS.md) ### Kilo Code [Section titled “Kilo Code”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#kilo-code) rtk init --agent kilocode # creates .kilocode/rules/rtk-rules.md in current project Kilo Code reads `.kilocode/rules/` as custom instructions. RTK adds guidance telling Kilo Code to prefer `rtk ` over raw commands. ### Google Antigravity [Section titled “Google Antigravity”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#google-antigravity) rtk init --agent antigravity # creates .agents/rules/antigravity-rtk-rules.md in current project Antigravity reads `.agents/rules/` as custom instructions. RTK adds guidance telling Antigravity to prefer `rtk ` over raw commands. ### Mistral Vibe (planned) [Section titled “Mistral Vibe (planned)”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#mistral-vibe-planned) Support is blocked on upstream `BeforeToolCallback` ([mistral-vibe#531](https://github.com/mistralai/mistral-vibe/issues/531) ). Tracked in [#800](https://github.com/rtk-ai/rtk/issues/800) . Integration tiers explained --------------------------- [Section titled “Integration tiers explained”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#integration-tiers-explained) | Tier | Mechanism | How rewrites work | | --- | --- | --- | | **Full hook** | Shell script or Rust binary, intercepts via agent API | Transparent — agent never sees the raw command | | **Plugin** | TypeScript, JavaScript, or Python in agent’s plugin system | Transparent, in-place mutation when the agent allows it | | **Rules file** | Prompt-level instructions | Guidance only — agent is told to prefer `rtk ` | Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it. Plugin integrations (OpenCode, Pi) use in-place mutation via the agent’s TypeScript extension API. Windows support --------------- [Section titled “Windows support”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#windows-support) The shell hook (`rtk-rewrite.sh`) requires a Unix shell. On native Windows: * `rtk init -g` automatically falls back to **CLAUDE.md injection mode** (prompt-level instructions) * Filters work normally (`rtk cargo test`, `rtk git status`) * Auto-rewrite does not work — the AI assistant is instructed to use RTK but commands are not intercepted For full hook support on Windows, use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) . Inside WSL, all agents with shell hook integration (Claude Code, Cursor, Gemini) work identically to Linux. Graceful degradation -------------------- [Section titled “Graceful degradation”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#graceful-degradation) Hooks never block command execution. If RTK is missing, the hook exits cleanly and the raw command runs unchanged: * RTK binary not found: warning to stderr, exit 0 * Invalid JSON input: pass through unchanged * RTK version too old: warning to stderr, exit 0 * Filter logic error: fallback to raw command output Override: disable RTK for one command ------------------------------------- [Section titled “Override: disable RTK for one command”](https://www.rtk-ai.app/docs/getting-started/supported-agents/#override-disable-rtk-for-one-command) RTK_DISABLED=1 git status # runs raw git status, no rewrite Or exclude commands permanently in `~/.config/rtk/config.toml`: [hooks]exclude_commands = ["git rebase", "git cherry-pick"] --- # Troubleshooting | RTK [Skip to content](https://www.rtk-ai.app/docs/resources/troubleshooting/#_top) Troubleshooting =============== Troubleshooting =============== [Section titled “Troubleshooting”](https://www.rtk-ai.app/docs/resources/troubleshooting/#troubleshooting) `rtk gain` says “not a rtk command” ----------------------------------- [Section titled “rtk gain says “not a rtk command””](https://www.rtk-ai.app/docs/resources/troubleshooting/#rtk-gain-says-not-a-rtk-command) **Symptom:** $ rtk gainrtk: 'gain' is not a rtk command. See 'rtk --help'. **Cause:** You installed **Rust Type Kit** (`reachingforthejack/rtk`) instead of **Rust Token Killer** (`rtk-ai/rtk`). They share the same binary name. **Fix:** cargo uninstall rtkcurl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | shrtk gain # should now show token savings stats How to tell which rtk you have ------------------------------ [Section titled “How to tell which rtk you have”](https://www.rtk-ai.app/docs/resources/troubleshooting/#how-to-tell-which-rtk-you-have) | If `rtk gain`… | You have | | --- | --- | | Shows token savings dashboard | Rust Token Killer ✅ | | Returns “not a rtk command” | Rust Type Kit ❌ | AI assistant not using RTK -------------------------- [Section titled “AI assistant not using RTK”](https://www.rtk-ai.app/docs/resources/troubleshooting/#ai-assistant-not-using-rtk) **Symptom:** Claude Code (or another agent) runs `cargo test` instead of `rtk cargo test`. **Checklist:** 1. Verify RTK is installed: rtk --versionrtk gain 2. Initialize the hook: rtk init --global # Claude Codertk init --global --cursor # Cursorrtk init --global --opencode # OpenCode 3. Restart your AI assistant. 4. Verify hook status: rtk init --show 5. Check `settings.json` has the hook registered (Claude Code): cat ~/.claude/settings.json | grep rtk RTK not found after `cargo install` ----------------------------------- [Section titled “RTK not found after cargo install”](https://www.rtk-ai.app/docs/resources/troubleshooting/#rtk-not-found-after-cargo-install) **Symptom:** $ rtk --versionzsh: command not found: rtk **Cause:** `~/.cargo/bin` is not in your PATH. **Fix:** For bash (`~/.bashrc`) or zsh (`~/.zshrc`): export PATH="$HOME/.cargo/bin:$PATH" For fish (`~/.config/fish/config.fish`): set -gx PATH $HOME/.cargo/bin $PATH Then reload: source ~/.zshrc # or ~/.bashrcrtk --version RTK on Windows -------------- [Section titled “RTK on Windows”](https://www.rtk-ai.app/docs/resources/troubleshooting/#rtk-on-windows) ### Double-clicking rtk.exe does nothing [Section titled “Double-clicking rtk.exe does nothing”](https://www.rtk-ai.app/docs/resources/troubleshooting/#double-clicking-rtkexe-does-nothing) **Symptom:** You double-click `rtk.exe`, a terminal flashes and closes instantly. **Cause:** RTK is a command-line tool. With no arguments, it prints usage and exits. The console window opens and closes before you can read anything. **Fix:** Open a terminal first, then run RTK from there: * Press `Win+R`, type `cmd`, press Enter * Or open PowerShell or Windows Terminal * Then run: `rtk --version` ### Hook not working (no auto-rewrite) [Section titled “Hook not working (no auto-rewrite)”](https://www.rtk-ai.app/docs/resources/troubleshooting/#hook-not-working-no-auto-rewrite) **Symptom:** `rtk init -g` shows “Falling back to —claude-md mode” on Windows. **Cause:** The auto-rewrite hook (`rtk-rewrite.sh`) requires a Unix shell. Native Windows doesn’t have one. **Fix:** Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for full hook support: # Inside WSLcurl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | shrtk init -g # full hook mode works in WSL On native Windows, RTK falls back to CLAUDE.md injection. Your AI assistant gets RTK instructions but won’t auto-rewrite commands. It can still use RTK manually: `rtk cargo test`, `rtk git status`, etc. ### Node.js tools not found [Section titled “Node.js tools not found”](https://www.rtk-ai.app/docs/resources/troubleshooting/#nodejs-tools-not-found) **Symptom:** rtk vitest --runError: program not found **Cause:** On Windows, Node.js tools are installed as `.CMD`/`.BAT` wrappers. Older RTK versions couldn’t find them. **Fix:** Update to RTK v0.23.1+: cargo install --git https://github.com/rtk-ai/rtkrtk --version # should be 0.23.1+ Compilation error during installation ------------------------------------- [Section titled “Compilation error during installation”](https://www.rtk-ai.app/docs/resources/troubleshooting/#compilation-error-during-installation) rustup update stablerustup default stablecargo cleancargo build --releasecargo install --path . --force Minimum required Rust version: 1.70+. OpenCode not using RTK ---------------------- [Section titled “OpenCode not using RTK”](https://www.rtk-ai.app/docs/resources/troubleshooting/#opencode-not-using-rtk) rtk init --global --opencode# restart OpenCodertk init --show # should show "OpenCode: plugin installed" `cargo install rtk` installs the wrong package ---------------------------------------------- [Section titled “cargo install rtk installs the wrong package”](https://www.rtk-ai.app/docs/resources/troubleshooting/#cargo-install-rtk-installs-the-wrong-package) If Rust Type Kit is published to crates.io under the name `rtk`, `cargo install rtk` may install the wrong one. Always use the explicit URL: cargo install --git https://github.com/rtk-ai/rtk Run the diagnostic script ------------------------- [Section titled “Run the diagnostic script”](https://www.rtk-ai.app/docs/resources/troubleshooting/#run-the-diagnostic-script) From the RTK repository root: bash scripts/check-installation.sh Checks: * RTK installed and in PATH * Correct version (Token Killer, not Type Kit) * Available features * Claude Code integration * Hook status Still stuck? ------------ [Section titled “Still stuck?”](https://www.rtk-ai.app/docs/resources/troubleshooting/#still-stuck) Open an issue: [https://github.com/rtk-ai/rtk/issues](https://github.com/rtk-ai/rtk/issues) --- # Telemetry & Privacy | RTK [Skip to content](https://www.rtk-ai.app/docs/resources/telemetry/#_top) Telemetry & Privacy =================== Telemetry & Privacy =================== [Section titled “Telemetry & Privacy”](https://www.rtk-ai.app/docs/resources/telemetry/#telemetry--privacy) RTK collects anonymous, aggregate usage metrics once per day to help improve the product. Telemetry is **disabled by default** and requires explicit consent during `rtk init` or `rtk telemetry enable`. Data Collector -------------- [Section titled “Data Collector”](https://www.rtk-ai.app/docs/resources/telemetry/#data-collector) **Entity**: `RTK AI Labs` **Contact**: [contact@rtk-ai.app](mailto:contact@rtk-ai.app) Why we collect telemetry ------------------------ [Section titled “Why we collect telemetry”](https://www.rtk-ai.app/docs/resources/telemetry/#why-we-collect-telemetry) Without telemetry, we have no visibility into: * Which commands are used most and need the best filters * Which filters are underperforming and need improvement * Which ecosystems to prioritize for new filter development * How much value RTK delivers to users (token savings in $ terms) * Whether users stay engaged over time or churn after trying RTK This data directly drives our roadmap. For example, if telemetry shows that 40% of users run Python commands but only 10% of our filters cover Python, we know where to invest next. How it works ------------ [Section titled “How it works”](https://www.rtk-ai.app/docs/resources/telemetry/#how-it-works) 1. **Once per day** (23-hour interval), RTK sends a single HTTPS POST to our telemetry endpoint 2. The ping runs in a **background thread** and never blocks the CLI (2-second timeout) 3. A marker file prevents duplicate pings within the interval 4. If the server is unreachable, the ping is silently dropped — no retries, no queue What is collected ----------------- [Section titled “What is collected”](https://www.rtk-ai.app/docs/resources/telemetry/#what-is-collected) ### Identity (anonymous) [Section titled “Identity (anonymous)”](https://www.rtk-ai.app/docs/resources/telemetry/#identity-anonymous) | Field | Example | Purpose | | --- | --- | --- | | `device_hash` | `a3f8c9...` (64 hex chars) | Count unique installations. SHA-256 of a per-device random salt stored locally (`~/.local/share/rtk/.device_salt`). Not reversible. No hostname or username included. | ### Environment [Section titled “Environment”](https://www.rtk-ai.app/docs/resources/telemetry/#environment) | Field | Example | Purpose | | --- | --- | --- | | `version` | `0.34.1` | Track adoption of new versions | | `os` | `macos` | Know which platforms to support and test | | `arch` | `aarch64` | Prioritize ARM vs x86 builds | | `install_method` | `homebrew` | Understand distribution channels (homebrew/cargo/script/nix) | ### Usage volume [Section titled “Usage volume”](https://www.rtk-ai.app/docs/resources/telemetry/#usage-volume) | Field | Example | Purpose | | --- | --- | --- | | `commands_24h` | `142` | Daily activity level | | `commands_total` | `32888` | Lifetime usage — segment light vs heavy users | | `top_commands` | `["git", "cargo", "ls"]` | Most popular tools (names only, max 5) | | `tokens_saved_24h` | `450000` | Daily value delivered | | `tokens_saved_total` | `96500000` | Lifetime value delivered | | `savings_pct` | `72.5` | Overall effectiveness | ### Quality (filter improvement) [Section titled “Quality (filter improvement)”](https://www.rtk-ai.app/docs/resources/telemetry/#quality-filter-improvement) | Field | Example | Purpose | | --- | --- | --- | | `passthrough_top` | `["git:15", "npm:8"]` | Top 5 commands with 0% savings — these need filters | | `parse_failures_24h` | `3` | Filter fragility — high count means filters are breaking | | `low_savings_commands` | `["rtk docker ps:25%"]` | Commands averaging <30% savings — filters to improve | | `avg_savings_per_command` | `68.5` | Unweighted average (vs global which is volume-biased) | ### Ecosystem distribution [Section titled “Ecosystem distribution”](https://www.rtk-ai.app/docs/resources/telemetry/#ecosystem-distribution) | Field | Example | Purpose | | --- | --- | --- | | `ecosystem_mix` | `{"git": 45, "cargo": 20, "js": 15}` | Category percentages — where to invest filter development | ### Retention (engagement) [Section titled “Retention (engagement)”](https://www.rtk-ai.app/docs/resources/telemetry/#retention-engagement) | Field | Example | Purpose | | --- | --- | --- | | `first_seen_days` | `45` | Installation age in days | | `active_days_30d` | `22` | Days with at least 1 command in last 30 days — measures stickiness | ### Economics [Section titled “Economics”](https://www.rtk-ai.app/docs/resources/telemetry/#economics) | Field | Example | Purpose | | --- | --- | --- | | `tokens_saved_30d` | `12000000` | 30-day token savings for trend analysis | | `estimated_savings_usd_30d` | `36.0` | Estimated dollar value saved (at ~$3/Mtok input pricing, Claude Sonnet) | ### Adoption [Section titled “Adoption”](https://www.rtk-ai.app/docs/resources/telemetry/#adoption) | Field | Example | Purpose | | --- | --- | --- | | `hook_type` | `claude` | Which AI agent hook is installed (claude/gemini/codex/cursor/none) | | `custom_toml_filters` | `3` | Number of user-created TOML filter files — DSL adoption | ### Configuration (user maturity) [Section titled “Configuration (user maturity)”](https://www.rtk-ai.app/docs/resources/telemetry/#configuration-user-maturity) | Field | Example | Purpose | | --- | --- | --- | | `has_config_toml` | `true` | Whether user has customized RTK config | | `exclude_commands_count` | `2` | Commands excluded from rewriting — high count may indicate frustration | | `projects_count` | `5` | Distinct project paths — multi-project = power user | ### Feature adoption [Section titled “Feature adoption”](https://www.rtk-ai.app/docs/resources/telemetry/#feature-adoption) | Field | Example | Purpose | | --- | --- | --- | | `meta_usage` | `{"gain": 5, "discover": 2}` | Which RTK features are actually used | What is NOT collected --------------------- [Section titled “What is NOT collected”](https://www.rtk-ai.app/docs/resources/telemetry/#what-is-not-collected) * Source code or file contents * Full command lines or arguments (only tool names like “git”, “cargo”) * File paths or directory structures * Secrets, API keys, or environment variable values * Repository names or URLs * Personally identifiable information * IP addresses (not stored in telemetry pings; stored temporarily in erasure audit log for accountability, anonymized after 6 months) Consent ------- [Section titled “Consent”](https://www.rtk-ai.app/docs/resources/telemetry/#consent) Telemetry requires explicit opt-in consent (GDPR Art. 6, 7). Consent is requested during `rtk init` or via `rtk telemetry enable`. Without consent, no data is sent. rtk telemetry status # Check current consent statertk telemetry enable # Give consent (interactive prompt)rtk telemetry disable # Withdraw consentrtk telemetry forget # Withdraw consent + delete local data + request server erasure Environment variable override (blocks telemetry regardless of consent): export RTK_TELEMETRY_DISABLED=1 Retention Policy ---------------- [Section titled “Retention Policy”](https://www.rtk-ai.app/docs/resources/telemetry/#retention-policy) * **Server-side**: telemetry records are retained for a maximum of **12 months**, then automatically purged. * **Server-side (erasure log)**: IP addresses in the erasure audit log are **anonymized after 6 months** (GDPR — IP is personal data). * **Client-side**: the local SQLite database (`~/.local/share/rtk/history.db`) retains data for **90 days** by default (configurable via `tracking.history_days` in `config.toml`). Deleted entirely by `rtk telemetry forget`. Your Rights (GDPR) ------------------ [Section titled “Your Rights (GDPR)”](https://www.rtk-ai.app/docs/resources/telemetry/#your-rights-gdpr) Under the EU General Data Protection Regulation, you have the right to: * **Access** your data: `rtk telemetry status` shows your device hash; the telemetry payload is fully documented above. * **Rectification**: since data is anonymous and aggregate, rectification is not applicable. * **Erasure** (Art. 17): run `rtk telemetry forget` to delete local data and send an erasure request to the server. Alternatively, email [contact@rtk-ai.app](mailto:contact@rtk-ai.app) with your device hash. * **Restriction of processing**: `rtk telemetry disable` stops all data collection immediately. * **Portability**: the local SQLite database at `~/.local/share/rtk/history.db` contains all locally stored data. * **Objection**: `rtk telemetry disable` or `export RTK_TELEMETRY_DISABLED=1`. Erasure Procedure ----------------- [Section titled “Erasure Procedure”](https://www.rtk-ai.app/docs/resources/telemetry/#erasure-procedure) 1. Run `rtk telemetry forget` — this disables telemetry, deletes your device salt, ping marker, and local tracking database (`history.db`), then sends an erasure request to the server. 2. If the server is unreachable, the CLI prints your full device hash and fallback instructions to email [contact@rtk-ai.app](mailto:contact@rtk-ai.app) for manual erasure. 3. You can also email [contact@rtk-ai.app](mailto:contact@rtk-ai.app) directly to request manual erasure. Data Handling ------------- [Section titled “Data Handling”](https://www.rtk-ai.app/docs/resources/telemetry/#data-handling) * All communications use HTTPS (TLS) * Data is used exclusively for RTK product improvement * No data is sold or shared with third parties * Aggregate statistics may be published (e.g. “70% of RTK users are on macOS”) ---