chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -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.
|
||||
@@ -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)
|
||||
```
|
||||
@@ -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
|
||||
@@ -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"]
|
||||
```
|
||||
Reference in New Issue
Block a user