wehub/rtk-ai--rtk
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:01:57 +08:00
commit 9dda3e2451
399 changed files with 118131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/analytics/discover.md
+58
View File
@@ -0,0 +1,58 @@
---
title: Discover and Session
description: Find missed savings opportunities with rtk discover, and track RTK adoption with rtk session
sidebar:
order: 2
---
# Discover and Session
## 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.
```bash
rtk discover # analyze current project history
rtk discover --all # all projects
rtk discover --all --since 7 # last 7 days, all projects
```
**Example output:**
```
Missed savings analysis (last 7 days)
────────────────────────────────────
Command Count Est. lost
cargo test 12 ~48,000 tokens
git log 8 ~12,000 tokens
pnpm list 3 ~6,000 tokens
────────────────────────────────────
Total missed: 23 ~66,000 tokens
Run `rtk init --global` to capture these automatically.
```
If commands appear in the missed list after installing RTK, it usually means the hook isn't active for that agent. See [Troubleshooting](../resources/troubleshooting.md) — "Agent not using RTK".
## rtk session — adoption tracking
`rtk session` shows RTK adoption across recent Claude Code sessions: how many shell commands ran through RTK vs. raw.
```bash
rtk session
```
**Example output:**
```
Recent sessions (last 10)
─────────────────────────────────────────────────────
Session Total RTK Coverage
2026-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.
docs/guide/analytics/gain.md
+215
View File
@@ -0,0 +1,215 @@
---
title: Token Savings Analytics
description: Measure and analyze your RTK token savings with rtk gain
sidebar:
order: 1
---
# Token Savings Analytics
`rtk gain` shows how many tokens RTK has saved across all your commands, with daily, weekly, and monthly breakdowns.
## Quick reference
```bash
# Default summary
rtk gain
# Temporal breakdowns
rtk gain --daily # all days since tracking started
rtk gain --weekly # aggregated by week
rtk gain --monthly # aggregated by month
rtk gain --all # all breakdowns at once
# Classic flags
rtk gain --graph # ASCII graph, last 30 days
rtk gain --history # last 10 commands
rtk gain --quota # monthly quota savings estimate (default tier: 20x)
rtk gain --quota -t pro # use pro tier token budget for estimate
# Export
rtk gain --all --format json > savings.json
rtk gain --all --format csv > savings.csv
```
## Daily breakdown
```bash
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
```bash
rtk gain --weekly
rtk gain --monthly
```
Same columns as daily, aggregated by Sunday-Saturday week or calendar month.
## 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:**
```json
{
"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
| 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
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 - Output
Savings % = (Saved / Input) × 100
```
## 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
```bash
# Inspect raw data
sqlite3 ~/.local/share/rtk/history.db \
"SELECT timestamp, rtk_cmd, saved_tokens FROM commands
ORDER BY timestamp DESC LIMIT 10"
# Backup
cp ~/.local/share/rtk/history.db ~/backups/rtk-history-$(date +%Y%m%d).db
# Reset
rm ~/.local/share/rtk/history.db # recreated on next command
```
## Analysis workflows
```bash
# Weekly progress: generate a CSV report every Monday
rtk gain --weekly --format csv > reports/week-$(date +%Y-%W).csv
# Monthly budget review
rtk gain --monthly --format json | jq '.monthly[] |
{month, saved_tokens, quota_pct: (.saved_tokens / 6000000 * 100)}'
# Cron: daily JSON snapshot for a dashboard
0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json
```
**Python/pandas:**
```python
import pandas as pd
import 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') + 2
daily_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):**
```yaml
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
`--quota` estimates how many tokens RTK has saved relative to your monthly subscription budget, so you can see the cost impact of those savings.
```bash
rtk gain --quota # uses 20x tier by default
rtk gain --quota -t pro # Claude Pro plan budget
rtk gain --quota -t 5x # 5× usage plan budget
rtk 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.
:::tip[Find missed savings]
`rtk gain` shows what RTK saved. To find commands that ran *without* RTK and calculate what you lost, see [rtk discover](./discover.md).
:::
## Troubleshooting
**No data showing:**
```bash
ls -lh ~/.local/share/rtk/history.db
sqlite3 ~/.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`:
```bash
pip install tiktoken
git status > output.txt
python -c "
import tiktoken
enc = tiktoken.get_encoding('cl100k_base')
print(len(enc.encode(open('output.txt').read())), 'actual tokens')
"
```
docs/guide/getting-started/configuration.md
+150
View File
@@ -0,0 +1,150 @@
---
title: Configuration
description: Customize RTK behavior via config.toml, environment variables, and per-project filters
sidebar:
order: 4
---
# Configuration
## Config file location
| Platform | Path |
|----------|------|
| Linux | `~/.config/rtk/config.toml` |
| macOS | `~/Library/Application Support/rtk/config.toml` |
```bash
rtk config # show current configuration
rtk config --create # create config file with defaults
```
## Full config structure
```toml
[tracking]
enabled = true # enable/disable token tracking
history_days = 90 # retention in days (auto-cleanup)
database_path = "/custom/path/history.db" # optional override
[display]
colors = true # colored output
emoji = true # use emojis in output
max_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 failure
mode = "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](../resources/telemetry.md).
## 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
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
Prevent specific commands from being rewritten by the hook:
```toml
[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:
```toml
[hooks]
exclude_commands = ["^curl", "^wget", "git rebase"]
```
Invalid regex patterns fall back to prefix matching.
Or for a single invocation:
```bash
RTK_DISABLED=1 git rebase main
```
## 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:
```bash
# Via environment variable
export RTK_TELEMETRY_DISABLED=1
# Via config.toml
[telemetry]
enabled = false
```
## Custom filters
Add your own filters (or override built-ins) in either location:
- **Project-local** — `.rtk/filters.toml` in your project root (committed with the repo)
- **User-global** — `~/.config/rtk/filters.toml` (applies to every project)
See [`src/filters/README.md`](https://github.com/rtk-ai/rtk/blob/master/src/filters/README.md) for the full TOML DSL reference.
### Trusting custom filters
Because a filter can rewrite what your AI assistant sees, custom filter files are **not applied until you trust them**. An untrusted (or edited) filter file is skipped silently on the command path. You review and manage trust with explicit commands:
```bash
rtk trust # shows each filter and asks to confirm (--yes to skip the prompt)
rtk untrust # revokes trust
```
`rtk init` also detects existing filters and lets you enable them — interactively, or non-interactively with `--trust-filters` / `--no-trust-filters`. Trust is tied to the file's contents (SHA-256), so editing a trusted file requires re-running `rtk trust`.
> **Upgrading:** earlier versions applied `~/.config/rtk/filters.toml` without trust. After upgrading, the user-global file is gated like project filters — if you already relied on a global filter, run `rtk trust` once to re-enable it.
docs/guide/getting-started/installation.md
+95
View File
@@ -0,0 +1,95 @@
---
title: Installation
description: Install RTK via curl, Homebrew, Cargo, or from source, and verify the correct version
sidebar:
order: 1
---
# 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
```bash
rtk --version # should print: rtk x.y.z
rtk gain # should show token savings stats
```
If both commands work, RTK is already installed. Skip to [Project initialization](#project-initialization).
## Quick install (Linux and macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
```
## Homebrew (macOS and Linux)
```bash
brew install rtk-ai/tap/rtk
```
## Cargo
:::caution[Name collision risk]
`cargo install rtk` may install **Rust Type Kit** instead of Rust Token Killer — two unrelated projects share the same crate name. Use the explicit Git URL to guarantee the correct package:
:::
```bash
cargo install --git https://github.com/rtk-ai/rtk rtk
```
## 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
```bash
rtk --version # rtk x.y.z
rtk gain # token savings dashboard
```
If `rtk gain` fails but `rtk --version` succeeds, you installed Rust Type Kit by mistake. Uninstall it first:
```bash
cargo uninstall rtk
```
Then reinstall using one of the methods above.
## Project initialization
Run once per project to enable the Claude Code hook:
```bash
rtk init
```
For a global install that patches `settings.json` automatically:
```bash
rtk init --global
```
## Uninstall
```bash
rtk init -g --uninstall # remove hook, RTK.md, and settings.json entry
cargo uninstall rtk # remove binary (if installed via Cargo)
brew uninstall rtk # remove binary (if installed via Homebrew)
```
docs/guide/getting-started/quick-start.md
+86
View File
@@ -0,0 +1,86 @@
---
title: Quick Start
description: Get RTK running in 5 minutes and see your first token savings
sidebar:
order: 2
---
# Quick Start
This guide walks you through your first RTK commands after installation.
## Prerequisites
RTK is installed and verified:
```bash
rtk --version # rtk x.y.z
rtk gain # shows token savings dashboard
```
If not, see [Installation](./installation.md).
## Step 1: Initialize for your AI assistant
```bash
# For Claude Code (global — applies to all projects)
rtk init --global
# For a single project only
cd /your/project && rtk init
```
This installs the hook that automatically rewrites commands. Restart your AI assistant after this step.
### Preview without writing: `--dry-run`
To see exactly what `init` would change before it touches anything, add `--dry-run`:
```bash
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:
```bash
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
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](../resources/what-rtk-covers.md) for the full list.
## Step 3: Check your savings
After a few commands, see how much was saved:
```bash
rtk gain
```
```
Total commands : 12
Input tokens : 45,230
Output tokens : 4,890
Saved : 40,340 (89.2%)
```
## Step 4: Unsupported commands
Commands RTK doesn't recognize run through passthrough — output is unchanged, usage is tracked:
```bash
rtk proxy make install
```
## Next steps
- [What RTK Optimizes](../resources/what-rtk-covers.md) — all supported commands and savings by ecosystem
- [Supported agents](./supported-agents.md) — Claude Code, Cursor, Copilot, and more
- [Configuration](./configuration.md) — customize RTK behavior
docs/guide/getting-started/supported-agents.md
+242
View File
@@ -0,0 +1,242 @@
---
title: Supported Agents
description: How to integrate RTK with Claude Code, Cursor, Copilot, Cline, Windsurf, Codex, OpenCode, Hermes, Kilo Code, Antigravity, and Factory Droid
sidebar:
order: 3
---
# Supported Agents
RTK supports all major AI coding agents across 3 integration tiers. Mistral Vibe support is planned.
## 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
| 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 |
| Factory Droid | Shell hook (`PreToolUse`, matcher `Execute`) | 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
### Claude Code
```bash
rtk init --global # installs hook + patches settings.json
```
Restart Claude Code. Verify:
```bash
rtk init --show # shows hook status
```
### Cursor
```bash
rtk init --global --agent cursor
```
Restart Cursor. The hook uses `preToolUse` with Cursor's `updated_input` format.
### GitHub Copilot (VS Code Chat + CLI)
```bash
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:
```bash
rtk init --uninstall --copilot
rtk 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
```bash
rtk init --global --gemini
```
### OpenCode
```bash
rtk init --global --opencode
```
Creates `~/.config/opencode/plugins/rtk.ts`. Uses the `tool.execute.before` hook.
### Pi
```bash
# Project-local (default)
rtk init --agent pi
# Global — all projects
rtk 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:
```bash
rtk init --uninstall --agent pi
rtk init --uninstall --agent pi --global
```
Removes only the installed Pi extension file.
### OpenClaw
```bash
openclaw plugins install ./openclaw
```
Plugin in the `openclaw/` directory. Uses the `before_tool_call` hook, delegates to `rtk rewrite`.
### Hermes
```bash
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.
### Factory Droid
```bash
rtk init -g --agent droid # user-scoped (~/.factory/hooks.json)
rtk init --agent droid # project-scoped (.factory/hooks.json, commit to share)
```
Installs a `PreToolUse` hook (matcher `Execute`) into Droid's canonical `hooks.json` — falling back to the `hooks` key of `settings.json` only when that file already carries live `PreToolUse` hooks. Respects `$FACTORY_HOME_OVERRIDE`.
RTK honors Droid's own permission lists, never another agent's settings. Commands matching an explicit `commandDenylist` or `commandBlocklist` entry — read from all four settings scopes (`~/.factory/settings.json`, `~/.factory/settings.local.json`, `.factory/settings.json`, `.factory/settings.local.json`) — are left untouched so Droid's native confirmation or block fires on the original command. Every other command is rewritten via `updatedInput` with **no** permission decision: Droid's native flow (allowlist, autonomy level, other hooks) decides on the rewritten command. To auto-run rewritten read-only commands, add `rtk`-prefixed entries (e.g. `rtk git status`) to your `commandAllowlist`.
Uninstall:
```bash
rtk init --uninstall -g --agent droid
rtk init --uninstall --agent droid
```
Removes only RTK's hook entry; other hooks and settings are untouched.
### Cline / Roo Code
```bash
rtk init --agent cline # creates .clinerules in current project
```
Cline reads `.clinerules` as custom instructions. RTK adds guidance telling Cline to prefer `rtk <cmd>` over raw commands.
### Windsurf
```bash
rtk init --global --agent windsurf # creates .windsurfrules in current project
```
### Codex CLI
```bash
rtk init --codex # project-scoped (AGENTS.md)
rtk init --global --codex # user-global (~/.codex/AGENTS.md)
```
### Kilo Code
```bash
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 <cmd>` over raw commands.
### Google Antigravity
```bash
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 <cmd>` over raw commands.
### 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
| 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 <cmd>` |
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
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
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
```bash
RTK_DISABLED=1 git status # runs raw git status, no rewrite
```
Or exclude commands permanently in `~/.config/rtk/config.toml`:
```toml
[hooks]
exclude_commands = ["git rebase", "git cherry-pick"]
```
docs/guide/index.md
+65
View File
@@ -0,0 +1,65 @@
---
title: RTK Documentation
description: RTK (Rust Token Killer) — reduce LLM token consumption by 60-90% on common dev commands, with zero workflow changes
sidebar:
order: 1
---
# 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
```
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
Dozens of commands across all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See [What RTK Optimizes](./resources/what-rtk-covers.md) for the full list with savings percentages.
## Get started
1. **[Installation](./getting-started/installation.md)** — Install RTK and verify you have the right package
2. **[Quick Start](./getting-started/quick-start.md)** — Connect to your AI assistant in 5 minutes
3. **[Supported Agents](./getting-started/supported-agents.md)** — Claude Code, Cursor, Copilot, Gemini, and more
## Measure your savings
```bash
rtk gain # total savings across all sessions
rtk gain --daily # day-by-day breakdown
rtk gain --weekly # weekly aggregation
```
See [Token Savings Analytics](./analytics/gain.md) for export formats and analysis workflows.
## Analyze your usage
```bash
rtk discover # find commands that ran without RTK (missed savings)
rtk session # RTK adoption rate per Claude Code session
```
See [Discover and Session](./analytics/discover.md) for details.
## Further reading
- [Configuration](./getting-started/configuration.md) — config.toml, global flags, env vars, tee recovery
- [Troubleshooting](./resources/troubleshooting.md) — common issues and fixes
- [Telemetry & Privacy](./resources/telemetry.md) — what RTK collects and how to opt out
- [ARCHITECTURE.md](https://github.com/rtk-ai/rtk/blob/master/ARCHITECTURE.md) — system design for contributors
docs/guide/resources/telemetry.md
+168
View File
@@ -0,0 +1,168 @@
---
title: Telemetry & Privacy
description: What RTK collects, how to opt out, and your GDPR rights
sidebar:
order: 3
---
# 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
**Entity**: `RTK AI Labs`
**Contact**: contact@rtk-ai.app
## 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
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
### 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
| 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
| 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)
| 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
| Field | Example | Purpose |
|-------|---------|---------|
| `ecosystem_mix` | `{"git": 45, "cargo": 20, "js": 15}` | Category percentages — where to invest filter development |
### 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
| 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
| 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)
| 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
| Field | Example | Purpose |
|-------|---------|---------|
| `meta_usage` | `{"gain": 5, "discover": 2}` | Which RTK features are actually used |
## 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
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.
```bash
rtk telemetry status # Check current consent state
rtk telemetry enable # Give consent (interactive prompt)
rtk telemetry disable # Withdraw consent
rtk telemetry forget # Withdraw consent + delete local data + request server erasure
```
Environment variable override (blocks telemetry regardless of consent):
```bash
export RTK_TELEMETRY_DISABLED=1
```
## 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)
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 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
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 for manual erasure.
3. You can also email contact@rtk-ai.app directly to request manual erasure.
## 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")
docs/guide/resources/troubleshooting.md
+184
View File
@@ -0,0 +1,184 @@
---
title: Troubleshooting
description: Common RTK issues and how to fix them
sidebar:
order: 2
---
# Troubleshooting
## `rtk gain` says "not a rtk command"
**Symptom:**
```bash
$ rtk gain
rtk: '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:**
```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
```
## 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
**Symptom:** Claude Code (or another agent) runs `cargo test` instead of `rtk cargo test`.
**Checklist:**
1. Verify RTK is installed:
```bash
rtk --version
rtk gain
```
2. Initialize the hook:
```bash
rtk init --global # Claude Code
rtk init --global --cursor # Cursor
rtk init --global --opencode # OpenCode
```
3. Restart your AI assistant.
4. Verify hook status:
```bash
rtk init --show
```
5. Check `settings.json` has the hook registered (Claude Code):
```bash
cat ~/.claude/settings.json | grep rtk
```
## RTK not found after `cargo install`
**Symptom:**
```bash
$ rtk --version
zsh: command not found: rtk
```
**Cause:** `~/.cargo/bin` is not in your PATH.
**Fix:**
For bash (`~/.bashrc`) or zsh (`~/.zshrc`):
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
For fish (`~/.config/fish/config.fish`):
```fish
set -gx PATH $HOME/.cargo/bin $PATH
```
Then reload:
```bash
source ~/.zshrc # or ~/.bashrc
rtk --version
```
## RTK on Windows
### Double-clicking rtk.exe 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)
**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:
```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
```
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
**Symptom:**
```
rtk vitest --run
Error: 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+:
```bash
cargo install --git https://github.com/rtk-ai/rtk
rtk --version # should be 0.23.1+
```
## Compilation error during installation
```bash
rustup update stable
rustup default stable
cargo clean
cargo build --release
cargo install --path . --force
```
Minimum required Rust version: 1.70+.
## OpenCode not using RTK
```bash
rtk init --global --opencode
# restart OpenCode
rtk init --show # should show "OpenCode: plugin installed"
```
## `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:
```bash
cargo install --git https://github.com/rtk-ai/rtk
```
## Run the diagnostic script
From the RTK repository root:
```bash
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?
Open an issue: https://github.com/rtk-ai/rtk/issues
docs/guide/resources/what-rtk-covers.md
+157
View File
@@ -0,0 +1,157 @@
---
title: What RTK Optimizes
description: Commands and ecosystems automatically optimized by RTK with typical token savings
sidebar:
order: 1
---
# 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
| 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
| 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)
| Command | Savings | What changes |
|---------|---------|--------------|
| `gt log` | 75% | Stack summary only |
| `gt status` | 70% | Current branch context |
## 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
| 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
| 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
| Command | Savings | What changes |
|---------|---------|--------------|
| `go test` | 80-90% | Failures only |
| `golangci-lint run` | 75% | Violations grouped by file |
| `go build` | 75% | Errors only |
## Ruby
| Command | Savings | What changes |
|---------|---------|--------------|
| `rspec` | 80-90% | Failures only |
| `rubocop` | 75% | Offenses grouped by file |
| `rake` | 70% | Task output, build errors highlighted |
## .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
| 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
| 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 <file>` | 60-80% | Smart file reading via `rtk read` |
| `rtk smart <file>` | 85% | 2-line heuristic code summary (signatures only) |
## 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
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) |
```bash
# Ultra-compact: even smaller output
rtk git log --ultra-compact
# Debug: see what RTK is doing
rtk git status -vvv
```
:::note
Use `--ultra-compact` (long form) rather than `-u` when working with Git commands. Git's own `-u` flag means `--set-upstream` and the short form can cause confusion.
:::
## 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:
```bash
rtk proxy make install # runs make install, tracks usage, no filtering
```
To check which commands were missed opportunities: `rtk discover`.