Technical Documentation: rtk-ai/rtk

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

rtk filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead.

What RTK Does Copy Chapter

RTK intercepts shell commands and compresses their output before your agent reads it.

How Savings Work Copy Chapter

RTK reduces the bash output your agent reads. That is what RTK measures, and it is not the same as cutting your bill by the same amount.

Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. The reduction dilutes at every step.

The token counts RTK reports are estimated as bytes / 4 — RTK ships no tokenizer, so the percentages are reliable but the absolute token numbers are approximate.

Full explanation: How RTK Savings Work

Installation Copy Chapter

brew install rtk                                              # macOS / Linux
winget install rtk-ai.rtk                                     # Windows
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Then check you have the right package — another project named "rtk" exists on crates.io:

rtk --version   # any current version
rtk gain        # must show the savings dashboard, not "command not found"

Cargo, pre-built binaries, native Windows, WSL, and uninstall: Installation guide

What You Install Copy Chapter

RTK ships as three downloads. The two rtk editions install a binary with the same name — hooks, scripts and agent config work unchanged across both — so they cannot be installed together. Uninstall one before installing the other.

flowchart TD
    agent["Your coding agent"]

    subgraph editions["Pick one · both install a binary named rtk"]
        direction LR
        full["<b>rtk</b><br/>Apache-2.0 + BUSL-1.1<br/>hooks · filters · engine"]
        oss["<b>rtk-oss</b><br/>Apache-2.0 only<br/>hooks · filters"]
    end

    proxy["<b>rtk-proxy</b><br/>BUSL-1.1<br/>compresses API traffic"]

    agent -->|"command output"| full
    agent -->|"command output"| oss
    agent -.->|"API traffic"| proxy

    classDef apache stroke:#2da44e,stroke-width:2px,fill:none
    classDef busl stroke:#0969da,stroke-width:2px,fill:none
    classDef mixed stroke:#8250df,stroke-width:2px,fill:none
    classDef plain stroke:#8c959f,stroke-width:1px,fill:none
    class full mixed
    class oss apache
    class proxy busl
    class agent plain
    style editions fill:none,stroke:#d0d7de,stroke-dasharray:4 4

Production use is free, engine and daemon included. What the BUSL grant does not cover is offering RTK or a derivative to third parties as a commercial product or service — for that, contact [email protected].

curl -fsSL .../install.sh | RTK_EDITION=oss sh    # Apache-2.0 edition
brew install rtk-ai/tap/rtk-oss

What the Apache-2.0 edition omits and where the licence boundary falls: Editions and Licensing

Quick Start Copy Chapter

# 1. Install for your AI tool
rtk init -g                     # Claude Code / Copilot (default)
rtk init -g --gemini            # Gemini CLI
rtk init -g --codex             # Codex (OpenAI)
rtk init -g --agent cursor      # Cursor
rtk init -g --agent windsurf    # Windsurf
rtk init --agent cline          # Cline / Roo Code
rtk init --agent kilocode       # Kilo Code
rtk init --agent antigravity    # Google Antigravity
rtk init --agent kimi           # Kimi AI
rtk init -g --agent pi          # Pi
rtk init --agent omp            # Oh My Pi (OMP)
rtk init --agent hermes         # Hermes
rtk init -g --agent droid       # Factory Droid
rtk init --agent trae           # Trae (project: .trae/hooks.json)
rtk init -g --agent trae        # Trae global: ~/.trae and existing ~/.trae-cn

# 2. Restart your AI tool, then test
git status  # Automatically rewritten to rtk git status

The agent receives compact output without ever calling rtk explicitly.

The hook only fires on Bash tool calls. Built-in tools like Read, Grep and Glob do not pass through it. Use shell commands (cat, rg, find) or call rtk read, rtk grep, rtk find directly.

Per-agent setup, --dry-run, and uninstall: Quick Start · Supported Agents

How It Works Copy Chapter

Without rtk:                                    With rtk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |         full raw output           |            |  compact output      | filter   |
    +-----------------------------------+            +------- (filtered) ---+----------+

Four strategies applied per command type:

1. Smart Filtering - Removes noise (comments, whitespace, boilerplate)
2. Grouping - Aggregates similar items (files by directory, errors by type)
3. Truncation - Keeps relevant context, cuts redundancy
4. Deduplication - Collapses repeated log lines with counts

Does RTK break Claude's prompt cache? No. RTK filters output once per command. The result is stored in history and cached normally on subsequent API calls, so the cache keeps working as expected. Smaller outputs also mean cheaper cache writes and reads. See Troubleshooting for details.

Supported AI Tools Copy Chapter

RTK supports 18 AI coding tools. Each integration rewrites shell commands to rtk equivalents, reducing the bash output the agent reads where the agent supports command interception.

For per-agent setup details, override controls, and graceful degradation, see the Supported Agents guide. The Hermes plugin source and tests live in hooks/hermes/; installed Hermes runtime files still live under ~/.hermes/plugins/rtk-rewrite/.

What RTK Covers Copy Chapter

100+ commands across Git, GitHub CLI, Cargo/Rust, JavaScript (npm, pnpm, vitest, jest, tsc, Next.js, Playwright, Prisma), Python (ruff, pytest, mypy, pip), Go (go test, golangci-lint), Ruby, .NET, JVM (Gradle, Maven), PHP, Docker, Kubernetes, AWS, Terraform, and the file/search builtins.

-v, --verbose          # increase verbosity (-v, -vv, -vvv)
rtk bypass <cmd>       # run one command unfiltered, still tracked

Every command and its filter: What RTK Optimizes

Measure It Copy Chapter

rtk gain                        # Summary stats
rtk gain --graph                # ASCII graph (last 30 days)
rtk gain --history              # Recent command history
rtk gain --daily                # Day-by-day breakdown
rtk gain --all --format json    # JSON export for dashboards

rtk discover                    # Find missed savings opportunities
rtk discover --all --since 7    # All projects, last 7 days

rtk session                     # Show RTK adoption across recent sessions

Attribution, the live dashboard and export formats: Token Savings Analytics

RTK Proxy (optional) Copy Chapter

rtk optimizes command output before your agent reads it. The rtk-proxy daemon extends the same engine to your agent's provider-API traffic — a local background process that sits between your agent and the provider and runs the pipeline on the traffic itself: it compresses payloads, strips bytes no model ever needed before forwarding, and carries the calls your pipeline routes to cheaper models, so they borrow the credential your agent already sends and show up in rtk gain. It can also align prompt-cache breakpoints where the agent leaves them open (opt-in).

rtk claude              # start the daemon if needed, then launch Claude through it
rtk llm-proxy status    # is it up
rtk gain                # savings, command-filtering and proxy side by side

Two independent ways in, because not every harness has a session hook:

rtk <harness> resolving is itself the signal that traffic really goes through the daemon — the subcommand exists only where redirection is verified. Today that is rtk claude. A harness without one is never silently unproxied: it falls through to plain passthrough, and rtk llm-proxy setup lists what can be launched.

It is a separate binary under a separate licence (BUSL-1.1), shipped as its own rtk-proxy-<target> archive — rtk never links it.

Setup and subcommands: RTK Proxy · what it compresses: What the Proxy Compresses · settings and endpoints: Proxy Configuration

The Engine (`pipeline.toml`) Copy Chapter

Everything RTK does — which commands get rewritten, what happens to a tool's output, what the proxy compresses — is expressed in one composable file. The engine (engine/, crate rtk-engine, BUSL-1.1) reads it, so the levers are configurable instead of hard-coded.

Upgrading changes nothing. With no pipeline file you are on rtk:default: the same PreToolUse rewrite, the same awareness file, your filters.toml, your config.toml. Everything beyond that is opt-in, one line at a time:

# ~/.config/rtk/pipeline.toml
[pipeline]
extends = ["rtk:posthook", "rtk:proxy"]

The tour: Pipelines · the reference: Writing a Pipeline, Conditions and Judges, Methods, Tasks and Upstreams · the commands: Pipeline Commands · write your own method: Plugins

Documentation Copy Chapter

rtk-ai.app/guide is the full user guide.

Repository references: engine/README.md · proxy/README.md · ARCHITECTURE.md · CONTRIBUTING.md · SECURITY.md

RTK collects no command content and no file contents. Telemetry is anonymous and off by default — it sends nothing until you opt in with explicit consent (GDPR Art. 6 & 7) via rtk telemetry enable, and documented in Telemetry & Privacy.

Star History Copy Chapter

StarMapper Copy Chapter

Core team Copy Chapter

• Patrick Szymkowiak — Founder
  GitHub · LinkedIn
• Florian Bruniaux — Core contributor
  GitHub · LinkedIn
• Adrien Eppling — Core contributor
  GitHub · LinkedIn
• Nicolas Le Cam — Core contributor
  Github · LinkedIn
• Takayuki Maeda — Core contributor
  GitHub · LinkedIn

Contributing Copy Chapter

Contributions welcome! Please open an issue or PR on GitHub.

Join the community on Discord.

License Copy Chapter

The rtk CLI is Apache-2.0 — see LICENSE.

It links one component under a different licence. rtk-engine (engine/) is
BUSL-1.1, source-available: see engine/LICENSE. Its
Additional Use Grant permits production use as part of the rtk binary, so
running rtk is covered; using the engine on its own, or inside another
product, is not until the Change Date.

The rtk-proxy daemon (proxy/) is BUSL-1.1 on the same terms and ships as
its own archive with its licence alongside — rtk never links it.

Disclaimer Copy Chapter

See DISCLAIMER.md.

Overview (`engine/README.md`) Copy Section

rtk-engine

The RTK pipeline engine: it parses, resolves and validates pipeline.toml, evaluates rules, and runs the methods and chains those rules name. The rtk CLI links it for the hooks; the rtk-proxy daemon links it for proxy.request rules.

User documentation Copy Chapter

The pipeline reference lives in the user guide, docs/guide/pipelines/, published at rtk-ai.app/guide:

Worked pipelines: examples/pipelines/.

Contributing Copy Chapter

See CONTRIBUTING.md. rtk methods list prints every registered method with its contract.

License Copy Chapter

Business Source License 1.1 — source-available, not OSI open source. Production use is free; offering the engine, or a derivative, to third parties as a paid or hosted product needs a licence from [email protected]. On 2030-09-09 this version converts to Apache-2.0. The rtk CLI's own source is Apache-2.0, and its Apache-2.0 edition is built without this crate — see Editions and Licensing.

Overview (`hooks/README.md`) Copy Section

LLM Agent Hooks

Scope Copy Chapter

Deployed hook artifacts — the files and agent-specific configuration installed on user machines by rtk init. External scripts and plugins are thin delegates to rtk rewrite; native processors such as Codex call the same Rust rewrite registry directly. Zero filtering logic is duplicated in this directory.

Contains per-agent hook scripts and configuration files for 13 supported agents (Claude Code, Copilot, Cursor, Cline, Windsurf, Codex, OpenCode, Hermes, Pi, Oh My Pi, Mistral Vibe, Trae, Google Antigravity). rtk init installs them.

Does not own: hook installation/uninstallation (that's src/hooks/init/), the rewrite pattern registry (that's discover/registry), or integrity verification (that's src/hooks/integrity.rs).

Awareness files Copy Chapter

rtk-awareness.md, rtk-awareness-high.md, rtk-awareness-full.md are the agent-neutral
instruction files embedded by rtk init (RTK.md, GEMINI.md, rules files, AGENTS.md blocks).
awareness.level in config.toml picks one for hook-based agents; agents without a hook always get
rtk-awareness-full.md, the only one that tells the agent to prefix commands with rtk.

Purpose Copy Chapter

LLM agent integrations that intercept CLI commands and route them through RTK for token optimization. Each hook transparently rewrites raw commands (e.g., git status) to their RTK equivalents (e.g., rtk git status), cutting the bash output that reaches the LLM context without requiring the agent or user to change their workflow.

How It Works Copy Chapter

Agent runs command (e.g., "cargo test --nocapture")
  -> Hook intercepts (PreToolUse / plugin event)
  -> Reads JSON input, extracts command string
  -> Uses the shared RTK rewrite registry
  -> Registry matches pattern, returns "rtk cargo test --nocapture"
  -> Hook sends response in agent-specific JSON format
  -> Agent executes "rtk cargo test --nocapture" instead
  -> Filtered output reaches LLM

All rewrite logic lives in the rtk binary. External hook scripts call rtk rewrite; native Rust hook processors call the registry directly. This keeps one source of truth for all 70+ rewrite patterns.

Directory Structure Copy Chapter

Each agent subdirectory has its own README with hook-specific details:

• claude/ — Shell hook, PreToolUse JSON format, settings.json patching, test script
• copilot/ — Rust binary hook, dual format (VS Code Chat vs Copilot CLI), deny-with-suggestion fallback
• cursor/ — Shell hook, Cursor JSON format, empty {} response requirement
• cline/ — Rules file (prompt-level), .clinerules project-local installation
• windsurf/ — Rules file (prompt-level), .windsurfrules workspace-scoped
• codex/ — Rust binary hook (rtk hook codex), PreToolUse.updatedInput, .codex/hooks.json / $CODEX_HOME/hooks.json, plus AGENTS.md awareness
• opencode/ — TypeScript plugin, OpenCode 2.0 and 1.x >= 1.18.29, in-place mutation
• pi/ — TypeScript extension, tool_call event, local isBashToolCallEvent guard, in-place mutation, ~/.pi/agent/extensions/; shared with Oh My Pi (OMP) — OMP installs the same file at .omp/extensions/ via its legacy-pi-compat layer
• hermes/ — Python plugin, pre_tool_call hook, in-place terminal command mutation
• vibe/ — Rust binary hook (rtk hook vibe), pre_tool entry in ~/.vibe/hooks.toml, hook_specific_output.tool_input rewrite plus system_message for UI visibility
• antigravity/ — Rust binary hook (rtk hook antigravity), PreToolUse plugin entry in .agents/plugins/rtk/hooks.json or ~/.gemini/config/plugins/rtk/hooks.json, transparent rewrite via overwrite.CommandLine

Supported Agents Copy Chapter

JSON Formats by Agent Copy Chapter

Claude Code (Shell Hook) Copy Section

Input (stdin):

{
  "tool_name": "Bash",
  "tool_input": { "command": "git status" }
}

Output (stdout, when rewritten):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "RTK auto-rewrite",
    "updatedInput": { "command": "rtk git status" }
  }
}

Cursor (Shell Hook) Copy Section

Input: Same as Claude Code.

Output (stdout, when rewritten):

{
  "permission": "allow",
  "updated_input": { "command": "rtk git status" }
}

Returns {} when no rewrite (Cursor requires JSON for all paths).

Trae (Rust Binary) Copy Section

Install with rtk init --agent trae for .trae/hooks.json, or rtk init -g --agent trae for ~/.trae/hooks.json; global installation also updates ~/.trae-cn/hooks.json when that directory already exists.

Input: Trae PreToolUse payloads for RunCommand, such as:

{
  "tool_name": "RunCommand",
  "tool_input": { "command": "git status", "description": "Check status" }
}

Output (only when rewritten):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": { "command": "rtk git status", "description": "Check status" }
  }
}

RTK deliberately does not set permissionDecision; Trae retains its own command-approval policy.

Codex CLI (Rust Binary) Copy Section

Input (stdin):

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "permission_mode": "default",
  "tool_input": { "command": "git status" }
}

Output (stdout, when rewritten):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "RTK auto-rewrite",
    "updatedInput": { "command": "rtk git status" }
  }
}

The allow value is required by Codex to accept updatedInput; Codex still runs its native approval and sandbox checks after applying the replacement. Those checks classify the rewritten command, and Codex does not currently unwrap the rtk binary for its safe/dangerous-command heuristics. Missing or unknown permission modes and other no-rewrite cases produce no stdout.

Copilot CLI (Rust Binary) Copy Section

Input (stdin, camelCase, toolArgs is JSON-stringified):

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

Output (no updatedInput support -- uses deny-with-suggestion):

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

VS Code Copilot Chat (Rust Binary) Copy Section

Input (stdin, snake_case):

{
  "tool_name": "Bash",
  "tool_input": { "command": "git status" }
}

Output: Same as Claude Code format (with updatedInput).

Gemini CLI (Rust Binary) Copy Section

Input (stdin):

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

Output (when rewritten):

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

No rewrite: {"decision": "allow"}

Mistral Vibe (Rust Binary) Copy Section

Input (stdin):

{
  "tool_name": "bash",
  "tool_input": { "command": "git status" },
  "hook_event_name": "pre_tool",
  "session_id": "..."
}

Output (when rewritten):

{
  "hook_specific_output": {
    "tool_input": { "command": "rtk git status" }
  },
  "system_message": "rtk: rewrote to `rtk git status`"
}

No rewrite: exit 0 with empty stdout (Vibe's contract for "no opinion" from a pre_tool hook).

Google Antigravity (Rust Binary) Copy Section

Input (stdin):

{
  "toolCall": {
    "name": "run_command",
    "args": { "CommandLine": "git status" }
  }
}

Output (when rewritten):

{
  "decision": "allow",
  "reason": "Rewritten by rtk for token optimization.",
  "overwrite": {
    "CommandLine": "rtk git status"
  }
}

No rewrite: {"decision": "allow"}

OpenCode (TypeScript Plugin) Copy Section

Delegates to rtk hook opencode via node:child_process.execFile (supports OpenCode 2.0 and 1.x >= 1.18.29). The Rust side owns the rewrite rules and the permission verdict; the plugin only carries it. The hook must be awaited — args.command = … after the call returns has nothing left to rewrite:

const tool = String(input?.tool ?? "").toLowerCase()
if (tool === "bash" || tool === "shell") {
  // 2.x also has `event.agent`, which rtk needs so an agent-scoped ask or deny
  // is judged against the agent that runs the command. 1.x sends no agent.
  const argv = ["hook", "opencode"]
  if (agent) argv.push("--agent", agent)
  argv.push(command)
  const rewritten = await new Promise((resolve) => {
    execFile(rtkBin, argv, { encoding: "utf8", timeout: 3000, windowsHide: true }, (err, stdout) => {
      if (err) return resolve(null) // pass through unchanged
      try {
        resolve(JSON.parse(String(stdout ?? "").trim() || "{}").command ?? null)
      } catch {
        resolve(null)
      }
    })
  })
  // {} means the rewrite would change OpenCode's own verdict — run as typed.
  if (rewritten && rewritten !== command) {
    args.command = rewritten
  }
}

Hermes (Python Plugin) Copy Section

Mutates args["command"] in-place via the pre_tool_call hook:

result = subprocess.run(["rtk", "rewrite", command], capture_output=True, text=True, timeout=2)
rewritten = result.stdout.strip()
if result.returncode in {0, 3} and rewritten and rewritten != command:
    args["command"] = rewritten

Command Rewrite Registry Copy Chapter

The registry handles command patterns across these categories:

Compound Command Handling Copy Section

The registry handles &&, ||, ;, |, |&, and & operators:

• Pipe (|): Producers and intermediate stages stay raw; only a pipeline-safe final stage is rewritten
• Stderr pipe (|&): The complete pipeline stays raw
• And/Or/Semicolon (&&, ||, ;): Both sides rewritten independently
• Pipeline-safe rules: Initially limited to argument-safe grep, rg, and wc invocations; search pattern-file forms defer

Example: cargo fmt --all && cargo test becomes rtk cargo fmt --all && rtk cargo test

Override Controls Copy Section

• RTK_DISABLED=1: Per-command override (RTK_DISABLED=1 git status runs raw)
• exclude_commands: In ~/.config/rtk/config.toml, list commands to never rewrite. Matches against the full command after stripping env prefixes. Subcommand patterns work ("git push" excludes git push origin main). Patterns starting with ^ are treated as regex.
• Already-RTK: rtk git status passes through unchanged (no rtk rtk git)

Exit Code Contract Copy Chapter

Hooks must never block command execution. All error paths (missing binary, bad JSON, rewrite failure) must exit 0 so the agent's command runs unmodified. A hook that exits non-zero prevents the user's command from executing.

When there is no rewrite to apply, the hook must produce no output (or {} for Cursor, which requires JSON on all paths).

Graceful Degradation Copy Chapter

Hooks are non-blocking -- they never prevent a command from executing:

• jq not installed: warning to stderr, exit 0 (command runs raw)
• rtk binary not found: warning to stderr, exit 0
• rtk version too old (< 0.23.0): warning to stderr, exit 0
• Invalid JSON input: pass through unchanged
• rtk rewrite crashes: hook exits 0 (subprocess error ignored)
• Filter logic error: fallback to raw command output

Adding a New Agent Integration Copy Chapter

New integrations must follow the Exit Code Contract and Graceful Degradation above, as well as the project's Design Philosophy.

Integration Tiers Copy Section

Eligibility Copy Section

RTK supports AI coding assistants that developers actually use day-to-day. To add a new agent:

• Agent has a documented, stable hook/plugin API (not experimental/alpha)
• Agent is actively maintained (commit activity in last 3 months)
• Integration follows the exit code contract (exit 0 on all error paths)
• Hook output matches the agent's expected JSON format exactly

Maintenance Copy Section

If an agent's API changes and the hook breaks, the integration should be updated promptly. If the agent becomes unmaintained or the hook can't be fixed, the integration may be deprecated with a release note.

Overview (`openclaw/README.md`) Copy Section

RTK Plugin for OpenClaw

Transparently rewrites shell commands executed via OpenClaw's exec tool to their RTK equivalents, so filtered output reaches the LLM context.

How it works Copy Chapter

The plugin registers a before_tool_call hook that intercepts exec tool calls. When the agent runs a command like git status, the plugin delegates to rtk rewrite which returns the optimized command (e.g. rtk git status). The compressed output enters the agent's context window, saving tokens.

All rewrite logic lives in RTK itself (rtk rewrite). This plugin is a thin delegate -- when new filters are added to RTK, the plugin picks them up automatically with zero changes.

Installation Copy Chapter

Prerequisites Copy Section

RTK must be installed and available in $PATH:

brew install rtk
# or
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Install the plugin Copy Section

# Copy the plugin to OpenClaw's extensions directory
mkdir -p ~/.openclaw/extensions/rtk-rewrite
cp openclaw/index.ts openclaw/openclaw.plugin.json ~/.openclaw/extensions/rtk-rewrite/

# Restart the gateway
openclaw gateway restart

Or install via OpenClaw CLI Copy Section

openclaw plugins install ./openclaw

Configuration Copy Chapter

In openclaw.json:

{
  plugins: {
    entries: {
      "rtk-rewrite": {
        enabled: true,
        config: {
          enabled: true,    // Toggle rewriting on/off
          verbose: false     // Log rewrites to console
        }
      }
    }
  }
}

Permissions Copy Chapter

RTK keeps the deny gate. OpenClaw owns approval.

The plugin runs rtk rewrite with RTK_REWRITE_HOST=openclaw. That tells RTK this host applies its own exec policy -- tools.exec.mode, security, ask -- to whatever the before_tool_call hook returns, so RTK does not prompt for a command that matched no rule.

Without it, RTK evaluates every command against Claude Code's four settings files (.claude/settings.json, .claude/settings.local.json, and the two under ~/.claude/) and returns "ask" for anything they do not explicitly allow. The plugin turned that into a blocking approval that denied on timeout, so a host running tools.exec.mode=full still stopped on every rewritable command, waiting on a decision derived from another agent's config file. See #3908.

What does not change:

• A command matching a permissions.deny rule in those Claude Code settings files is still refused, and the plugin blocks the tool call. As in Claude Code, a rule matches the command as written rather than every way of invoking the program — Bash(git push *) does not stop git -C . push — so a deny rule is not a security boundary.
• A command matching a permissions.ask rule you wrote still prompts when RTK rewrites it: RTK returns exit 3 and the plugin raises its approval request. Only the default ask -- no rule matched -- is relaxed. A command RTK does not rewrite passes through to OpenClaw's own policy unchanged.
• A command containing a command substitution (`, $(...)) or a redirect to a file is never rewritten, on any host.

What does change: the plugin no longer prompts for a command that matched no rule. Any approval prompt you still see comes from OpenClaw itself, or from an explicit ask rule.

Writing exec rules Copy Section

The plugin replaces params.command in before_tool_call, and OpenClaw carries hook adjustments forward into the parameters it passes to the exec tool. The tool therefore receives rtk git push, not git push, and the checks the exec tool runs on its own parameters -- tools.exec.mode, tools.exec.security, tools.exec.ask, and the exec-approvals allowlist -- match against the rtk form. Write those rules against the rtk form. This was already true before the permission change.

One gate runs earlier and sees the original command: a trusted tool policy registered with api.registerTrustedToolPolicy(...). OpenClaw runs trusted policies before ordinary before_tool_call hooks, so such a policy is shown git push, not rtk git push. Only the exec tool's own checks see the rewritten string.

Upgrading from an earlier build Copy Section

An rtk older than RTK_REWRITE_HOST cannot collapse the default ask, so it
prompts for more commands than a current one; the plugin keeps treating exit 3
as "rewrite it, require approval", and upgrading is what removes the redundant
prompt. Nothing else changes on upgrade.

rtk version Copy Section

No minimum. RTK_REWRITE_HOST travels in the environment rather than in argv precisely so that an rtk which does not know it simply ignores it: you get the previous behaviour, a prompt on exit 3, rather than a gate that silently stops matching. The exit-code table in src/hooks/README.md lists what each exit means for a delegate.

What gets rewritten Copy Chapter

Everything that rtk rewrite supports (30+ commands). See the full command list.

What's NOT rewritten Copy Chapter

Handled by rtk rewrite guards:

• Commands already using rtk
• Piped commands (|, &&, ;)
• Heredocs (<<)
• Commands without an RTK filter

License Copy Chapter

Apache 2.0 -- same as RTK.

Overview (`proxy/README.md`) Copy Section

rtk-proxy

rtk optimizes command output before it reaches your assistant's context.
rtk-proxy brings the same engine to the API traffic itself: it sits
between your AI coding tool and the real provider endpoint, runs the pipeline
on the traffic — compression, and the relay of calls your pipeline routes to
cheaper models — then relays the response back. It is agent-agnostic by
design: it speaks the provider's dialect, not the agent's. Today Claude Code
is wired, through rtk claude; other agents follow as their redirection is
verified end to end.

It is a local daemon: one background process on your machine, driven by the
rtk CLI. It does four things: intercept, compress, forward, record.

Claude Code ──▶ rtk-proxy ──▶ api.anthropic.com
                     │
                     ├─ normalize: strip ANSI / redraws / dupes
                     ├─ your proxy.request.tool_result method rules
                     ├─ (opt-in) cache-align
                     └─ record usage ──▶ rtk gain

User documentation Copy Chapter

Setup, what the daemon compresses, its settings and endpoints live in the user guide, docs/guide/proxy/, published at rtk-ai.app/guide:

rtk claude              # start the daemon if needed, then launch Claude through it
rtk llm-proxy status    # is it up
rtk gain                # savings, RTK and proxy side by side

Building Copy Chapter

The crate lives in the rtk repository as its own workspace, and is not
linked into the rtk CLI — rtk locates and spawns this binary.

cargo build --release --manifest-path proxy/Cargo.toml   # the daemon
cargo test --manifest-path proxy/Cargo.toml              # unit + functional + real-binary smoke

Contributing to the daemon: see docs/contributing/.

License Copy Chapter

Business Source License 1.1 — source-available, not an
OSI-approved open-source license. Its Additional Use Grant permits free
production use, including running the daemon. What it does not permit is
offering rtk-proxy, or a derivative, to third parties as a paid or hosted
product or service — for that, contact [email protected]. On
2030-09-09 this version converts automatically to Apache-2.0.

This is a different license from the rtk CLI in the parent directory, which
is Apache-2.0. The two are separate crates and separate binaries; rtk never
links this code.

Overview (`examples/pipelines/README.md`) Copy Section

Pipeline examples

Example pipeline files. For how pipeline files work, see
Pipelines.
Copy one to ~/.config/rtk/pipeline.toml (or drop several into
~/.config/rtk/pipelines/) and run rtk pipeline validate.

Writing nothing is also a configuration: with no pipeline file you are on
rtk:default — RTK exactly as it works today.

The six built-in reference pipelines are compiled in — print any of them
with rtk pipeline show rtk:default / rtk:posthook / rtk:proxy /
rtk:delegate-reads / rtk:verbatim-diffs / rtk:terse.

Overview (`hooks/antigravity/README.md`) Copy Section

Google Antigravity Hooks

Part of hooks/

Specifics Copy Chapter

• Native programmatic PreToolUse lifecycle hook (rtk hook antigravity) providing transparent command rewriting via overwrite.CommandLine
• Supported across all Antigravity surfaces: Antigravity CLI (agy), Antigravity IDE, and Antigravity 2.0
• Installs the awareness file selected by awareness.level as rules/AGENTS.md inside the plugin (plain markdown, applied whenever the plugin is active)
• Uses Antigravity's modular Plugin architecture:
  • Local workspace: .agents/plugins/rtk/
  • Global scope: ~/.gemini/config/plugins/rtk/
• Full lifecycle support:
  • Setup: rtk init --agent antigravity (or rtk init -g --agent antigravity)
  • Preview: rtk init --agent antigravity --dry-run
  • Uninstallation: rtk init --agent antigravity --uninstall (or rtk init -g --agent antigravity --uninstall)

Permission Evaluation Note Copy Chapter

Antigravity evaluates its tool permissions after lifecycle hooks rewrite commands. If you maintain strict command allowlists, ensure permitted commands account for rtk (e.g. command(rtk git status) or command(rtk *)).

Overview (`hooks/claude/README.md`) Copy Section

Claude Code Hooks

Part of hooks/

Specifics Copy Chapter

• Shell-based PreToolUse hook -- requires jq for JSON parsing
• Returns updatedInput JSON for transparent command rewrite (agent doesn't know RTK is involved)
• Exits silently (exit 0) on any failure: jq missing, rtk missing, rtk too old (< 0.23.0), no match
• Version guard checks rtk --version against minimum 0.23.0
• ../rtk-awareness.md (or -high / -full, per awareness.level in config.toml) is the instructions file embedded into CLAUDE.md by rtk init

Overview (`hooks/cline/README.md`) Copy Section

Cline / Roo Code Hooks

Part of hooks/

Specifics Copy Chapter

• Prompt-level guidance only (no programmatic hook) -- relies on Cline reading custom instructions
• Installs ../rtk-awareness-full.md (shared, agent-neutral): the instruction to prefix every shell command with rtk, plus meta commands. No hook, so the full level is always used regardless of awareness.level
• Installed to .clinerules (project-local) by rtk init

Overview (`hooks/codex/README.md`) Copy Section

Codex CLI Hooks

Part of hooks/

Specifics Copy Chapter

• Native Rust PreToolUse processor: rtk hook codex
• Transparently rewrites tool_input.command with Codex's updatedInput response
• Registers a Bash matcher in .codex/hooks.json (project) or $CODEX_HOME/hooks.json (global)
• Writes the shared awareness document selected by awareness.level to RTK.md, referenced from AGENTS.md
• Installed by rtk init --codex (project) or rtk init -g --codex (global)
• Uninstalled by adding --uninstall to the corresponding project or global command

Codex requires permissionDecision: "allow" in the hook response for updatedInput to take effect. Codex applies the replacement before its normal command approval and sandbox checks, so those native checks still run on the rewritten command. Codex's command safety classifier does not currently unwrap the rtk binary, so classification is based on the rewritten command. This can add prompts for known-safe commands or obscure signals for wrapped mutating commands such as git push.

RTK rewrites the documented Codex permission modes. Missing or unknown permission modes, no match, malformed JSON, unsupported commands, heredocs, substitutions, and file redirections fail open: the hook exits successfully without stdout and Codex executes the original command.

RTK does not parse Codex execution rules or reuse another agent's permission
files: Codex's native execution layer remains responsible for those rules.

History in workspace-write sandboxes Copy Chapter

Command rewriting can work even when the sandbox prevents RTK from writing its
SQLite history database. If recording reports SQLITE_CANTOPEN, run
rtk init --codex outside the sandbox to see an optional Codex configuration
snippet using the actual database parent directory. The path follows
RTK_DB_PATH, then tracking.database_path, then the platform default.

To opt in, merge the printed sandbox_workspace_write.writable_roots entry into
your Codex config.toml, preserving existing entries. SQLite needs directory
access for journal/WAL files as well as the database itself. RTK only prints the
snippet; it does not change sandbox settings. Review custom paths before granting
access, and prefer a dedicated RTK data directory.

See the Codex configuration reference.

Overview (`hooks/copilot/README.md`) Copy Section

GitHub Copilot Hooks

Part of hooks/

Specifics Copy Chapter

• Uses the rtk hook copilot Rust binary (not a shell script) -- no jq dependency
• Auto-detects two input formats: VS Code Copilot Chat (snake_case tool_name/tool_input) and Copilot CLI (camelCase toolName/toolArgs with JSON-stringified args)
• VS Code format: returns updatedInput for transparent rewrite
• Copilot CLI format: returns permissionDecision: "deny" with suggestion (Copilot CLI API doesn't support updatedInput)

Overview (`hooks/cursor/README.md`) Copy Section

Cursor IDE Hooks

Part of hooks/

Specifics Copy Chapter

• Same delegating pattern as Claude Code hook but outputs Cursor's JSON format (permission/updated_input instead of hookSpecificOutput/updatedInput)
• Returns {} (empty JSON) when no rewrite applies -- Cursor requires JSON output for all code paths
• Requires jq and rtk >= 0.23.0

Overview (`hooks/hermes/README.md`) Copy Section

RTK Plugin for Hermes

Rewrites Hermes terminal tool commands to RTK equivalents before execution, so Hermes receives compact command output without changing your workflow.

Installation Copy Chapter

rtk init --agent hermes

The installer writes the plugin to ~/.hermes/plugins/rtk-rewrite/ and enables it through plugins.enabled in the Hermes config.

How it works Copy Chapter

Hermes loads plugins from Python, so the plugin entrypoint is Python. The Python code is only a thin Hermes adapter. It reads the Hermes terminal tool payload, calls rtk rewrite for the actual command decision, then mutates the terminal tool command before Hermes executes it.

All rewrite rules stay in Rust inside rtk rewrite. When RTK adds or changes command rewrite behavior, the Hermes plugin picks up that behavior by delegating to the RTK binary.

Fail-open behavior Copy Chapter

The plugin does not block command execution. If anything goes wrong, Hermes runs the original command unchanged.

If rtk is not available in PATH when Hermes loads the plugin, the plugin prints a warning and skips hook registration.

• rtk is missing from PATH
• rtk rewrite exits with an error
• Hermes sends a non-terminal tool call
• The tool payload has no string command
• The plugin raises an unexpected exception

Limitations Copy Chapter

• Only Hermes terminal tool calls are rewritten.
• Commands skipped by rtk rewrite stay unchanged, including commands already prefixed with rtk, compound shell commands, heredocs, and commands without an RTK filter.
• Shell hooks are not used for Hermes command rewriting. The integration depends on Hermes loading Python plugins and passing a mutable terminal tool payload.

Overview (`hooks/kilocode/README.md`) Copy Section

Kilo Code Hooks

Part of hooks/

Specifics Copy Chapter

• Prompt-level guidance only (no programmatic hook) -- relies on Kilo Code reading custom instructions
• Installs ../rtk-awareness-full.md (shared, agent-neutral): the instruction to prefix every shell command with rtk, plus meta commands. No hook, so the full level is always used regardless of awareness.level
• Installed to .kilocode/rules/rtk-rules.md (project-local) by rtk init --agent kilocode

Overview (`hooks/opencode/README.md`) Copy Section

OpenCode Hooks

Part of hooks/

Specifics Copy Chapter

• TypeScript plugin (not a shell hook)
• Supports OpenCode 2.0 (execute.before via { id, setup }) and OpenCode 1.x >= 1.18.29 (tool.execute.before), the dual-shape default export OpenCode's own V2 docs prescribe
• Requires OpenCode 1.18.29 or newer, the floor OpenCode's V2 plugin docs give for this dual-shape export. With an older OpenCode, rtk init -g --opencode writes nothing and leaves an existing plugin alone, when it can read opencode --version
• Thin delegating shim: calls rtk hook opencode as a subprocess, and the Rust side is the single source of truth for rewrite rules
• The Rust side judges the command against OpenCode's own permission rules and answers {} whenever the rewrite would change the verdict those rules give — OpenCode evaluates the final command itself, so RTK never lifts a deny, silences an ask, or blocks an allow (#4195). Rules are read from root and project opencode.json/.jsonc in the order OpenCode resolves them: the legacy permission map first, then the 2.x permissions list, whatever order the file declares them. Every file's root rules load before any file's agent rules, so a project allow cannot outrank a global agent ask. 2.x list actions match as globs against shell, so sh* covers it; a list rule whose action only names bash does not count, because OpenCode ignores it there. A legacy map key the two generations read differently (shell and sh* apply only on 2.x, b* only on 1.x) makes rtk leave the command as typed, because it cannot tell which generation it is serving. Global rules come before project rules. An agent defined as a markdown file in agents/ or agent/, under ~/.config/opencode/ or any .opencode/ from the working directory up, whose frontmatter declares permission: or permissions:, is not parsed here, so no rewrite happens for that agent and OpenCode applies its own rules.
• Uses standard node:child_process.execFile (compatible with OpenCode CLI, OpenCode Desktop/Electron, and Windows; zero Bun/zx dependencies)
• Passes the command as a single argv element, never through a shell
• Resolves rtk from the system PATH only (PATHEXT on Windows), and skips a PATH entry that is a directory. OpenCode's shell tool runs with OpenCode's own PATH and never sources .profile/.bashrc, so an rtk found outside PATH cannot be spawned as a bare rtk … — see #4462
• Probes the resolved binary once per session with rtk hook opencode --help (cached): exit 0 means the subcommand is there, exit 2 means it predates it, and a broken or wrong-arch binary fails to spawn. Not a version number — a develop build reports rtk 0.49.0 and so does a release that lacks the subcommand
• Passes OpenCode 2.x's event.agent as rtk hook opencode --agent <name>, so an agent.<name>.permission ask or deny is judged against the agent that runs the command. OpenCode 1.x sends no agent field, so that path stays root-only
• Two separate off switches, both named RTK_DISABLED. The per-command form is RTK_DISABLED=1 git status, an env prefix inside the command string; the Rust rewrite engine handles that one and the plugin passes the string through untouched. The plugin also reads RTK_DISABLED=1 from OpenCode's own process environment, which switches rewriting off for the whole session
• Mutates command in-place (event.input.command in v2, output.args.command in v1) if the answered rewrite differs from the original
• Any failure — non-zero exit, timeout, non-JSON stdout, missing binary — passes the command through unchanged
• Installed to ~/.config/opencode/plugins/rtk.ts by rtk init -g --opencode
• Tests: node --test hooks/opencode/rtk.test.mjs

Overview (`hooks/pi/README.md`) Copy Section

Pi Hooks

Part of hooks/

Design Intent Copy Chapter

RTK's Pi extension is a rewrite-only token optimizer. It mutates bash commands to their
rtk-prefixed equivalents, so filtered output reaches the context.

Permission gating is intentionally out of scope. RTK does not block, confirm, or audit
commands — that concern belongs to a dedicated permission extension (e.g. one that gates
rm -rf, sudo, etc.). This separation keeps RTK's hook fast, predictable, and composable
with other Pi extensions.

Specifics Copy Chapter

• TypeScript extension using Pi's ExtensionAPI (not a shell hook, no zx dependency)
• Subscribes to tool_call event, narrows to bash tool
• Calls rtk rewrite via pi.exec; mutates event.input.command in-place if rewrite differs
• All error paths return undefined (pass through); RTK never blocks execution on its own
• If an rtk pipeline rule blocks the command, the extension returns { block: true, reason } with the rule's message
• Version guard at load time: checks rtk >= 0.23.0; warns and registers no-op if too old or missing
• Install updates only current or known historical stock content. For modified or unrelated content it asks before overwriting; --auto-patch approves and --no-patch leaves the file unchanged. A declined protected update, including --no-patch, exits nonzero; in --dry-run mode it reports the prompt without changing files or creating directories. LF and CRLF line endings are treated as the same stock content.
• Installed to .pi/extensions/rtk.ts by rtk init --agent pi (project-local) or ~/.pi/agent/extensions/rtk.ts by rtk init --agent pi --global

The same extension is shared with Oh My Pi (OMP) through OMP's legacy-pi-compat layer. OMP installs it at .omp/extensions/rtk.ts (project-local) or ~/.omp/agent/extensions/rtk.ts (global). The global OMP path follows PI_CODING_AGENT_DIR, which OMP also honors. When the Pi and OMP paths in either scope resolve to the same file, RTK records Pi/OMP ownership in an adjacent hidden .rtk-agents state file. A valid sidecar is authoritative; missing or unreadable state is treated as uncertain, warned about, and not used to claim sole ownership. A definitively shared project or global file prompts before removal (--auto-patch approves it); an uncertain legacy or corrupt-state uninstall warns and proceeds, while --no-patch still leaves definitively shared files in place with a nonzero exit. RTK currently targets OMP's default profile and .omp project directory, not named profiles or custom PI_CONFIG_DIR locations.

Uninstall Copy Chapter

# Remove project-local install (run from the project root)
rtk init --uninstall --agent pi
# → removes .pi/extensions/rtk.ts

# Remove global install
rtk init --uninstall --agent pi --global
# → removes ~/.pi/agent/extensions/rtk.ts

Uninstalling an absent extension is a no-op. Current and known historical stock files are removed, while modified RTK content is preserved and causes a normal uninstall to fail with a manual-removal message; --dry-run previews that refusal. Unreadable content is left alone but causes a normal uninstall to fail nonzero; --dry-run reports it and succeeds. Unrelated content is left alone. When Pi and OMP paths in either scope resolve to the same file, a valid sidecar recording both agents makes uninstall ask before removing it; --auto-patch approves and --no-patch leaves it in place with a nonzero exit. Missing or unreadable ownership state produces a warning and proceeds without definitive shared-file protection. Only the extension file and RTK's adjacent ownership state are managed by install/uninstall.

Overview (`hooks/vibe/README.md`) Copy Section

Mistral Vibe Hooks

Part of hooks/

Specifics Copy Chapter

• Uses the rtk hook vibe Rust binary (not a shell script) -- no jq dependency
• pre_tool hook declared in ~/.vibe/hooks.toml (user-scoped) with match = "bash" and strict = false
• Reads Vibe's stdin JSON payload (tool_name, tool_input.command, hook_event_name, session_id)
• Returns hook_specific_output.tool_input.command for transparent rewrite plus a system_message for UI visibility
• Non-bash tool / empty command / malformed JSON / RTK-unknown command → passthrough (exit 0, empty stdout)
• RTK permission deny → {"decision":"deny","reason":"..."}
• Alongside the hook, a system prompt at ~/.vibe/prompts/rtk.md is installed as a belt-and-suspenders fallback (skip with --hook-only); its content follows awareness.level in config.toml (../rtk-awareness*.md)
• Installed globally via rtk init -g --agent vibe; there is no project-scoped variant

Notes Copy Chapter

• The hook is a subcommand of the RTK binary (rtk hook vibe); no separate script or plugin file is installed
• Vibe hook contract reference: https://docs.mistral.ai/vibe/code/cli/hooks

Overview (`hooks/windsurf/README.md`) Copy Section

Windsurf (Cascade) Hooks

Part of hooks/

Specifics Copy Chapter

• Prompt-level guidance only (no programmatic hook) -- relies on Windsurf Cascade reading rules files
• Installs ../rtk-awareness-full.md (shared, agent-neutral): the instruction to prefix every shell command with rtk, plus meta commands. No hook, so the full level is always used regardless of awareness.level
• Installed to .windsurfrules (project-local, workspace-scoped) by rtk init

Overview (`src/analytics/README.md`) Copy Section

Analytics

See also docs/contributing/TECHNICAL.md for the full architecture overview

Scope Copy Chapter

Read-only dashboards over the tracking database. Queries the recorded bash output reduction, correlates with external spending data, and surfaces adoption metrics. Never modifies the tracking DB.

Owns: rtk gain (savings dashboard), rtk cc-economics (cost reduction), rtk session (adoption analysis), and Claude Code usage data parsing.

Does not own: recording token savings (that's core/tracking called by cmds/), or command filtering itself (that's cmds/).

Boundary rule: if a new module writes to the DB, it belongs in core/ or cmds/, not here. Tool-specific analytics (like cc_economics reading Claude Code data) are fine — the boundary is "read-only presentation", not "tool-agnostic".

Purpose Copy Chapter

Bash output reduction analytics, economic modeling, and adoption metrics. The stored percentages measure output bytes; token counts are bytes / 4 estimates, not billed tokens.

These modules read from the SQLite tracking database to produce dashboards, spending estimates, and session-level adoption reports.

Adding New Functionality Copy Chapter

To add a new analytics view: (1) create a new *_cmd.rs file in this directory, (2) query core/tracking for the metrics you need using the existing TrackingDb API, (3) register the command in main.rs under the Commands enum, and (4) add #[cfg(test)] unit tests with sample tracking data. Analytics modules should be read-only against the tracking database and never modify it.

Overview (`src/cmds/README.md`) Copy Section

Command Filter Modules

Scope Copy Chapter

Command execution and output filtering. Every module here calls an external CLI tool (Command::new("some_tool")), transforms its stdout/stderr to reduce the bytes the agent reads, and records the reduction via core/tracking.

Owns: all command-specific filter logic, organized by ecosystem (git, rust, js, python, go, dotnet, cloud, system). Cross-ecosystem routing (e.g., lint_cmd detecting Python and delegating to ruff_cmd) is an intra-component concern.

Does not own: the TOML DSL filter engine (that's core/toml_filter), hook interception (that's hooks/), or analytics dashboards (that's analytics/). This component writes to the tracking DB; analytics reads from it.

Boundary rule: a module belongs here if and only if it executes an external command and filters its output. Infrastructure that serves multiple modules without calling external commands belongs in core/.

When to Write a Rust Module (vs TOML Filter) Copy Chapter

Rust modules exist here because they need capabilities TOML filters don't have: parsing structured output (JSON, NDJSON), state machine parsing across phases, injecting CLI flags (--format json), cross-command routing, or flag-aware filtering — detecting user-requested verbose flags (e.g., --nocapture) and adjusting compression accordingly (see Design Philosophy and TOML vs Rust decision table).

Ecosystem placement: Match the command's language/toolchain. Use system/ for language-agnostic commands. New ecosystem when 3+ related commands justify it.

For the full contribution checklist (including discover/rules.rs registration), see Adding a New Command Filter below.

Purpose Copy Chapter

All command-specific filter modules that execute CLI commands and transform their output to minimize LLM token consumption. Each module follows a consistent pattern: execute the underlying command, filter its output through specialized parsers, track token savings, and propagate exit codes.

Ecosystems Copy Chapter

Each subdirectory has its own README with file descriptions, parsing strategies, and cross-command dependencies.

• git/ — git, gh, gt, diff — trailing_var_arg parsing, gh markdown filtering, gt passthrough
• rust/ — cargo, runner (err/test) — Cargo sub-enum routing, runner dual-mode
• js/ — npm, pnpm, vitest, lint, tsc, next, prettier, playwright, prisma — Package manager auto-detection, lint routing, cross-deps with python
• python/ — ruff, pytest, mypy, pip — JSON check vs text format, state machine parsing, uv auto-detection
• go/ — go test/build/vet, golangci-lint — NDJSON streaming, Go sub-enum pattern
• dotnet/ — dotnet, binlog, trx, format_report — DotnetCommands sub-enum, internal helper modules
• cloud/ — aws, docker/kubectl, curl, wget, psql — Docker/Kubectl sub-enums, JSON forced output
• system/ — ls, tree, read, grep, find, wc, env, json, log, deps, summary, format, smart — format_cmd routing, filter levels, language detection
• ruby/ — rake/rails test, rspec, rubocop — JSON injection pattern, ruby_exec() bundle exec auto-detection

Execution Flow Copy Chapter

The shared wrappers in core/runner.rs encapsulate the execution skeleton. Modules build the Command (custom arg logic), then delegate to a runner entry point. All runners handle tracking, tee recovery, and exit code propagation automatically.

run_streaming()       Filter applied              tee_and_hint()
      |                (per-line or post-hoc)            |
      v                       |                          v
 +---------+  stdout  +-------+-------+  filtered  +-------+
 | Spawn   |--------->| filter        |----------->| Print |
 +---------+  stderr  +---------------+            +-------+
      |        (live)                                    |
      v                                                  v
 +----------+                                    +---------+
 | raw =    |                                    | Track   |
 | stdout + |                                    | savings |
 | stderr   |                                    +---------+
 +----------+                                          |
                                                       v
                                                 +-----------+
                                                 | Ok(code)  |
                                                 | returned  |
                                                 +-----------+

Filter modes Copy Section

All execution goes through core::stream::run_streaming() with one of four FilterMode variants. The runner entry points (run_filtered, run_streamed, run_passthrough) select the appropriate mode automatically — module authors don't interact with FilterMode directly.

When to use which Copy Section

Phases Copy Section

1. Spawn — run_streaming() starts the child process with piped stdout/stderr (or inherited TTY for Passthrough)
2. Filter — stdout is processed per the FilterMode; stderr is forwarded to the terminal in real time via a dedicated reader thread
3. Print — filtered output is written to stdout (live for Streaming, post-hoc for CaptureOnly/Buffered); if tee enabled, appends recovery hint on failure
4. Track — timer.track() records raw vs filtered for token savings
5. Exit code — returns Ok(exit_code) to caller; main.rs calls process::exit(code) once

RunOptions builder:

Example — filtered command (recommended):

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

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

Exit code handling is fully automatic when using run_filtered() — the wrapper extracts the exit code (including Unix signal handling via 128+signal), tracks savings, and returns Ok(exit_code). Module authors just return the result.

Streaming filters (line-by-line):

Use runner::run_streamed() when the command is long-running or produces unbounded output that should be filtered line-by-line. Three levels of abstraction, from simplest to most flexible:

Level 1: RegexBlockFilter — regex start pattern + indent continuation (3-5 lines)

For block-based errors where blocks start with a regex match and continue on indented lines. Handles skip prefixes, block counting, and summary automatically.

use crate::core::shell::display_args;
use crate::core::stream::{BlockStreamFilter, RegexBlockFilter};

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

    let filter = RegexBlockFilter::new("mycmd", r"^error\[")
        .skip_prefixes(&["warning:", "note:"]);

    runner::run_streamed(
        cmd, "mycmd", &display_args(args),
        Box::new(BlockStreamFilter::new(filter)),
        runner::RunOptions::with_tee("mycmd"),
    )
}

RegexBlockFilter provides: regex-based block start detection, indent-based continuation (space/tab), configurable line skipping via prefixes, and automatic summary ("mycmd: 3 blocks in output" or "mycmd: no errors found").

Level 2: BlockHandler trait — custom block detection with state tracking

When you need custom block start/continuation logic or stateful parsing beyond regex + indent. Implement the BlockHandler trait and wrap in BlockStreamFilter.

use crate::core::stream::{BlockHandler, BlockStreamFilter};

struct MyHandler { error_count: usize }

impl BlockHandler for MyHandler {
    fn should_skip(&mut self, line: &str) -> bool { line.is_empty() }
    fn is_block_start(&mut self, line: &str) -> bool {
        if line.starts_with("FAIL") { self.error_count += 1; true } else { false }
    }
    fn is_block_continuation(&mut self, line: &str, _block: &[String]) -> bool {
        line.starts_with("  ") || line.starts_with("at ")
    }
    fn format_summary(&self, _exit_code: i32, _raw: &str) -> Option<String> {
        Some(format!("{} failures\n", self.error_count))
    }
}

See cmds/rust/cargo_cmd.rs::CargoBuildHandler and cmds/js/tsc_cmd.rs::TscHandler for production examples.

Level 3: StreamFilter trait — full line-by-line control

When block-based parsing doesn't fit (e.g., state machines, multi-phase output, line transforms). Implement StreamFilter directly.

use crate::core::stream::StreamFilter;

struct MyFilter { state: State }

impl StreamFilter for MyFilter {
    fn feed_line(&mut self, line: &str) -> Option<String> {
        // Return Some(text) to emit, None to suppress
        if line.contains("error") { Some(format!("{}\n", line)) } else { None }
    }
    fn flush(&mut self) -> String { String::new() }
    fn on_exit(&mut self, exit_code: i32, raw: &str) -> Option<String> { None }
}

See cmds/rust/runner.rs::ErrorStreamFilter for a complete reference implementation (state machine that tracks error blocks across lines).

Example — passthrough command (no filtering):

pub fn run_passthrough(args: &[OsString], verbose: u8) -> Result<i32> {
    runner::run_passthrough("mycmd", args, verbose)
}

Example — manual execution (custom logic):

pub fn run(args: &[String], verbose: u8) -> Result<i32> {
    let output = resolved_command("mycmd").args(args)
        .output().context("Failed to run mycmd")?;
    let exit_code = exit_code_from_output(&output, "mycmd");
    // ... custom filtering, tracking ...
    Ok(exit_code)
}

Modules with deviations (subcommand dispatch, parser trait systems, two-command fallback, synthetic output).

Cross-Command Dependencies Copy Chapter

• lint_cmd routes to mypy_cmd or ruff_cmd when detecting Python projects
• format_cmd routes to prettier_cmd or ruff_cmd depending on the formatter detected
• gh_cmd imports compact_diff() from git for diff formatting (markdown helpers are defined in gh_cmd itself)

Cross-Cutting Behavior Contracts Copy Chapter

These behaviors must be uniform across all command modules. Full audit details in docs/ISO_ANALYZE.md.

Exit Code Propagation Copy Section

All module run() functions return Result where the i32 is the underlying command's exit code. main.rs calls std::process::exit(code) once at the single exit point — modules never call process::exit() directly.

How exit codes are extracted:

When using run_filtered(): exit code handling is fully automatic. The wrapper extracts the exit code, handles signals, and returns Ok(exit_code). Module authors just return the wrapper's result — no exit code logic needed.

When doing manual execution: use exit_code_from_output() or exit_code_from_status() and return Ok(exit_code). Never call process::exit(), never use .code().unwrap_or(1) (loses signal info).

Filter Failure Passthrough Copy Section

When filtering fails, fall back to raw output and warn on stderr. Never block the user.

Tee Recovery Copy Section

Modules that parse structured output (JSON, NDJSON, state machines) must call tee::tee_and_hint() so users can recover full output on failure.

Internal Truncation Recovery Copy Section

When a filter caps a list at N items (e.g. take(20)), the remaining items must be accessible via a tee hint. Never show "… +N more" without a recovery path — the agent has no way to retrieve the hidden content.

Choosing the right hint:

Cap values come from src/core/truncate.rs. Pick the CAP_* matching your data class (CAP_ERRORS, CAP_WARNINGS, CAP_LIST, CAP_INVENTORY) and bind it to a local const MAX_XXX: usize = CAP_Y;. Derive take(MAX_XXX), > MAX_XXX, and the offset MAX_XXX + 1 from the local. These CAPs will later become the configuration surface for per-filter cap tuning (user-overridable via config) — keep all truncation values routed through them so that hook lands as a single switch rather than a codebase-wide hunt. A filter that genuinely needs to deviate uses truncate::reduced(CAP_Y, n) (e.g. reduced(CAP_WARNINGS, 5)) so it still tracks the global when reconfigured — never a bare literal, never cap - n (underflows once caps are runtime-configurable), and never *// (those scale unboundedly). reduced falls back to the full cap if the reduction would empty the list. Each deviation needs a one-line comment stating why; if there's no real reason, just use the plain CAP. See src/core/README.md ("Truncation Caps") for the full rationale.

The stored content must match what was shown. For force_tee_tail_hint, build the recall blob from the same formatted values displayed — not raw/intermediate data — and pass the 1-based first-hidden line as offset. rtk recall <hash> slices the stored content from that offset, so the agent gets exactly the hidden items. If the filter reformats items before displaying them, pre-build a Vec<String> of formatted lines and use it for both the display loop and the recall blob.

Stderr Handling Copy Section

Modules must capture stderr and include it in the raw string passed to timer.track(), so token savings reflect total output.

Tracking Completeness Copy Section

All modules must call timer.track() on every path — success, failure, and fallback. Since modules return Ok(exit_code) instead of calling process::exit(), tracking always runs before the program exits.

Verbose Flag Copy Section

All modules accept verbose: u8. Use it to print debug info (command being run, savings %, filter tier). Do not accept and ignore it.

Adding a New Command Filter Copy Chapter

Adding a new filter or command requires changes in multiple places. For TOML-vs-Rust decision criteria, see CONTRIBUTING.md.

Rust module (structured output, flag injection, state machines) Copy Section

1. Create module in src/cmds/<ecosystem>/mycmd_cmd.rs:
   • Write the filter_mycmd() function (pure: &str -> String, no side effects)
   • Write pub fn run(...) -> Result using runner::run_filtered() — build the Command, choose RunOptions, delegate
   • Use RunOptions::stdout_only() when the filter parses structured stdout (JSON, NDJSON) — stderr would corrupt parsing
   • Use RunOptions::default() when filtering combined text output
   • Add .tee("label") when the filter parses structured output (enables raw output recovery on failure)
   • Exit codes: handled automatically by run_filtered() — just return its result
   • Truncation: if the filter caps any list at N items, emit force_tee_tail_hint (flat lists) or force_tee_hint (multi-line blocks) so the agent can recover hidden items — see Internal Truncation Recovery. Use a named constant for the cap; derive the offset from it (MAX_XXX + 1)
   • Arguments: if the filter inspects its args at all — which flags were passed, which are paths, what to inject or strip — classify them with arg_tokenizer, never a string scan. Write the takes_value predicate from the tool's own --help and check it against the real binary
2. Register module:
   • Add pub mod mycmd_cmd; to the ecosystem mod.rs, keeping the list alphabetical. Modules are listed explicitly rather than generated from the directory: rustfmt only follows literal mod items and cannot expand macros, so a generated list hides every file under src/cmds/ from cargo fmt — and therefore from CI's fmt gate. build.rs fails the build if a .rs file here is missing from its mod.rs, since an undeclared module is never compiled, linted, or tested.
   • Add variant to Commands enum in main.rs with #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
   • Add routing match arm in main.rs: Commands::Mycmd { args } => mycmd_cmd::run(&args, cli.verbose)?,
3. Add rewrite pattern — Entry in src/discover/rules.rs (PATTERNS + RULES arrays at matching index) so hooks auto-rewrite the command
4. Write tests — Real fixture, snapshot test, >= 20% reduction in bash output (measured with RTK's token estimator, see testing rules)
5. Update docs — Ecosystem README (CHANGELOG.md is auto-generated by release-please)

TOML filter (simple line-based filtering) Copy Section

1. Create filter in src/filters/
2. Add rewrite pattern in src/discover/rules.rs
3. Write tests and update docs

Overview (`src/core/README.md`) Copy Section

Core Infrastructure

See also docs/contributing/TECHNICAL.md for the full architecture overview

Scope Copy Chapter

Domain-agnostic building blocks with no knowledge of any specific command, hook, or agent. If a module references "git", "cargo", "claude", or any external tool by name, it does not belong here. Core is a leaf in the dependency graph — it is consumed by all other components but imports from none of them.

Owns: configuration loading, token tracking persistence, TOML filter engine, tee output recovery, display formatting, explicit shell/direct command construction, telemetry, and shared utilities.

Does not own: command-specific filtering logic (that's cmds/), hook lifecycle management (that's src/hooks/), or analytics dashboards (that's analytics/).

Purpose Copy Chapter

Core infrastructure shared by all RTK command modules. Every filter, tracker, and command handler depends on these modules. No inward dependencies — leaf in the dependency graph (no circular imports possible).

TOML Filter Pipeline Copy Chapter

The TOML DSL applies 8 stages in order:

1. strip_ansi: Remove ANSI escape codes if enabled
2. replace: Line-by-line regex substitutions (chainable, supports backreferences)
3. match_output: Short-circuit rules (if output matches pattern, return message; unless field prevents swallowing errors)
4. strip/keep_lines: Filter lines by regex (mutually exclusive)
5. truncate_lines_at: Truncate each line to N chars (unicode-safe)
6. head/tail_lines: Keep first N or last N lines (with omit message)
7. max_lines: Absolute line cap applied after head/tail
8. on_empty: Return message if result is empty after all stages

Three-tier filter lookup (first match wins):

1. .rtk/filters.toml (project-local, requires rtk trust)
2. ~/.config/rtk/filters.toml (user-global)
3. Built-in filters concatenated by build.rs at compile time

Source File Comment Stripping Copy Chapter

src/core/filter.rs is a separate engine from the TOML DSL: it filters source
files (used by rtk read) rather than command output. At -l minimal it
strips comments using the per-language delimiters in
Language::comment_patterns().

Python does not use that walk. It has no block comments — """ opens a
string, which may be a docstring or an ordinary value — so it gets a
string-aware path that removes # comments and leaves string contents alone.
Matching """ as a block delimiter misread both of these:

QUERY = """          # contains """ without starting with it
SELECT 1
"""

"""Module doc."""    # opens and closes on one line

Docstrings are kept at minimal. aggressive has no string awareness: it
keeps a line inside a string when that line looks like an import or a
signature.

Tracking Database Schema Copy Chapter

CREATE TABLE commands (
  id INTEGER PRIMARY KEY,
  timestamp TEXT,              -- UTC ISO8601
  original_cmd TEXT,           -- "ls -la"; words quoted only when needed: "grep 'a b' f"
  rtk_cmd TEXT,                -- "rtk ls", "rtk:toml make all", "rtk:passthrough git tag"
  project_path TEXT,           -- cwd (for project-scoped stats)
  input_tokens INTEGER,        -- estimated from raw output (bytes / 4, no tokenizer)
  output_tokens INTEGER,       -- estimated from filtered output (bytes / 4)
  saved_tokens INTEGER,        -- input - output
  savings_pct REAL,            -- (saved / input) * 100, i.e. reduction in bash output bytes
  exec_time_ms INTEGER         -- elapsed milliseconds
);

CREATE TABLE parse_failures (
  id INTEGER PRIMARY KEY,
  timestamp TEXT,
  raw_command TEXT,
  error_message TEXT,
  fallback_succeeded INTEGER   -- 1=yes, 0=no
);

Project-scoped queries use GLOB patterns (not LIKE) to avoid _/% wildcard issues in paths.

Config Sections Copy Chapter

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

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

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

[telemetry]
enabled = true

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

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

Shared Utilities (utils.rs) Copy Chapter

Key functions available to all command modules:

Argument Tokenizer (arg_tokenizer.rs) Copy Chapter

Shared classifier for an already----restored args slice (see args_utils::restore_double_dash) into flags, their values, and positionals. tokenize_grammar takes a takes_value(kind, name) predicate the caller supplies — the list of which flags take a value is per-tool, but the token-walking around it isn't. tokenize(args) is the structural-only entry point, for a caller asking which arguments are flags and where -- is; it assumes no flag takes a value, so anything reading a value or counting free positionals needs tokenize_grammar.

Use it for anything that decides what an argument is. A new command filter, a new flag on an existing one, or a fix to how one is detected goes through tokenize_grammar — not starts_with('-'), not args.iter().any(|a| a == "--flag"). Those miss exactly what this module exists for: a flag's own value (git log --grep -p searches for the string "-p"), an attached value (--flag=v, /bl:x), a short cluster (-rn), and everything past --. Every bug the migration fixed was one of those four.

Four rules, each of which cost a real bug before it was written down:

• One grammar per tool and subcommand. Never reuse a sibling's predicate wholesale because it looks close enough — -u means -p in git log but --include-untracked in git stash show, and -T is --initial-tab in grep but --type-not in rg. Transcribe from the tool's own --help and verify against the real binary; grep and rg share 13 of ~50 value-taking flags, so one merged table is wrong for both.
• Scope the lookup to the region the tool parses. Everything past -- is a pathspec or an argument forwarded to another program — before_dashdash gives the tool's own tokens. Dialect::Msbuild keeps classifying past the boundary (it forwards rather than ending option parsing), which makes this explicit slice mandatory there, not optional.
• Inject before the boundary. RTK's own flags go at injection_point, never appended: dotnet parks anything after -- in UnparsedTokens and git reads it as a pathspec, so an appended --verify-no-changes silently does nothing.
• Detect and act with one rule. Strip or inject using the detected token's source_index; re-matching the text lets the two disagree, which deleted a pathspec named --no-compact and swallowed a forwarded --write.

takes_value returns Option<ValueSpec>, not a bool: one table per tool, answering every question the tokenizer has about a flag's value rather than one predicate per question, which is how two lists start drifting apart.

• ValueSpec::value() — --flag=v or --flag v, and a literal -- is the boundary. The common case.
• ValueSpec::attached_only() — --flag=v only, the next argument is never the value (git's -M/-U/-C/-B take an optional attached number and nothing else).
• ValueSpec::solo_only() — a Short flag takes a separate value only when it is the whole argument: git log -n 2 does, git log -pn 2 does not. No meaning for a Long flag.
• .claiming_dash_dash() — lets a literal -- be this flag's value. A per-tool split, not per-flag: grep and rg let any value-taking flag swallow it, git and cargo reject it whichever flag is asking.

Dialects Copy Section

Everything that is not per-flag is per-tool, and stays a parameter: tokenize_grammar(args, takes_value, Dialect::Msbuild). Dialect is a Copy struct of five independent axes, because the tools measured want five different combinations of them:

Naming rule. A preset names a grammar family that several tools can share — a parser library, or a real convention — so its name answers "can my tool reuse this?". Dialect::CommonsCli is checkable (ls /usr/share/maven/lib/ ships commons-cli-1.11.0.jar); "is my tool Maven?" is not. A single tool's bespoke parser gets no preset: its caller composes the axes at its own call site. That rule is what stops this list growing one variant per tool.

• Dialect::Posix — git, cargo, rg, golangci-lint. Cluster, =, -- ends options, case-sensitive, no /flag.
• Dialect::Msbuild — dotnet. Atomic, = or :, -- forwards, case-folded, /flag.
• Dialect::CommonsCli — Apache commons-cli. POSIX with Atomic: the library's short options are whole multi-character words (-pl, -am, -gs, -emp), so mvn -Bo is an error, not a cluster. Maven is the first consumer.
• Dialect::GoFlag — Go's flag package: atomic single-dash options, and -run is the same flag as --run.

Gradle gets no preset: its parser is org.gradle.cli (gradle:jdk21 ships gradle-cli-*.jar and no commons-cli), used by nothing else. It is Posix with dash_dash: EndsGlobalOptions, composed as a const in gradlew_cmd.rs. The axis value is shared infrastructure; the one-tool combination is not.

src/core/arg_tokenizer/frozen.rs is the pre-axes implementation, kept as the oracle for the differential test in differential.rs: every arg vector up to four tokens over an alphabet covering each construct the scanner branches on, asserted token-for-token identical under Posix and Msbuild. Never edit frozen.rs to match new behaviour — a diff against it is the only proof the presets have not moved.

Consumer Contracts Copy Chapter

Core provides infrastructure that cmds/ and other components consume. These contracts define expected usage.

Command Construction (`shell`) Copy Section

Use shell::direct_command() when the caller already has an argv vector. It
preserves argument boundaries and never expands globs, variables, redirects,
or operators. Use shell::shell_command() only for an intentional command
string, with an explicit shell when syntax is shell-specific. The platform
default remains sh -c on Unix and cmd /C on Windows for compatibility.

Never infer the command parser from $SHELL: agent hosts and terminal wrappers
can execute a different shell while preserving the user's login-shell value.
Callers that accept --shell must require the complete script as one quoted
argument instead of reconstructing it by joining parsed argv.

Tracking (`TimedExecution`) Copy Section

Consumers must call timer.track() on all code paths — success, failure, and fallback. Calling std::process::exit() before track() loses metrics. The raw string passed to track() should include both stdout and stderr to produce accurate savings percentages.

Output recovery (`tee_and_hint` + recall store) Copy Section

Consumers that parse structured output (JSON, NDJSON, state machines) should call tee::tee_and_hint() to persist raw output for LLM recovery on failure. It must be called before std::process::exit().

For truncation recovery on success (e.g. a list capped at 20 items), use tee::force_tee_hint() (multi-line blocks) or tee::force_tee_tail_hint(content, slug, offset) (flat lists). All three persist the full output to the content-addressed recall store (retriever.rs) and emit a runnable hint — [full output: rtk recall <hash>] or [+N hidden: rtk recall <hash>] — instead of burning tokens working around missing data.

The agent runs rtk recall <hash> to get back exactly what was elided. For force_tee_tail_hint, offset is the 1-based first hidden line (header_lines + MAX_CAP + 1); it is stored so the default recall returns only the hidden tail. Storage is byte-faithful (BLOB + lossless gzip); tune limits via the [retriever] config section.

Truncation Caps (`truncate`) Copy Section

src/core/truncate.rs defines four global cap policies — CAP_ERRORS, CAP_WARNINGS, CAP_LIST, CAP_INVENTORY — for the data classes RTK filters truncate. Each filter binds the right CAP to a local const MAX_* so the cap is one named jump away from the call site. These CAPs are the staging point for filter-level cap configuration (planned, not yet implemented): once the config surface lands, overriding CAP_LIST in ~/.config/rtk/config.toml will tune every list filter in one place instead of editing 20+ files.

Config policy. Configured values are accepted as-is, including 0, which means "summary only" — the filter still prints the count and the [full output: …] recovery hint, just no individual items. Caps are never refused and rtk never aborts on them, in keeping with the never-block-the-user fallback philosophy.

Deviating from a cap. A filter whose items are unusually verbose (multi-line entries, backtraces) may show fewer than its class cap. Use truncate::reduced(cap, by) rather than a bare cap - by: reduced returns cap - by, except when the reduction would empty the list (by >= cap), in which case it drops the deviation and uses the full cap. This guarantees a deviation can never hide every item, and — crucially — stays a usize-underflow-safe const fn once caps become runtime-configurable (a bare CAP_WARNINGS - 5 would panic or wrap to "no truncation" if a user set CAP_WARNINGS below 5). Never deviate with a bare literal or with *// (those scale unboundedly). Each deviation needs a one-line comment stating why.

Adding New Functionality Copy Chapter

Place new infrastructure code here if it meets all of these criteria: (1) it has no dependencies on command modules or hooks, (2) it is used by two or more other modules, and (3) it provides a general-purpose utility rather than command-specific logic. Follow the existing pattern of lazy-initialized resources (LazyLock for regex, on-demand config loading) to preserve the <10ms startup target. Add #[cfg(test)] mod tests with unit tests in the same file.

Overview (`src/discover/README.md`) Copy Section

Discover — History Analysis & Command Rewrite

Full rewrite pipeline diagram: docs/contributing/TECHNICAL.md

What This Module Does Copy Chapter

This module has two jobs:

1. Rewrite commands — Every LLM agent hook calls rtk rewrite "git status". This module decides whether to rewrite it (rtk git status) or pass it through unchanged. This is the hot path — every command the LLM runs goes through here.

2. Analyze history — rtk discover scans past LLM sessions to find commands that could have been rewritten but weren't. Same classification logic, different consumer.

How Command Rewriting Works Copy Chapter

When a hook sends cargo fmt --all && cargo test 2>&1 | tail -20:

Tokenization — The lexer (lexer.rs) turns the raw string into typed tokens. It's a single-pass state machine that understands shell quoting, escapes, redirects, and operators. This is critical because naive string splitting breaks on quoted content like git commit -m "fix && update".

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

Compound splitting — The rewrite engine walks the tokens, splitting on Operator (&&, ||, ;, and the case terminators ;;, ;&, ;;&) and typed Pipe tokens (|, |&). For normal pipelines, intermediate stages stay raw. A final stage whose rule's pipeline_safety allows it (ordinary grep and rg invocations) is rewritten; search pattern-file forms (-f/--file) defer because they can consume pipeline stdin as configuration. The producer stage is rewritten when its rule's pipeline_safety allows it and every downstream stage is a display-only consumer (cat, head, non-following tail) with no file-target redirect (#3171). Stderr pipelines (|&) and pipelines containing opaque shell groups remain raw.

Quoted shell wrappers — An exact sh -c, bash -c, zsh -c or fish -c segment whose script is one balanced quoted argument has that script rewritten in place, leaving the shell path, quote delimiters, spacing, suffix arguments and redirects byte-identical (shell_wrapper.rs). Recursion is capped at one level, so a wrapper inside a wrapper stays raw. A script carrying a newline, heredoc, $((, or any construct the lexer cannot attest defers unchanged. The wrapper names the shell, so the script is attested under that shell's grammar (ShellDialect): inside fish -c, (cmd) is substitution and and/or/end are control flow, and either one defers — while the same shapes in a host command string or a POSIX wrapper stay ordinary bash and keep rewriting.

Per-segment rewriting — Each segment goes through:

1. Strip trailing redirects (2>&1, >/dev/null) — matched via lexer tokens, set aside, re-appended after rewriting
2. Short-circuit special cases — head -20 file → rtk read file --head-lines 20, tail -n 5 file → rtk read file --tail-lines 5. These can't go through generic prefix replacement because it would produce rtk read -20 file (wrong flag position)
3. Classify the command — strip env prefixes (FOO="bar baz"), normalize paths (/usr/bin/grep → grep), strip git global opts (git -C /tmp → git), then match against 60+ regex patterns from rules.rs
4. Apply the rewrite — find the matching rule, replace the command prefix with rtk <cmd>, re-prepend the env prefix, re-append the redirect suffix

Guards along the way:

• RTK_DISABLED=1 in the env prefix → skip rewrite
• gh with --json/--jq/--template → skip (structured output, rtk would corrupt it)
• cat with flags other than -n → skip (different semantics than rtk read)
• cat/head/tail with > or >> → skip (write operation, not a read)
• Command in hooks.exclude_commands config → skip

Result: rtk cargo fmt --all && rtk cargo test 2>&1 | tail -20. Bash handles the && and | at execution time — each rtk invocation is a separate process.

Shared Lexer Toolkit Copy Chapter

lexer.rs is layer 1 of RTK's command parsing (raw string → quote/operator-aware tokens and words) — layer 2, already-split argv → flags/values, is core/arg_tokenizer.rs. It's not private to this module: hooks/permissions.rs, hooks/mod.rs, and main.rs's rtk bypass all build on it instead of re-scanning commands themselves.

The permission gate, discover/analytics classification, and rewrite each segment compound commands (&&, ;, |, background &, subshells) slightly differently on purpose — the gate must never under-segment (a hidden command could evade a deny rule), while rewrite and analytics only need to reproduce or classify the command's actual shape. Don't reuse split_on_operators or rewrite_compound's segmenting for a permission/security decision; use split_for_permissions.

How History Analysis Works Copy Chapter

rtk discover reads Claude Code JSONL session files. Each file contains tool_use/tool_result pairs for every command the LLM ran. The module:

1. Extracts commands from the JSONL (via SessionProvider trait — currently only Claude Code)
2. Splits compound commands using the same lexer-based tokenization
3. Classifies each command against the same rules used for live rewriting
4. Aggregates results: which commands could have been rewritten, estimated token savings, adoption rate

The classification logic is shared between discover and rewrite — same patterns, same rules, different consumers.

Env Prefix Handling Copy Chapter

The ENV_PREFIX regex strips env variable assignments and env from the front of commands. sudo is deliberately not stripped, so sudo-prefixed commands stay unclassified and pass through unrewritten. It handles:

• Unquoted: FOO=bar
• Double-quoted with spaces: FOO="bar baz"
• Single-quoted: FOO='bar baz'
• Escaped quotes: FOO="he said \"hello\""
• Chained: A="x y" B=1 env git status

The prefix is stripped twice: once in classify_command() to match the underlying command against rules, and again in rewrite_segment() to extract it for re-prepending to the rewritten command.

Process Wrapper Handling Copy Chapter

A process wrapper runs another command without changing which command runs, so
the rewrite peels it, rewrites what it wraps, and re-prepends the wrapper text
byte for byte: timeout 300 cargo test becomes timeout 300 rtk cargo test.
PROCESS_WRAPPERS in registry.rs describes each wrapper's own arguments —
options that take a value, options that do not, values that may be attached to
their option, and any positional argument the wrapper consumes before the
command (timeout's duration).

Two rules keep the peeling honest. An option the table does not describe drops
the rewrite, because an unknown option may consume the following word and make
the wrong token look like the command. Shell syntax before the command (a
redirect, a subshell, a glob) does the same, because the wrapper's argv can no
longer be read off the token list.

stdbuf is deliberately not a wrapper here: it exists to make the wrapped
command emit output incrementally, and routing through rtk buffers that output
until the child exits, so rewriting it would remove the only reason to type it.
The permission gate still reads past it, and past a bare xargs, when it
matches deny and ask rules (matching_readings): recognising the command
behind a prefix and rewriting through it are separate decisions.

Wrapping also changes who receives a signal. timeout 300 rtk cargo test
signals rtk rather than cargo, so core::stream relays SIGINT/SIGTERM to the
child and lets the normal filter-and-print path finish. Without that relay a
killed run prints nothing at all, which is strictly worse than the unwrapped
command.

Adding a New Rewrite Rule Copy Chapter

Add an entry to rules.rs. Each rule has:

• pattern — regex that matches the command (used by RegexSet for fast matching)
• rtk_cmd — the RTK command it maps to (e.g., "rtk cargo")
• rewrite_prefixes — command prefixes to replace (e.g., &["cargo"])
• category, savings_pct — metadata for discover reports
• subcmd_savings, subcmd_status — per-subcommand overrides

No other files need to change. The registry compiles the patterns at first use via LazyLock.

Overview (`src/filters/README.md`) Copy Section

Built-in Filters

See also docs/contributing/TECHNICAL.md for the full architecture overview

Each .toml file in this directory defines one filter and its inline tests.
Files are concatenated alphabetically by build.rs into a single TOML blob embedded in the binary.

When to Use a TOML Filter Copy Chapter

TOML filters strip noise lines — they don't reformat output. The filtered result must still look like real command output (see Design Philosophy). For the full TOML-vs-Rust decision criteria, see CONTRIBUTING.md.

TOML works well for commands with predictable, line-by-line text output where regex filtering achieves 60%+ savings:

• Install/update logs (brew, composer, poetry) — strip Using ... / Already installed lines
• System monitoring (df, ps, systemctl) — keep essential rows, drop headers/decorations
• Simple linters (shellcheck, yamllint, hadolint) — strip context, keep findings
• Infra tools (terraform plan, helm, rsync) — strip progress, keep summary

For the full contribution checklist (including discover/rules.rs registration), see src/cmds/README.md — Adding a New Command Filter.

Adding a filter Copy Chapter

1. Copy any existing .toml file and rename it (e.g. my-tool.toml)
2. Update the three required fields: description, match_command, and at least one action field
3. Add [[tests.my-tool]] entries to verify the filter behaves correctly
4. Run cargo test — the build step validates TOML syntax and runs inline tests

File format Copy Chapter

[filters.my-tool]
description = "Short description of what this filter does"
match_command = "^my-tool\\b"          # regex matched against the full command string
strip_ansi = true                       # optional: strip ANSI escape codes first
strip_lines_matching = [               # optional: drop lines matching any of these regexes
  "^\\s*$",
  "^noise pattern",
]
max_lines = 40                          # optional: keep only the first N lines after filtering
on_empty = "my-tool: ok"               # optional: message to emit when output is empty after filtering

[[tests.my-tool]]
name = "descriptive test name"
input = "raw command output here"
expected = "expected filtered output"

Available filter fields Copy Chapter

Naming convention Copy Chapter

Use the command name as the filename: terraform-plan.toml, docker-inspect.toml, mix-compile.toml.
For commands with subcommands, prefer <cmd>-<subcommand>.toml over grouping multiple filters in one file.

Build and runtime pipeline Copy Chapter

How a .toml file goes from contributor → binary → filtered output.

flowchart TD
    A[["src/filters/my-tool.toml\n(new file)"]] --> B

    subgraph BUILD ["cargo build"]
        B["build.rs\n1. ls src/filters/*.toml\n2. sort alphabetically\n3. concat → BUILTIN_TOML"] --> C
        C{"TOML valid?\nDuplicate names?"} -->|"fail"| D[["Build fails\nerror points to bad file"]]
        C -->|"ok"| E[["OUT_DIR/builtin_filters.toml\n(generated)"]]
        E --> F["rustc embeds via include_str!"]
        F --> G[["rtk binary\nBUILTIN_TOML embedded"]]
    end

    subgraph TESTS ["cargo test"]
        H["test_builtin_filter_count\nassert_eq!(filters.len(), N)"] -->|"wrong count"| I[["FAIL"]]
        J["test_builtin_all_filters_present\nassert!(names.contains('my-tool'))"] -->|"name missing"| K[["FAIL"]]
        L["test_builtin_all_filters_have_inline_tests\nassert!(tested.contains(name))"] -->|"no tests"| M[["FAIL"]]
    end

    subgraph RUNTIME ["rtk my-tool args"]
        R["TomlFilterRegistry::load()\n1. .rtk/filters.toml\n2. ~/.config/rtk/filters.toml\n3. BUILTIN_TOML\n4. passthrough"] --> S
        S{"match_command\nmatches?"} -->|"no match"| T[["exec raw (passthrough)"]]
        S -->|"match"| U["exec command\ncapture stdout"]
        U --> V["8-stage pipeline\nstrip_ansi → replace → match_output\n→ strip/keep_lines → truncate\n→ tail_lines → max_lines → on_empty"]
        V --> W[["print filtered output + exit code"]]
    end

    G --> H & J & L & R

Filter lookup priority Copy Chapter

flowchart LR
    CMD["rtk my-tool args"] --> P1
    P1{"1. .rtk/filters.toml\n(project-local)"}
    P1 -->|"match"| WIN["apply filter"]
    P1 -->|"no match"| P2
    P2{"2. ~/.config/rtk/filters.toml\n(user-global)"}
    P2 -->|"match"| WIN
    P2 -->|"no match"| P3
    P3{"3. BUILTIN_TOML\n(binary)"}
    P3 -->|"match"| WIN
    P3 -->|"no match"| P4[["exec raw (passthrough)"]]

First match wins. A project filter with the same name as a built-in shadows the built-in and triggers a warning:

[rtk] warning: filter 'make' is shadowing a built-in filter

Custom filters and trust Copy Chapter

You can add your own filters in two places (both use the format above):

• Project-local — .rtk/filters.toml (committed with a repo, applies in that project)
• User-global — ~/.config/rtk/filters.toml (applies in every project)

Because a filter can rewrite or hide the command output an agent sees, custom filter files are not applied until you trust them. An untrusted (or edited) filter file is skipped silently on the command path — RTK never prints a warning around a rewritten command. You discover and enable untrusted filters through commands you run deliberately:

rtk trust       # lists each detected filter (labelled project/global) + a risk summary, then asks to confirm ([y/N], or --yes)
rtk untrust     # revokes trust

• Trust is recorded as a SHA-256 of the file's contents, so editing a trusted file requires re-running rtk trust — a content change invalidates trust.
• rtk init detects existing custom filters and lets you enable them — an interactive [y/N], or --trust-filters / --no-trust-filters for scripts. It stays silent for an empty template (comments only) and, when run non-interactively, leaves filters disabled.
• Built-in filters (this directory) are compiled into the binary and always trusted; only the on-disk project and user-global files are gated.

Honest limitation: this is consent + tamper-evidence, not a sandbox. An attacker who can write your filter file can usually also write the trust store (~/.local/share/rtk/trusted_filters.json) and bypass the gate. It defends the common case — a filter dropped in by a script, a dotfile sync, or an untrusted repo — not a same-user attacker who specifically targets RTK.

Overview (`src/hooks/README.md`) Copy Section

Hook System

See also docs/contributing/TECHNICAL.md for the full architecture overview | hooks/ for deployed hook artifacts

Scope Copy Chapter

The lifecycle management layer for LLM agent hooks: install, uninstall, verify integrity, audit usage, and manage trust. This component creates and maintains the hook artifacts that live in hooks/ (root), but does not execute rewrite logic itself — that lives in discover/registry.

Owns: rtk init installation flows (6 agents via AgentTarget enum, now including Mistral Vibe + 3 special modes: Gemini, Codex, OpenCode), SHA-256 integrity verification, hook version checking, audit log analysis, rtk rewrite CLI entry point, and TOML filter trust management.

Does not own: the deployed hook scripts themselves (that's hooks/), the rewrite pattern registry (that's discover/), or command filtering (that's cmds/).

Boundary notes:

• decision.rs is the single place RTK decides what a hook should do with a command — deny, defer, rewrite-and-allow, or rewrite-and-ask. All three entry points route through it: the in-process rtk hook <agent> hosts (hook_cmd.rs), the rtk rewrite subprocess path (rewrite_cmd.rs), and the rtk hook check diagnostic (main.rs). Add a gate there, not in a caller.
• rewrite_cmd.rs is a thin CLI bridge — it exists to serve hooks (hooks call rtk rewrite as a subprocess) and renders decision.rs's verdict as the exit codes those delegates branch on.
• trust.rs gates project-local TOML filter execution. It lives here because the trust workflow is tied to hook-installed filter discovery, not to the core filter engine.

Purpose Copy Chapter

LLM agent integration layer that installs, validates, and executes command-rewriting hooks for AI coding assistants. Hooks intercept raw CLI commands (e.g., git status) and rewrite them to RTK equivalents (e.g., rtk git status) so that LLM agents automatically benefit from token savings without explicit user configuration.

Installation Modes Copy Chapter

rtk init supports these installation flows:

Integrity Verification Copy Chapter

The integrity system prevents unauthorized hook modifications:

1. At install: integrity::store_hash() computes SHA-256 of the hook file, writes to ~/.claude/hooks/.rtk-hook.sha256 (read-only 0o444)
2. At runtime: integrity::runtime_check() re-computes hash and compares; blocks execution if tampered
3. On demand: rtk verify prints detailed verification status (PASS/FAIL/WARN/SKIP)

Five integrity states:

• Verified: Hash matches stored value
• Tampered: Hash mismatch (blocks execution)
• NoBaseline: Hook exists but no hash stored (old install)
• NotInstalled: No hook, no hash
• OrphanedHash: Hash file exists, hook missing

PatchMode Behavior Copy Chapter

Controls how rtk init modifies agent settings files:

Atomicity and Safety Copy Chapter

All file operations use atomic writes (tempfile + rename) to prevent corruption on crash. Settings files are backed up to .bak before modification. All operations are idempotent -- running rtk init multiple times is safe.

Permission Model Copy Chapter

RTK enforces a permission precedence that matches Claude Code's least-privilege default:

Deny > Defer > Ask > Allow (explicit) > Default (ask)

Rules are loaded from all Claude Code settings.json files (project + global, including .local variants). Only Bash(...) rules are extracted; other scopes (Read, Write) are ignored.

Quoted sh -c, bash -c, zsh -c and fish -c scripts add a
second command-parsing boundary. RTK checks deny rules against both the outer
wrapper and the parsed inner segments, including a wrapper behind a prefix the
rewrite strips (env bash -c '…', timeout 5 sh -c '…', a configured
transparent_prefixes entry — registry::shell_wrapper_positions). A shell
name that is merely an argument (grep -rn bash -c src) is not a wrapper. A
deny rule matching an inner segment yields Defer: RTK neither rewrites nor
decides, so the host sees the command exactly as typed.
A wrapper at the start of a segment is never auto-allowed: its strongest RTK
verdict is Ask. A wrapper behind a prefix is only checked for deny rules and
otherwise keeps the outer command's verdict, as on master. Ask-capable hosts
prompt, while other hosts retain their existing native permission flow.
Unsupported or ambiguous wrapper syntax is left unchanged for the host to
evaluate. Line continuations are joined before the check, as the rewrite joins
them.

A deny or ask rule is matched against each segment as written, without the grammar a split leaves ({, !, (), and past each leading assignment or wrapper in turn (registry::matching_readings): env HUSKY=0 git push is read as HUSKY=0 git push and as git push, as Claude Code reads it. A reading need not be what the shell runs (nohup HUSKY=0 git push makes nohup look for a program named HUSKY=0), so it can only make a verdict stricter. Past 32 prefixes the command behind them is unread, and where a deny or ask rule exists the verdict is at least Ask. An allow rule matches the segment as written only, so a wrapper never inherits the allow of the command it runs.

A delegate that shells out to rtk rewrite and applies its own exec policy to
the result can set RTK_REWRITE_HOST=<agent> on that subprocess. For an agent
whose AgentPath records it as owning approval — OpenClaw is the only one —
Default renders as exit 0 instead of 3, because a Default verdict means no
rule matched and RTK asking as well would be a second gate sourced from Claude
Code's settings the runtime never opted into (#3908). An explicit Ask rule is
the user's own instruction, so it still renders as exit 3 and the host still
prompts. The verdict source is unchanged, and Deny still renders as exit 2 for
every delegate, so naming a host can never relax an explicit deny or discard an
explicit ask. An unknown or unset value keeps the table above — and a caller
that does not own approval should scrub the variable before invoking rtk rewrite, since it is inherited by every child process. See decision.rs's
ApprovalOwner.

Per-tool support Copy Section

Implementation Copy Section

• permissions.rs — loads deny/ask/allow rules, evaluates precedence, returns PermissionVerdict
• rewrite_cmd.rs — maps verdict to exit code (consumed by shell hook)
• hook_cmd.rs — maps decisions to each agent's JSON protocol, including Codex updatedInput
• discover/shell_wrapper.rs — shares conservative script-span parsing between rewrite and permission checks

Exit Code Contract Copy Chapter

Hook processors in hook_cmd.rs must return Ok(()) on every path — success, no-match, parse error, and unexpected input. Returning Err propagates to main() and exits non-zero, which blocks the agent's command from executing. This violates the non-blocking guarantee documented in hooks/README.md.

Adding New Functionality Copy Chapter

To add support for a new AI coding agent: (1) add the hook installation logic to src/hooks/init/ following the existing agent patterns, (2) if the agent requires a custom hook protocol (like Gemini's BeforeTool or Vibe's pre_tool), add a processor function in hook_cmd.rs and a matching HookCommands::<Agent> variant + AgentTarget::<Agent> enum entry in main.rs, (3) if the agent has installable permission surfaces (denylist / allowlist), wire them into permissions.rs::check_command_for via a new Host::<Agent> variant, and (4) update integrity.rs with the expected hash for the new hook file. Note that hook_check.rs::maybe_warn() only checks the Claude Code hook — other agents don't have an outdated-hook warning path. Test by running rtk init in a fresh environment and verifying the hook rewrites commands correctly in the target agent.

Overview (`src/learn/README.md`) Copy Section

Learn — CLI Correction Detection

See also docs/contributing/TECHNICAL.md for the full architecture overview

Purpose Copy Chapter

Analyzes Claude Code session history to detect recurring CLI mistakes — commands that fail then get corrected by the agent. Powers the rtk learn command, which identifies error patterns (unknown flags, wrong paths, missing args) and can auto-generate .claude/rules/cli-corrections.md to prevent them.

Key Types Copy Chapter

• ErrorType — UnknownFlag, CommandNotFound, WrongSyntax, WrongPath, MissingArg, PermissionDenied, Other(String)
• CorrectionPair — Raw detection: wrong command + right command + error output + confidence score
• CorrectionRule — Deduplicated pattern: wrong pattern + right pattern + occurrence count + base command

Dependencies Copy Chapter

• Uses: discover::provider::ClaudeProvider (session file discovery and command extraction), LazyLock/regex (error pattern matching), serde_json (JSON output)
• Used by: src/main.rs (routes rtk learn command)

Detection Algorithm Copy Chapter

1. Extract all commands from JSONL sessions via ClaudeProvider
2. Scan chronologically for fail-then-succeed pairs (same base command, first has error output, second succeeds)
3. Classify the error type using regex patterns on the error output
4. Assign confidence scores based on similarity and error clarity
5. Deduplicate into rules (merge identical wrong->right patterns, count occurrences)
6. Filter by --min-confidence and --min-occurrences thresholds

Overview (`src/parser/README.md`) Copy Section

Parser Infrastructure

See also docs/contributing/TECHNICAL.md for the full architecture overview

Overview Copy Chapter

The parser infrastructure provides a unified, three-tier parsing system for tool outputs with graceful degradation:

• Tier 1 (Full): Complete JSON parsing with all structured data
• Tier 2 (Degraded): Partial parsing with warnings (fallback regex)
• Tier 3 (Passthrough): Raw output truncation with error markers

Architecture Copy Chapter

┌─────────────────────────────────────────────────────────┐
│                    ToolCommand Builder                   │
│  Command::new("vitest").arg("--reporter=json")          │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                   OutputParser<T> Trait                  │
│  parse() → ParseResult<T>                               │
│    ├─ Full(T)           - Tier 1: Complete JSON parse   │
│    ├─ Degraded(T, warn) - Tier 2: Partial with warnings │
│    └─ Passthrough(str)  - Tier 3: Truncated raw output  │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Canonical Types                         │
│  TestResult, LintResult, DependencyState, BuildOutput   │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  TokenFormatter Trait                    │
│  format_compact() / format_verbose() / format_ultra()   │
└─────────────────────────────────────────────────────────┘

Usage Pattern Copy Chapter

1. Implement OutputParser for a tool — try JSON (Tier 1), fall back to regex (Tier 2), then passthrough (Tier 3)
2. In command module: call Parser::parse(), then data.format(FormatMode::from_verbosity(verbose))
3. Degradation warnings: print [RTK:DEGRADED] in verbose mode, [RTK:PASSTHROUGH] on full fallback

See src/parser/types.rs for the OutputParser trait and ParseResult enum.

Canonical Types Copy Chapter

TestResult Copy Section

For test runners (vitest, playwright, jest, etc.)

• Fields: total, passed, failed, skipped, duration_ms, failures
• Formatter: Shows summary + failure details (compact: top 5, verbose: all)

LintResult Copy Section

For linters (eslint, biome, tsc, etc.)

• Fields: total_files, files_with_issues, total_issues, errors, warnings, issues
• Formatter: Groups by rule_id, shows top violations

DependencyState Copy Section

For package managers (pnpm, npm, cargo, etc.)

• Fields: total_packages, outdated_count, dependencies
• Formatter: Shows upgrade paths (current → latest)

BuildOutput Copy Section

For build tools (next, webpack, vite, cargo, etc.)

• Fields: success, duration_ms, bundles, routes, warnings, errors
• Formatter: Shows bundle sizes, route metrics

Format Modes Copy Chapter

Compact (default, verbosity=0) Copy Section

• Summary only
• Top 5-10 items
• Token-optimized

Verbose (verbosity=1) Copy Section

• Full details
• All items (up to 20)
• Human-readable

Ultra (verbosity=2+) Copy Section

• Symbols: ✓✗⚠ pkg: ^
• Ultra-compressed
• 30-50% token reduction

Error Handling Copy Chapter

ParseError Types Copy Section

• JsonError: Line/column context for debugging
• PatternMismatch: Regex pattern failed
• PartialParse: Some fields missing
• InvalidFormat: Unexpected structure
• MissingField: Required field absent
• VersionMismatch: Tool version incompatible
• EmptyOutput: No data to parse

Degradation Warnings Copy Section

[RTK:DEGRADED] vitest parser: JSON parse failed at line 42, using regex fallback
[RTK:PASSTHROUGH] playwright parser: Pattern mismatch, showing truncated output

Migration Guide Copy Chapter

Existing Module → Parser Trait Copy Section

Replace direct filter_*_output() calls with Parser::parse() + FormatMode. Key change: add --reporter=json flag injection, match on ParseResult (Full/Degraded/Passthrough), format with data.format(mode). Degraded and Passthrough tiers handle tool version changes gracefully.

Testing Copy Chapter

Run cargo test parser::tests. Each parser should have tier validation tests: assert result.tier() == 1 for valid JSON fixtures, tier() == 2 for regex fallback inputs, and tier() == 3 for completely malformed output.

Benefits Copy Chapter

1. Maintenance: Tool version changes break gracefully (Tier 2/3 fallback)
2. Reliability: Never silent failures or false data
3. Observability: Clear degradation markers in verbose mode
4. Token Efficiency: Structured data enables better compression
5. Consistency: Unified interface across all tool types
6. Testing: Fixture-based regression tests for multiple versions

Roadmap Copy Chapter

Phase 4: Module Migration Copy Section

• vitest_cmd.rs → VitestParser
• playwright_cmd.rs → PlaywrightParser
• pnpm_cmd.rs → PnpmParser (list, outdated)
• lint_cmd.rs → EslintParser
• tsc_cmd.rs → TscParser
• gh_cmd.rs → GhParser

Phase 5: Observability Copy Section

• Extend tracking.db: parse_tier, format_mode
• rtk parse-health command
• Alert if degradation > 10%

Overview (`src/cmds/cloud/README.md`) Copy Section

Cloud and Infrastructure

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• aws_cmd.rs — 25 specialized filters covering STS, S3, EC2, ECS, RDS, CloudFormation, CloudWatch Logs, Lambda, IAM, DynamoDB, EKS, SQS, Secrets Manager. Forces --output json for structured parsing, uses force_tee_hint() for truncation recovery, strips Lambda secrets. Shared runner run_aws_filtered() handles boilerplate for JSON-based filters; text-based filters (S3 ls, S3 sync/cp) have dedicated runners
• container.rs handles Docker, Kubernetes, and OpenShift; DockerCommands, KubectlCommands, and OcCommands sub-enums in main.rs route to container::run() -- uses passthrough for unknown subcommands
• curl_cmd.rs truncates long responses, saves full output to file for recovery
• wget_cmd.rs wraps wget with output filtering
• psql_cmd.rs filters PostgreSQL query output

Overview (`src/cmds/dotnet/README.md`) Copy Section

.NET Ecosystem

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• dotnet_cmd.rs uses DotnetCommands sub-enum in main.rs
• Internal helper modules (dotnet_trx.rs, dotnet_format_report.rs, binlog.rs) are only used by dotnet_cmd.rs -- they parse specialized .NET output formats (TRX XML, binary logs, format reports)
• Test fixtures are in tests/fixtures/dotnet/ (JSON and text formats)

Overview (`src/cmds/git/README.md`) Copy Section

Git and VCS

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• git_cmd.rs uses trailing_var_arg = true + allow_hyphen_values = true so native git flags (--oneline, --cached, etc.) pass through correctly
• Flag grammar (which flags take a value, what -u/-p mean) is per-subcommand, not shared wholesale between log/diff/show/stash show — see src/core/README.md
• Default git status uses --porcelain -b so the compact output never exceeds raw git status (an untracked directory collapses to a single line, matching git's default); branch/short-only flags reuse the compact path, other explicit args still pass through unchanged
• Global git options (-C, --git-dir, --work-tree, --no-pager) are prepended before the subcommand
• Exit code propagation is critical for CI/CD pipelines
• glab_cmd.rs declares -R/--repo and -g/--group at the clap level; they are appended to the glab args (not prepended) so subcommand dispatch stays intact
• has_output_flag() short-circuits to passthrough when the user explicitly requests -F / --output / --json (avoids double JSON injection)
• should_passthrough_view() redirects mr/issue view to passthrough when --web or --comments is set
• JSON handlers use the local run_glab_json<F>() helper wrapping runner::run_filtered + RunOptions::stdout_only().early_exit_on_failure().no_trailing_newline(); on JSON parse error, falls back to the raw stdout (glab sometimes emits plain text for empty results)
• ci status uses text-keyword parsing (glab doesn't support -F json for this subcommand); when no English status keyword is recognized (non-English locale), returns raw verbatim
• ci trace uses ANSI-stripping + GitLab section-marker filtering + runner/git/artifact boilerplate removal; kept as text-only filter, not JSON
• release list falls back to raw output when the glab 1.82+ format doesn't match the legacy tab-delimited parser
• Pipeline / merge-status indicators use text tags ([ok], [fail], [cancel], [run], [pend], [skip], [conflict]) to match gh_cmd.rs and avoid multi-byte rendering quirks

Cross-command Copy Chapter

• gh_cmd.rs imports compact_diff() from git_cmd.rs for diff formatting; markdown helpers (filter_markdown_body, filter_markdown_segment) are defined in gh_cmd.rs itself
• glab_cmd.rs also uses compact_diff() from git_cmd.rs for mr diff; its filter_markdown_body is currently duplicated from gh_cmd.rs (shared-module refactor deferred)
• diff_cmd.rs is a standalone ultra-condensed diff (separate from git diff)

glab vs gh JSON schema quick-ref Copy Chapter

Overview (`src/cmds/go/README.md`) Copy Section

Go Ecosystem

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• go_cmd.rs uses GoCommands sub-enum in main.rs (same pattern as git/cargo)
• go test outputs NDJSON (-json flag injected by RTK) -- parsed line-by-line as streaming events
• golangci_cmd.rs forces --out-format=json for structured parsing

Overview (`src/cmds/js/README.md`) Copy Section

JavaScript / TypeScript / Node

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• utils::package_manager_exec() auto-detects pnpm/yarn/npm -- JS modules should use this instead of hardcoding a package manager
• lint_cmd.rs is a cross-ecosystem router: detects Python projects and delegates to mypy_cmd or ruff_cmd
• vitest_cmd.rs uses the parser/ module for structured output parsing
• playwright_cmd.rs uses the parser/ module for test result extraction

Cross-command Copy Chapter

• lint_cmd routes to cmds/python/mypy_cmd and cmds/python/ruff_cmd for Python projects
• prettier_cmd is also called by cmds/system/format_cmd as a format dispatcher target

Overview (`src/cmds/jvm/README.md`) Copy Section

JVM ecosystem filters

Filters for JVM-based build tools.

Maven (`mvn_cmd.rs`) Copy Chapter

Phase routing (detect_phase):

Key behaviours:

• ANSI strip first in every filter — real Maven output contains colour escapes.

• English-footer guard — if neither BUILD SUCCESS nor BUILD FAILURE appears as a trimmed line suffix, return the ANSI-stripped raw input unchanged. Protects non-English locales.

• Verbose bypass — -X, --debug, -e, --errors skip filtering (run_passthrough). User asked for detail; respect it.

• Surefire block collapse — Surefire emits [INFO] Running <FQN> … [INFO] Tests run: N, Failures: F, Errors: E, …, Time elapsed: T s - in <FQN>. The filter buffers each block and emits it only when F > 0 or E > 0. Passing blocks (the bulk of healthy-project output) are dropped silently. Failing blocks are emitted with framework stack frames stripped via a deny-list (at org.junit., at java.util., at sun.reflect., etc.).

• Multi-failure classes (trail re-arm) — when a single class has several failing tests, Surefire 3.x emits one blank-separated detail block per failing test under a single close line. When a failure trail ends at a blank line, the state machine arms a re-entry: the next per-test subline ([ERROR] FQN.method -- Time elapsed: … <<< FAILURE! or <<< ERROR!) re-enters the trail with the same keep/drop decision, so every failure message survives (and a capped class drops all its blocks). Any other non-blank line disarms the re-entry.

• <<< ERROR! markers — per-test sublines use <<< ERROR! for thrown (non-assertion) exceptions; the close-line regex also tolerates an ERROR! marker defensively (Surefire 3.5.5 emits FAILURE! even for errors-only classes — failure detection keys off the Failures/Errors counts, not the marker).

• Help-boilerplate stripping (all modes) — the post-failure block Maven emits after [ERROR] Failed to execute goal (See …, -> [Help 1], Re-run Maven, To see the full stack trace, For more information, help URLs, bare [ERROR] dividers) is dropped in quiet and non-quiet filters alike (shared BOILER_PREFIXES). Deliberately kept as signal: Failed to execute goal itself and the multi-module resume hint ([ERROR] After correcting the problems… + [ERROR] mvn <args> -rf :module — tells the user/agent how to resume the build). Real durations (Time elapsed: … s, Total time: …) ship untouched — the numbers are diagnostic signal.

• Wrapper detection — ./mvnw (POSIX) and mvnw.cmd (Windows) detected via string-literal Command::new (semgrep-safe); falls back to resolved_command("mvn").

• Maven Daemon (rtk mvnd) — mvnd is a separate entry point (run_daemon), not a mvn alias: it shares phase detection and every filter, but always executes mvnd and is never substituted by a ./mvnw wrapper found in the working directory. The daemon's rolling console UI only engages on a TTY, so what rtk captures is ordinary Maven log output and the existing filters apply unchanged. Two daemon-specific quirks are handled explicitly:

  • [INFO]-prefixed blanks — the daemon logger prefixes even empty lines with [INFO] , so the Surefire failure trail's blank-line terminator uses is_blank_separator (a bare [INFO] counts as blank). Without it the trail never closes and everything after the last failing class passes through verbatim.
  • Parallel-reactor lanes — mvnd builds multi-module reactors in parallel by default and prefixes per-module lines with [module] , interleaved line-by-line. split_lane classifies on the prefix-stripped view while emitting the original (module identity survives), and each module gets its own SurefireLane (block machine + compile-continuation flag + summary-open flag) so a passing close from one module can't be attributed to another's open block. Three consequences of the interleaving are handled explicitly: unprefixed raw lines (stack traces, javac symbol: / location: continuations) go to the lane in an active failure trail before any lane merely holding an open block (raw_owner) — otherwise a module opening a block between a failing close and its exception swallows the diagnostics and drops them when it closes green — and when ownership is genuinely ambiguous (several plain blocks open, no trail) the line is preserved verbatim rather than routed to a guess. The [ERROR] Failures: budget stays reactor-wide (FailuresSummaryCap, reset only when a header opens the first summary), so interleaved per-module summaries share one cap instead of each getting MAX_MVN_FAILING_CLASSES.

  One known limit remains, not a regression — it already applies to mvn -T: daemon status chatter (Connecting to the daemon, …) carries no [INFO]/[ERROR] prefix, so the keep-list filters (filter_surefire, filter_compile, filter_package) drop it — but filter_quiet has no keep-list, only a deliberate "keep anything else" safety net, so rtk mvnd -q passes that chatter through where rtk mvn -q emits nothing.

• Reactor Summary preservation — for multi-module builds, the trailing Reactor Summary for <root> block with per-module SUCCESS/FAILURE rows is kept (toggled by a [INFO] Reactor Summary for header and cleared on BUILD SUCCESS / BUILD FAILURE).

• Failure cap — both the count of emitted failing test classes and the size of the [ERROR] Failures: summary block are bounded by MAX_MVN_FAILING_CLASSES = CAP_WARNINGS (the shared test-failure cap class from src/core/truncate.rs, same binding as pytest/rspec/rake/runner). Excess emissions are replaced by a single … +N more failing test classes / … +N more failures tail (canonical join_with_overflow shape) to keep large failure sets compact; the raw output stays recoverable via the tee [full output: …] hint. Per the core cap policy, a cap of 0 means summary-only: no blocks emitted, the tail still counts every dropped class.

Token-savings tests run inline as part of cargo test --all. The mvn fixtures (gzipped, ~1100 lines each; flate2, already in Cargo.toml, decompresses the ~3 KB gzipped fixtures in milliseconds) verify ≥90% savings for mvn test and ≥85% for mvn install. The mvnd fixtures are smaller synthetic captures and are held to the repo-wide ≥60% savings floor instead (mvnd_reactor_pass_savings, mvnd_test_fail_savings, mvnd_parallel_reactor_fail_savings, mvnd_compile_error_savings; actuals run 64.9–76.5%).

Integrity-check whitelist Copy Section

Commands::Aws, Commands::Psql, Commands::Wc, Commands::Mypy, Commands::Gradlew, Commands::Mvn, and Commands::Mvnd are included in is_operational_command in src/lib.rs because hook rewrites invoke them as RTK subcommands. The whitelist is intentionally opt-in: a newly added rewritten command must be listed or it will not receive the runtime SHA-256 hook-integrity check.

Gradle (`gradlew_cmd.rs`) Copy Chapter

See module docs and the gradle PR (feat/gradlew-android-support) for rationale. Streaming filter chosen because Gradle output is task-line-based, not block-based — unlike Maven Surefire.

Overview (`src/cmds/php/README.md`) Copy Section

PHP

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• php_cmd.rs summarizes php -l syntax checks and routes php artisan* to specialized helpers
• artisan_cmd.rs cleans Artisan output and applies runner-aware filtering for php artisan test
• phpunit_cmd.rs strips progress/header noise and keeps failure details + final summary
• phpstan_cmd.rs injects JSON output by default and emits compact file/line error summaries
• ecs_cmd.rs condenses EasyCodingStandard output while preserving file paths and error lines
• pest_cmd.rs runs Pest with compact progress suppression and test-focused output
• paratest_cmd.rs runs ParaTest with compact progress suppression and test-focused output
• test_output.rs provides shared PHPUnit/Pest/ParaTest output filtering logic
• utils.rs resolves local vendor/bin/* tools first, then falls back to global binaries

Overview (`src/cmds/python/README.md`) Copy Section

Python Ecosystem

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• pytest_cmd.rs uses a state machine text parser (no JSON available from pytest)
• ruff_cmd.rs uses JSON for check mode (--output-format=json) and text filtering for format mode
• sqlfluff_cmd.rs injects --format json for lint mode and groups violations by rule and file; other subcommands pass through capped
• Ruff and SQLFluff list identical descriptions once beside a visible top rule.
  Locations retain the rule code; differing messages and rules outside the
  summary cap keep their descriptions beside each location.
• pip_cmd.rs auto-detects uv as a pip alternative and routes accordingly
• uv_cmd.rs preserves uv run environment semantics: the program's own output passes through on success (bounded, with a tee hint), diagnostics are extracted on failure
• python -m pytest and python3 -m mypy are rewritten by the hook registry to rtk pytest / rtk mypy

Cross-command Copy Chapter

• ruff_cmd is called by cmds/js/lint_cmd and cmds/system/format_cmd for Python projects
• mypy_cmd is called by cmds/js/lint_cmd when detecting Python type checking

Overview (`src/cmds/ruby/README.md`) Copy Section

Ruby on Rails

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• rake_cmd.rs filters Minitest output via rake test / rails test; state machine text parser, failures only (85-90% reduction)
• rspec_cmd.rs uses JSON injection (--format json) with text fallback; failures only (60%+ reduction)
• rubocop_cmd.rs uses JSON injection, groups by cop/severity (60%+ reduction)
• All three modules use ruby_exec() from utils.rs to auto-detect bundle exec when a Gemfile exists
• TOML filter bundle-install.toml strips Using lines from bundle install/update (90%+ reduction)

Overview (`src/cmds/rust/README.md`) Copy Section

Rust Ecosystem

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• cargo_cmd.rs uses restore_double_dash() fix: Clap strips -- but cargo needs it for test flags (e.g., cargo test -- --nocapture)
• runner.rs is a generic two-mode runner (err = stderr only, test = failures only) used as fallback for commands without a dedicated filter. It executes argv directly by default; --shell <name> '<script>' is the explicit escape hatch for shell syntax.
• runner.rs is also referenced by other modules outside this directory as a generic command executor

Overview (`src/cmds/system/README.md`) Copy Section

System and Generic Utilities

Part of src/cmds/ — see also docs/contributing/TECHNICAL.md

Specifics Copy Chapter

• read.rs uses core/filter for language-aware code stripping (FilterLevel: none/minimal/aggressive)
• search.rs backs both rtk grep and rtk rg: it runs the invoked engine (never substituting one for the other) and groups its output, reading core/config for limits.grep_max_results and limits.grep_max_per_file. Format-altering flags (-c, -l, -L, -o, -Z) bypass RTK filtering and run raw, except a bare file list (-l, -L, --files with no other shape flag), whose shared directory prefix is folded into a (N files) header under the never_worse guard.
• ctest_cmd.rs takes the run total from the first result line (covering --stop-on-failure, disabled tests, and forwarded suites) and validates both result lines and the summary against it, deduplicates retries by test number+name, folds wrapped result lines until their terminator, falls back to the raw FAILED: trailer for unparsed failures, keeps the error trailer behind an empty run, labels and caps failure details with tee recovery, and attributes diagnostics safely under -j; explicit verbose/show-only/help/version flags and dashboard modes bypass filtering, except -T Test, which prints ordinary test output and stays filtered.
• local_llm.rs (rtk smart) uses core/filter for heuristic file summarization
• format_cmd.rs is a cross-ecosystem dispatcher: auto-detects and routes to prettier_cmd or ruff_cmd (black is handled inline, not as a separate module)
• summary.rs executes argv directly before summarizing output. Shell-specific syntax requires --shell <name> '<script>'; it never guesses from $SHELL.

Cross-command Copy Chapter

• format_cmd routes to cmds/js/prettier_cmd and cmds/python/ruff_cmd

Guide Index (`docs/guide/index.md`) Copy Section

title: RTK Documentation sidebar: order: 1 Copy Chapter

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: fewer bash output bytes reaching the LLM 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 Copy Chapter

Your AI assistant runs:  git status
                              ↓
              Hook intercepts (PreToolUse)
                              ↓
              rtk git status  (transparent rewrite)
                              ↓
     Raw output: 40 lines     →     Filtered: 3 lines
                              ↓
              LLM sees the compact output

Zero config changes to your workflow. The hook handles everything automatically.

What the savings mean Copy Chapter

RTK reduces bash output bytes — the output a shell command sends back before your agent reads it. That is not the same as reducing your bill by the same amount.

Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. The reduction dilutes at every step.

See How RTK Savings Work for the full picture, including why the token counts RTK reports are estimates.

What RTK optimizes Copy Chapter

Dozens of commands across all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See What RTK Optimizes for the full list.

Get started Copy Chapter

1. Installation — Install RTK and verify you have the right package
2. Quick Start — Connect to your AI assistant in 5 minutes
3. Supported Agents — Claude Code, Cursor, Copilot, Gemini, and more

Measure your savings Copy Chapter

rtk gain           # total savings across all sessions
rtk gain --daily   # day-by-day breakdown
rtk gain --weekly  # weekly aggregation

See Token Savings Analytics for export formats and analysis workflows.

Analyze your usage Copy Chapter

rtk discover       # find commands that ran without RTK (missed savings)
rtk session        # RTK adoption rate per Claude Code session

See Discover and Session for details.

Go further Copy Chapter

Two optional layers sit on top of the hooks. Neither changes anything until you opt in.

• The engine — everything RTK does is expressed in one composable pipeline.toml: which commands get rewritten, what happens to a tool's output, what the proxy compresses. With no pipeline file you are on rtk:default and nothing changes. Start with Writing a Pipeline; Conditions and Judges and Methods are the vocabulary, Pipeline Commands is for inspecting, debugging and sharing one.
• The RTK Proxy — a local daemon that runs the pipeline on the API traffic itself, one layer above bash output. Ships as its own download. See What the Proxy Compresses and Proxy Configuration.

Further reading Copy Chapter

• Configuration — config.toml, global flags, env vars, recall recovery
• Troubleshooting — common issues and fixes
• Telemetry & Privacy — what RTK collects and how to opt out
• Agent Coverage — what each agent's hook API lets RTK do
• Editions and Licensing — the three downloads, what each contains, where the licence boundary falls
• ARCHITECTURE.md — system design for contributors

Guide Pipelines Overview (`docs/guide/pipelines/overview.md`) Copy Section

title: Pipelines sidebar: order: 1 Copy Chapter

The RTK pipeline

RTK saves tokens by intercepting what your coding agent reads and sends. In v1.0 what it does is a pipeline: a file that says when RTK acts, on what, and what it does. Every built-in behaviour is written in that same grammar, so you can read it (rtk pipeline show rtk:default), change one line of it, or replace it.

The file is agent-agnostic. You write shell, read, before_tool; RTK translates to Claude Code, Cursor, Gemini CLI or whatever you set up with rtk init. A pipeline written on one machine works on another.

:::note[Full edition only]
The pipeline engine is absent from the Apache-2.0 edition. See Editions and Licensing.
:::

What it provides Copy Chapter

RTK can act in two places, and a pipeline can add two more kinds of things.

Three files you might write Copy Chapter

Nothing. Upgrade, run rtk init, and you have rtk:default — RTK exactly as it worked before: the shell-command rewrite, the awareness file, your filters.toml, your config.toml. No new hooks are registered, nothing changes.

Turn on more. Output compression after every tool call, and the proxy's cache layer, are reference pipelines you opt into — rtk init offers the proxy one; rtk:posthook you add by hand, as below.

# ~/.config/rtk/pipeline.toml
[pipeline]
extends = ["rtk:posthook", "rtk:proxy"]

Tune one thing.

[pipeline]
extends = "rtk:delegate-reads"

[override.shunt-large-read]
when.file_lines_gt = 500

This raises the threshold of the inherited shunt-large-read rule from 350 lines; the rest of its when is kept.

Adopt a behaviour and supply what only you can.

[pipeline]
extends = "rtk:delegate-reads"

[upstream.flash]
provider = "google"
model = "gemini-2.5-flash"
api_key_env = "GEMINI_API_KEY"

[task.bulk-read]
upstream = "flash"
[task.code-write]
upstream = "flash"

Where to go next Copy Chapter

Where things land on disk Copy Chapter

Paths use the Linux spelling; on macOS the user directory is ~/Library/Application Support/rtk/, on Windows %APPDATA%\rtk\.

Hooks are registered for the events and tools your pipeline uses at the time of rtk init. After adding a rule for a new tool or event, run rtk init -g again — rtk pipeline validate prints hook needed: … until you do.

Version skew: what degrades, what refuses Copy Chapter

Pipelines travel — between machines, rtk versions, and (via rtk pipeline share) between people. The validator's contract is split by what a rule can do:

• Transform rules fail open. A compression rule naming a method or condition this rtk does not know gets a warning (W014/W015), that rule is skipped, and the rest of the file stays active. A newer pipeline on an older rtk loses an optimization, never the whole file.
• Control rules fail closed. A rule with an action (deny, route, rewrite, passthrough) must validate completely — an unknown condition or task kind is a hard error for that file. A protection can never look installed while being silently inert.

Upgrading from RTK ≤ 0.51 Copy Chapter

Nothing to do. rtk:default is the RTK you had; there is no migration command.

Guide Proxy Overview (`docs/guide/proxy/overview.md`) Copy Section

title: RTK Proxy sidebar: order: 1 Copy Chapter

RTK Proxy

rtk gain and the agent hooks work on bash output — what a command prints before your agent reads it. The RTK Proxy works one layer up, on the request your agent sends to the model: conversation history, tool results, file contents. It is a local HTTP daemon your agent talks to instead of talking to the model provider directly. The daemon binary is rtk-proxy; you drive it with rtk llm-proxy.

Claude Code ──▶ rtk-proxy ──▶ api.anthropic.com
                     │
                     ├─ normalize: strip ANSI / redraws / dupes
                     ├─ your proxy.request.tool_result rules
                     ├─ (opt-in) cache-align
                     └─ record usage ──▶ rtk gain

It is local: one background process on your machine. It does four things — intercept, compress, forward, record — and does not store prompt or completion text (the opt-in CCR keeps the originals it compresses). What it compresses is in What the Proxy Compresses; its settings and endpoints are in Proxy Configuration.

Both layers are optional and independent. You can run the hooks without the proxy, the proxy without the hooks, or both — rtk gain reports them side by side.

:::note[Separate download, separate licence]
The daemon is a second binary, rtk-proxy, shipped as its own release archive (rtk-proxy-<target>). It is not inside the rtk archive, because it is licensed separately — the rtk CLI is Apache-2.0, rtk-proxy is BUSL-1.1. See Editions and licensing.
:::

Install the daemon Copy Chapter

Download the rtk-proxy-<target> archive for your platform from the releases page and put the binary next to rtk (anywhere on your PATH also works).

From a source checkout:

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

rtk looks for the daemon next to its own binary first, then on PATH. If it cannot find it, rtk llm-proxy tells you exactly where it looked.

Quick start Copy Chapter

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

setup is the one to run first: it reports which AI agents on this machine can be pointed at the proxy, and how.

You rarely need start by hand — rtk claude starts the daemon for you. See Getting your agent onto the proxy.

Getting your agent onto the proxy Copy Chapter

Two independent ways in. rtk init configures your agent once and persists it; rtk <harness> needs no configuration at all.

`rtk init -g` — the guided setup Copy Section

On a Claude Code init, RTK asks:

Set up the RTK proxy (routes Claude Code's API traffic through a local daemon)? [y/N]

Say yes and it writes env.ANTHROPIC_BASE_URL into settings.json and adds extends = "rtk:proxy" to your pipeline. Then it asks how the daemon should come back after a reboot:

Declining leaves everything alone: "Skipped — enable later with rtk init -g or rtk llm-proxy start --env."

If you already have the base URL set but nothing restarting the daemon, re-running rtk init -g asks only the persistence question.

The question is only asked when the daemon can actually run: the rtk-proxy binary is installed (next to rtk or on PATH) or an rtk-proxy already answers on 127.0.0.1:8080. Otherwise init says the proxy was not offered and leaves settings.json alone. rtk init -g --uninstall removes the env.ANTHROPIC_BASE_URL this flow wrote, when it still points at the RTK daemon; a base URL aimed anywhere else is kept.

What the SessionStart hook actually does

It does not do the redirection — that is the settings.json entry above. The hook is a keep-alive: when a session whose ANTHROPIC_BASE_URL points at a loopback address finds nothing listening there, it runs rtk llm-proxy start.

It reports through systemMessage, which is user-visible and never enters model context — RTK spends no tokens configuring itself. Every failure path stays silent rather than disrupting the session.

This route only exists on harnesses that have a SessionStart hook, which is why the next one matters.

`rtk ` — the launcher Copy Section

rtk claude

One command, no configuration, nothing persisted: it starts the daemon if it is not already up, points the harness at it, and execs the real binary. On Unix this is a genuine exec, so signals, stdio and the exit code behave exactly as if you had launched the harness directly.

This route needs no hook system. Not every harness has a SessionStart hook, but most offer a base-URL override — so this is how an agent without hooks still gets onto the proxy.

The daemon is agent-agnostic by design: it speaks the provider's dialect, not the agent's. A subcommand exists only where that redirection has been verified end to end, so rtk <harness> resolving is itself the signal that traffic really goes through the daemon. Today the list is:

A harness absent from the list is never silently unproxied — it falls through to plain passthrough. rtk llm-proxy setup reports what can be launched on this machine.

The launcher never blocks you: if the daemon cannot start, the harness launches unproxied with a warning rather than failing.

`--env` — one shell, by hand Copy Section

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

Any agent launched from that shell routes through the proxy. This is choice 3 above, done manually.

Binding to another address Copy Chapter

Start it on a different address with --bind:

rtk llm-proxy start --bind 127.0.0.1:9090

Every subcommand that talks to a running daemon (stop, status, stats) takes the same --bind flag, so you can manage a proxy that is not on the default 127.0.0.1:8080.

Runtime settings and background service Copy Chapter

Two subcommands forward straight through to the daemon's own CLI:

rtk llm-proxy config <args...>    # get/set runtime settings on a running proxy
rtk llm-proxy service <args...>   # manage a per-user background service

Run either with --help to see the daemon's own options; the settings themselves are listed in Proxy Configuration. service is choice 2 of the guided setup — a per-user background service that survives logins independently of any agent.

Where it keeps its state Copy Chapter

One fixed location, so the daemon's state does not depend on the shell's working directory when it was started:

Because the usage database lives at a known path, rtk gain can report proxy savings whether or not the daemon is currently running.

Seeing the savings Copy Chapter

With the proxy running, a bare rtk gain switches to a live dashboard covering both layers. See Live dashboard and Attribution.

rtk gain              # live dashboard (proxy running, interactive terminal)
rtk gain --text       # force the static view
rtk gain --text --by-method  # which compression method saved what

TELEMETRY (`docs/TELEMETRY.md`) Copy Section

Telemetry

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 Copy Chapter

Entity: RTK AI Labs
Contact: [email protected]

Why we collect telemetry Copy Chapter

RTK supports 100+ commands across 15+ ecosystems. Without telemetry, we have no way to know:

• 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 Copy Chapter

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

Source code: src/core/telemetry.rs

What is collected Copy Chapter

Identity (anonymous) Copy Section

Environment Copy Section

Usage volume Copy Section

Quality (filter improvement) Copy Section

Ecosystem distribution Copy Section

Retention (engagement) Copy Section

Economics Copy Section

Adoption Copy Section

Configuration (user maturity) Copy Section

Feature adoption Copy Section

What is NOT collected Copy Chapter

• 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 Copy Chapter

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 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):

export RTK_TELEMETRY_DISABLED=1

Retention Policy Copy Chapter

• Server-side: telemetry records are retained for a maximum of 12 months, then automatically purged (periodic task every 24 hours).
• 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/tracking.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) Copy Chapter

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 [email protected] with your device hash.
• Restriction of processing: rtk telemetry disable stops all data collection immediately.
• Portability: the local SQLite database at ~/.local/share/rtk/tracking.db contains all locally stored data.
• Objection: rtk telemetry disable or export RTK_TELEMETRY_DISABLED=1.

Erasure Procedure Copy Chapter

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 [email protected] for manual erasure.
3. You can also email [email protected] directly to request manual erasure.

Data Handling Copy Chapter

• Telemetry endpoint URL and auth token are injected at compile time via option_env!() — they are not in the source code
• 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")

Server-side Requirements Copy Section

The telemetry server must implement:

• POST /erasure endpoint accepting {"device_hash": "...", "action": "erasure"}, authenticated via X-RTK-Token
• Automatic periodic purge of telemetry records older than 12 months
• Audit log for erasure requests (GDPR Art. 17(2) accountability) with IP anonymization after 6 months

For contributors Copy Chapter

The telemetry implementation lives in src/core/telemetry.rs. Key design decisions:

• Fire-and-forget: errors are silently ignored, never shown to users
• Non-blocking: runs in a std::thread::spawn, 2-second timeout
• No async: consistent with RTK's single-threaded design
• Compile-time gating: if RTK_TELEMETRY_URL is not set at build time, all telemetry code is dead — the binary makes zero network calls
• 23-hour interval: prevents clock-drift accumulation that a strict 24h interval would cause

When adding new fields:

1. Add the query method to src/core/tracking.rs
2. Add the field to EnrichedStats in src/core/telemetry.rs
3. Populate it in get_enriched_stats()
4. Add it to the JSON payload in send_ping()
5. Update this document and the README.md privacy table
6. Ensure the field contains only aggregate counts or anonymized names — no raw paths, arguments, or user data

Contributing ARCHITECTURE (`docs/contributing/ARCHITECTURE.md`) Copy Section

rtk Architecture Documentation

Deep reference for RTK's system design, filtering taxonomy, performance characteristics, and architecture decisions. For a guided tour of the end-to-end flow, start with TECHNICAL.md.

rtk (Rust Token Killer) is a high-performance CLI proxy that minimizes LLM token consumption through intelligent output filtering and compression.

Table of Contents Copy Chapter

1. System Overview
2. Command Lifecycle
3. Module Organization
4. Filtering Strategies
5. Shared Infrastructure
6. Token Tracking System
7. Global Flags Architecture
8. Error Handling
9. Configuration System
10. Common Patterns
11. Build Optimizations
12. Extensibility Guide
13. Architecture Decision Records

System Overview Copy Chapter

For the proxy pattern diagram and key components table, see TECHNICAL.md.

Design Principles Copy Section

1. Single Responsibility: Each module handles one command type
2. Minimal Overhead: ~5-15ms proxy overhead per command
3. Exit Code Preservation: CI/CD reliability through proper exit code propagation
4. Fail-Safe: If filtering fails, fall back to original output
5. Transparent: Users can always see raw output with -v flags

Hook Architecture (v0.9.5+) Copy Section

For the hook interception diagram and agent-specific JSON formats, see TECHNICAL.md and hooks/README.md.

Two hook strategies:

Auto-Rewrite (default)              Suggest (non-intrusive)
─────────────────────               ────────────────────────
Hook intercepts command             Hook emits systemMessage hint
Rewrites before execution           Claude decides autonomously
Rewrites every matched command      Relies on the model following it
Zero context overhead               Minimal context overhead
Best for: production                Best for: learning / auditing

Command Lifecycle Copy Chapter

Six-Phase Execution Flow Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Verbosity Levels Copy Section

-v (Level 1): Show debug messages
  Example: eprintln!("Git log summary:");

-vv (Level 2): Show command being executed
  Example: eprintln!("Executing: git log --oneline -5");

-vvv (Level 3): Show raw output before filtering
  Example: eprintln!("Raw output:\n{}", stdout);

Module Organization Copy Chapter

Module Map Copy Section

For the full file-level module tree, see TECHNICAL.md and each folder's README.

Ecosystems:

GIT (cmds/git/)          status, diff, log, gh, gt
  JS/TS (cmds/js/)         lint, tsc, next, prettier, playwright, prisma, vitest, pnpm
  PYTHON (cmds/python/)    ruff, pytest, mypy, pip
  GO (cmds/go/)            go test/build/vet, golangci-lint
  RUBY (cmds/ruby/)        rake, rspec, rubocop
  DOTNET (cmds/dotnet/)    dotnet build/test, binlog
  CLOUD (cmds/cloud/)      aws, docker/kubectl, curl, wget, psql
  SYSTEM (cmds/system/)    ls, tree, read, grep, find, json, log, env, deps
  RUST (cmds/rust/)        cargo test/build/clippy, err

Total: 64 modules (42 command modules + 22 infrastructure modules)

Module Breakdown Copy Section

• Command Modules: src/cmds/ — organized by ecosystem (git, rust, js, python, go, dotnet, cloud, system, ruby). Each ecosystem README lists its files.
• Core Infrastructure: src/core/ — utils, filter, tracking, retriever (recall store), tee, tee_file, config, toml_filter, display_helpers, telemetry, arg_tokenizer
• Hook System: src/hooks/ — init, rewrite, permissions, hook_cmd, hook_check, hook_audit, verify, trust, integrity
• Analytics: src/analytics/ — gain, cc_economics, ccusage, session_cmd

Module Count Breakdown Copy Section

• Command Modules: 42 (directly exposed to users)
• Infrastructure Modules: utils, filter, tracking, retriever, tee, tee_file, config, init, gain, toml_filter, verify_cmd, etc.
• Git Commands: 7 operations (status, diff, log, add, commit, push, branch/checkout)
• JS/TS Tooling: 8 modules (modern frontend/fullstack development)
• Python Tooling: 3 modules (ruff, pytest, pip)
• Go Tooling: 2 modules (go test/build/vet, golangci-lint)

Filtering Strategies Copy Chapter

Strategy Matrix Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Code Filtering Levels (src/core/filter.rs) Copy Section

// FilterLevel::None - Keep everything
fn calculate_total(items: &[Item]) -> i32 {
    // Sum all items
    items.iter().map(|i| i.value).sum()
}

// FilterLevel::Minimal - Strip comments only (20-40% reduction)
fn calculate_total(items: &[Item]) -> i32 {
    items.iter().map(|i| i.value).sum()
}

// FilterLevel::Aggressive - Strip comments + function bodies
fn calculate_total(items: &[Item]) -> i32 { ... }

Language Support: Rust, Python, JavaScript, TypeScript, Go, C, C++, Java

Detection: File extension-based with fallback heuristics

Python & Go Module Architecture Copy Chapter

Design Rationale Copy Section

Added: 2026-02-12 (v0.15.1)
Motivation: Complete language ecosystem coverage beyond JS/TS

Python and Go modules follow distinct architectural patterns optimized for their ecosystems:

┌────────────────────────────────────────────────────────────────────────┐
│                 Python vs Go Module Design                             │
└────────────────────────────────────────────────────────────────────────┘

PYTHON (Standalone Commands)         GO (Sub-Enum Pattern)
──────────────────────────           ─────────────────────

Commands::Ruff { args }       ──────  Commands::Go {
Commands::Pytest { args }              Test { args },
Commands::Pip { args }                 Build { args },
                                       Vet { args }
                                     }
├─ ruff_cmd.rs                       Commands::GolangciLint { args }
├─ pytest_cmd.rs                     │
└─ pip_cmd.rs                        ├─ go_cmd.rs (sub-enum router)
                                     └─ golangci_cmd.rs

Mirrors: lint, prettier              Mirrors: git, cargo

Python Stack Architecture Copy Section

Command Implementations

┌────────────────────────────────────────────────────────────────────────┐
│                           Python Commands                              │
└────────────────────────────────────────────────────────────────────────┘

Module            Strategy              Output Format      Savings
─────────────────────────────────────────────────────────────────────────

ruff_cmd.rs       JSON/TEXT DUAL        • check → JSON    80%+
                                        • format → text

  ruff check:  JSON API with structured violations
    {
      "violations": [{"rule": "F401", "file": "x.py", "line": 5}]
    }
    → Group by rule, count occurrences

  ruff format: Text diff output
    "Fixed 12 files"
    → Extract summary, hide unchanged files

pytest_cmd.rs     STATE MACHINE         Text parser       90%+

  State tracking: IDLE → TEST_START → PASSED/FAILED → SUMMARY
  Extract:
    • Test names (test_auth_login)
    • Outcomes (PASSED ✓ / FAILED ✗)
    • Failures only (hide passing tests)

pip_cmd.rs        JSON PARSING          JSON API          70-85%

  pip list --format=json:
    [{"name": "requests", "version": "2.28.1"}]
    → Compact table format

  pip show <pkg>: JSON metadata
    {"name": "...", "version": "...", "requires": [...]}
    → Extract key fields only

  Auto-detect uv: If uv exists, use uv pip instead

Shared Infrastructure

No Package Manager Detection
Unlike JS/TS modules, Python commands don't auto-detect poetry/pipenv/pip because:

• pip is universally available (system Python)
• uv detection is explicit (binary presence check)
• Poetry/pipenv aren't execution wrappers (they manage virtualenvs differently)

Virtual Environment Awareness
Commands respect active virtualenv via sys.executable paths.

Go Stack Architecture Copy Section

Command Implementations

┌────────────────────────────────────────────────────────────────────────┐
│                            Go Commands                                 │
└────────────────────────────────────────────────────────────────────────┘

Module            Strategy              Output Format      Savings
─────────────────────────────────────────────────────────────────────────

go_cmd.rs         SUB-ENUM ROUTER       Mixed formats     75-90%

  go test:  NDJSON STREAMING
    {"Action": "run", "Package": "pkg1", "Test": "TestAuth"}
    {"Action": "fail", "Package": "pkg1", "Test": "TestAuth"}

    → Line-by-line JSON parse (handles interleaved package events)
    → Aggregate: "2 packages, 3 failures (pkg1::TestAuth, ...)"

  go build: TEXT FILTERING
    Errors only (compiler diagnostics)
    → Strip warnings, show errors with file:line

  go vet:   TEXT FILTERING
    Issue detection output
    → Extract file:line:message triples

golangci_cmd.rs   JSON PARSING          JSON API          85%

  golangci-lint run --out-format=json:
    {
      "Issues": [
        {"FromLinter": "errcheck", "Pos": {...}, "Text": "..."}
      ]
    }
    → Group by linter rule, count violations
    → Format: "errcheck: 12 issues, gosec: 5 issues"

Sub-Enum Pattern (go_cmd.rs)

Uses Commands::Go { #[command(subcommand)] command: GoCommand } in main.rs, with GoCommand enum routing to run_test/run_build/run_vet. Mirrors git/cargo patterns.

Why Sub-Enum?

• go test/build/vet are semantically related (core Go toolchain)
• Mirrors existing git/cargo patterns (consistency)
• Natural CLI: rtk go test not rtk gotest

Why golangci-lint Standalone?

• Third-party tool (not core Go toolchain)
• Different output format (JSON API vs text)
• Distinct use case (comprehensive linting vs single-tool diagnostics)

Ruby Module Architecture Copy Section

Added: 2026-03-15
Motivation: Ruby on Rails development support (minitest, RSpec, RuboCop, Bundler)

Ruby modules follow the standalone command pattern (like Python) with a shared ruby_exec() utility for auto-detecting bundle exec.

Module            Strategy              Output Format      Savings
─────────────────────────────────────────────────────────────────────────
rake_cmd.rs       STATE MACHINE         Text parser       85-90%
  Minitest output (rake test / rails test)
  → State machine: Header → Running → Failures → Summary
  → All pass: "ok rake test: 8 runs, 0 failures"
  → Failures: summary + numbered failure details

rspec_cmd.rs      JSON/TEXT DUAL        JSON → 60%+       60%+
  Injects --format json, parses structured results
  → Fallback to text state machine when JSON unavailable
  → Strips Spring, SimpleCov, DEPRECATION, Capybara noise

rubocop_cmd.rs    JSON PARSING          JSON API          60%+
  Injects --format json, groups by cop/severity
  → Skips JSON injection in autocorrect mode (-a, -A)

bundle-install.toml  TOML FILTER       Text rules        90%+
  → Strips "Using" lines, short-circuits to "ok bundle: complete"

Shared: ruby_exec(tool) in utils.rs auto-detects bundle exec when Gemfile exists. Used by rake_cmd, rspec_cmd, rubocop_cmd.

Format Strategy Decision Tree Copy Section

Output format known?
├─ Tool provides JSON flag?
│  ├─ Structured data needed? → Use JSON API
│  │    Examples: ruff check, pip list, golangci-lint
│  │
│  └─ Simple output? → Use text mode
│       Examples: ruff format, go build errors
│
├─ Streaming events (NDJSON)?
│  └─ Line-by-line JSON parse
│       Examples: go test (interleaved packages)
│
└─ Plain text only?
   ├─ Stateful parsing needed? → State machine
   │    Examples: pytest (test lifecycle tracking)
   │
   └─ Simple filtering? → Text filters
        Examples: go vet, go build

Module Integration Checklist Copy Section

When adding Python/Go module support:

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

Shared Infrastructure Copy Chapter

Utilities Layer Copy Section

For the full utilities API (truncate, strip_ansi, execute_command, ruby_exec, etc.), see src/core/README.md. Used by most command modules.

Argument Handling Copy Section

Every command that inspects its own arguments — which flags were passed, which tokens are paths, what to inject or strip — classifies them with src/core/arg_tokenizer.rs. String scans (starts_with('-'), arg == "--flag") miss a flag's own value, attached values, short clusters and everything past --, which is where this module's whole bug class lives.

For the predicate contract and the four rules that come with it (one grammar per subcommand, scope the lookup to the region the tool parses, inject before the boundary, detect and act with one rule), see src/core/README.md.

Package Manager Detection Pattern Copy Section

Critical Infrastructure for JS/TS Stack

┌────────────────────────────────────────────────────────────────────────┐
│                   Package Manager Detection Flow                       │
└────────────────────────────────────────────────────────────────────────┘

Detection Order:
┌─────────────────────────────────────┐
│ 1. Check: pnpm-lock.yaml exists?   │
│    → Yes: pnpm exec -- <tool>      │
│                                     │
│ 2. Check: yarn.lock exists?        │
│    → Yes: yarn exec -- <tool>      │
│                                     │
│ 3. Fallback: Use npx               │
│    → npx --no-install -- <tool>    │
└─────────────────────────────────────┘

Example (lint_cmd.rs):

let is_pnpm = Path::new("pnpm-lock.yaml").exists();
let is_yarn = Path::new("yarn.lock").exists();

let mut cmd = if is_pnpm {
    Command::new("pnpm").arg("exec").arg("--").arg("eslint")
} else if is_yarn {
    Command::new("yarn").arg("exec").arg("--").arg("eslint")
} else {
    Command::new("npx").arg("--no-install").arg("--").arg("eslint")
};

Affects: lint, tsc, next, prettier, playwright, prisma, vitest, pnpm

Why This Matters:

• CWD Preservation: pnpm/yarn exec preserve working directory correctly
• Monorepo Support: Works in nested package.json structures
• No Global Installs: Uses project-local dependencies only
• CI/CD Reliability: Consistent behavior across environments

Token Tracking System Copy Chapter

SQLite-Based Metrics Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Thread Safety Copy Section

Single-threaded execution with Mutex<Option> for future-proofing. No multi-threading currently, but safe concurrent access is possible if needed.

Global Flags Architecture Copy Chapter

Verbosity System Copy Section

┌────────────────────────────────────────────────────────────────────────┐
│                         Verbosity Levels                               │
└────────────────────────────────────────────────────────────────────────┘

main.rs
#[arg(short, long, action = clap::ArgAction::Count)]
verbose: u8,

Levels:
┌─────────┬──────────────────────────────────────────────────────┐
│ Flag    │ Behavior                                             │
├─────────┼──────────────────────────────────────────────────────┤
│ (none)  │ Compact output only                                  │
│ -v      │ + Debug messages (eprintln! statements)              │
│ -vv     │ + Command being executed                             │
│ -vvv    │ + Raw output before filtering                        │
└─────────┴──────────────────────────────────────────────────────┘

Example (git_cmd.rs):
if verbose > 0 {
    eprintln!("Git diff summary:");
}

Error Handling Copy Chapter

anyhow::Result<()> Propagation Chain Copy Section

┌────────────────────────────────────────────────────────────────────────┐
│                      Error Handling Architecture                       │
└────────────────────────────────────────────────────────────────────────┘

Propagation Chain:

main() → Result<()>
  ↓
  match cli.command {
      Commands::Git { args, .. } => git::run(&args, verbose)?,
      ...
  }
  ↓ .context("Git command failed")
git::run(args: &[String], verbose: u8) → Result<()>
  ↓ .context("Failed to execute git")
git::execute_git_command() → Result<String>
  ↓ .context("Git process error")
Command::new("git").output()?
  ↓ Error occurs
anyhow::Error
  ↓ Bubble up through ?
main.rs error display
  ↓
eprintln!("Error: {:#}", err)
  ↓
std::process::exit(1)

Exit Code Preservation (Critical for CI/CD) Copy Section

┌────────────────────────────────────────────────────────────────────────┐
│                    Exit Code Handling Strategy                         │
└────────────────────────────────────────────────────────────────────────┘

Standard Pattern (git_cmd.rs):

let output = Command::new("git").args(args).output()?;

if !output.status.success() {
    let stderr = String::from_utf8_lossy(&output.stderr);
    eprintln!("{}", stderr);
    std::process::exit(output.status.code().unwrap_or(1));
}

Exit Codes:
┌─────────┬──────────────────────────────────────────────────────┐
│ Code    │ Meaning                                              │
├─────────┼──────────────────────────────────────────────────────┤
│ 0       │ Success                                              │
│ 1       │ rtk internal error (parsing, filtering, etc.)        │
│ N       │ Preserved exit code from underlying tool            │
│         │ (e.g., git returns 128, lint returns 1)             │
└─────────┴──────────────────────────────────────────────────────┘

Why This Matters:
• CI/CD pipelines rely on exit codes to determine build success/failure
• Pre-commit hooks need accurate failure signals
• Git workflows require proper exit code propagation

Modules with Exit Code Preservation:
• git_cmd.rs (all git commands)
• lint_cmd.rs (linter failures)
• tsc_cmd.rs (TypeScript errors)
• vitest_cmd.rs (test failures)
• playwright_cmd.rs (E2E test failures)

Configuration System Copy Chapter

Configuration Copy Section

For config file format, recall/tee settings, tracking database path, and TOML filter tiers, see src/core/README.md.

Two tiers: User settings (~/.config/rtk/config.toml) and LLM integration (CLAUDE.md via rtk init).

Initialization Flow Copy Section

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

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

Common Patterns Copy Chapter

1. Package Manager Detection (JS/TS modules)

// Detect lockfiles
let is_pnpm = Path::new("pnpm-lock.yaml").exists();
let is_yarn = Path::new("yarn.lock").exists();

// Build command
let mut cmd = if is_pnpm {
    Command::new("pnpm").arg("exec").arg("--").arg("eslint")
} else if is_yarn {
    Command::new("yarn").arg("exec").arg("--").arg("eslint")
} else {
    Command::new("npx").arg("--no-install").arg("--").arg("eslint")
};

2. Verbosity Guards

if verbose > 0 {
    eprintln!("Debug: Processing {} files", count);
}

if verbose >= 2 {
    eprintln!("Executing: {:?}", cmd);
}

if verbose >= 3 {
    eprintln!("Raw output:\n{}", raw);
}

Build Optimizations Copy Chapter

Release Profile (Cargo.toml) Copy Section

[profile.release]
opt-level = 3          # Maximum optimization
lto = true             # Link-time optimization
codegen-units = 1      # Single codegen unit for better optimization
strip = true           # Remove debug symbols

panic = "abort" is deliberately not set: the PostToolUse hook relies on unwinding to fail open when a filter panics.

Performance Targets Copy Section

• Startup: <10ms
• Memory: <5MB in typical usage

Extensibility Guide Copy Chapter

For the complete step-by-step process to add a new command (module file, enum variant, routing, tests, documentation), see src/cmds/README.md — Adding a New Command Filter.

Architecture Decision Records Copy Chapter

Why Rust? Copy Section

• Performance: ~5-15ms overhead per command (negligible for user experience)
• Safety: No runtime errors from null pointers, data races, etc.
• Single Binary: No runtime dependencies (distribute one executable)
• Cross-Platform: Works on macOS, Linux, Windows without modification

Why SQLite for Tracking? Copy Section

• Zero Config: No server setup, works out-of-the-box
• Lightweight: ~100KB database for 90 days of history
• Reliable: ACID compliance for data integrity
• Queryable: Rich analytics via SQL (gain report)

Why anyhow for Error Handling? Copy Section

• Context: .context() adds meaningful error messages throughout call chain
• Ergonomic: ? operator for concise error propagation
• User-Friendly: Error display shows full context chain

Why Clap for CLI Parsing? Copy Section

• Derive Macros: Less boilerplate (declarative CLI definition)
• Auto-Generated Help: --help generated automatically
• Type Safety: Parse arguments directly into typed structs
• Global Flags: -v and -u work across all commands

Resources Copy Chapter

• TECHNICAL.md: Guided tour of end-to-end flow
• CONTRIBUTING.md: Design philosophy, contribution workflow, checklist
• CLAUDE.md: Quick reference for AI agents (dev commands, build verification)
• README.md: User guide, installation, examples
• Cargo.toml: Dependencies, build profiles, package metadata

Glossary Copy Chapter

Last Updated: 2026-03-24
Architecture Version: 3.1

Contributing CODING PRACTICES (`docs/contributing/CODING_PRACTICES.md`) Copy Section

RTK Coding Practices v1.0

This document follows the Design Philosophy in CONTRIBUTING.md. Once you understand the mental model there, this guide describes the coding practices we use day-to-day in RTK and what reviewers will look for on your PR.

Our goal is to keep the codebase consistent and easy to extend. PRs that deviate from these practices may be asked for changes during review — this is guidance, not a gate. If a rule seems wrong for your specific case, flag it in the PR and we'll discuss.

Heads up: RTK has grown quickly and some code in the repository predates these practices. You may spot modules that don't fully follow them — this is expected, and core/ecosystem maintainers will refactor them over time. When in doubt, follow the practices below for new code rather than mirroring older patterns.

Quick Start for Contributors Copy Chapter

New to RTK? The fastest path to a mergeable first PR:

1. Read the flow once. Start at CONTRIBUTING.md, then skim docs/contributing/TECHNICAL.md to see how a command flows from main.rs → a *_cmd.rs filter → tracking → stdout.
2. Look at a good example. src/cmds/git/git_cmd.rs is a representative filter — it shows the run() entry point, LazyLock regex setup, filter helpers, and embedded tests all in one file.
3. Know the shared helpers before reimplementing. Two files cover most of what you need:
   • src/core/runner.rs — command execution wrappers: run_filtered() (run a command, then apply your filter function), run_passthrough() (run unfiltered but tracked), run_streamed() (streaming filter).
   • src/core/utils.rs — shared utilities: resolved_command(), strip_ansi(), truncate(), count_tokens(), and more.
4. Follow the checklist. src/cmds/README.md — Adding a New Command Filter walks you through creating a filter, registering it, and adding tests.
5. Write the test first. We follow Red-Green-Refactor. A snapshot test plus a token-savings assertion (see Testing below) is enough for most filters.

If you're unsure whether your approach fits, open a draft PR or a discussion early — we'd rather help shape the design than ask for a rewrite at review.

Design Philosophy Copy Chapter

For the full framing (Correctness vs. Token Savings, Transparency, Never Block, Zero Overhead, Extensibility), see the Design Philosophy section in CONTRIBUTING.md.

Two practical reminders that come up often in review:

Portability. RTK should behave the same across platforms. Use #[cfg(target_os = "...")] for platform-specific code; never assume a single OS.

Extensibility. RTK should be modular. Before writing a new feature or filter, check whether an existing entry point fits — runner::run_filtered(), runner::run_passthrough(), helpers in src/core/utils.rs, etc. If your logic could be reused elsewhere, lift it into a shared component rather than burying it in one *_cmd.rs file.

Files, Functions, and Documentation Copy Chapter

Each folder contains a root README.md that explains the main principles, flows, and specificities of the source files it owns. These READMEs should describe concepts and cases — not list individual source files or counts, to avoid stale lists as the code evolves. Because the root README reflects core features and logic, it should not change often; meaningful edits usually imply a core refactor.

Tests live in the same file as the code they test (inside #[cfg(test)] mod tests { ... }), not in a separate test file. This keeps the filter, its fixtures, and its assertions close together.

Edge Cases Copy Chapter

When you add an edge-case branch or a non-obvious exception, leave a short comment above it explaining why it exists. This prevents a future contributor from removing it because the reason isn't visible from the code alone.

Referencing an issue is often the clearest form:

// ISSUE #123: some `git log` output contains NUL bytes when --format=%x00 is used;
// skip the line rather than panicking on invalid UTF-8.
if line.contains('\0') {
    continue;
}

Comments Copy Chapter

Prefer code that reads clearly over code that needs comments to explain it. In particular, avoid redundant comments that restate what the function signature already says.

Comments are welcome when they add information the code cannot carry on its own. The common cases:

• File header (//!) — purpose and scope of the current file.
• Edge case — a non-obvious branch or exception, as described above.
• Issue reference — e.g. // ISSUE #123: the fix for this.
• "Why, not what" — when the intent or tradeoff behind a decision isn't obvious from the code.

In short: avoid noise comments; keep the ones that would save a future reader a trip to git blame.

Variables Copy Chapter

Use explicit, descriptive names for variables, just like for functions.

Do not hardcode repetitive patterns or values that control behavior — extract them into named constants at the top of the file. For anything a user might want to tune (thresholds, limits, display cutoffs), use config::limits() so it flows through ~/.config/rtk/config.toml.

Example from src/cmds/git/git_cmd.rs:

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

Function and File Size Copy Chapter

Prefer functions under ~60 lines. Shorter functions are easier to read, test, and reuse. If a function grows beyond that, it's usually a sign the logic should be split into helpers — but this is a guideline, not a hard cap.

Legitimate exceptions include:

• Dispatcher / match functions that route to subcommands, where each arm delegates to a focused helper.
• State-machine parsers where splitting would harm readability.

When you keep a longer function, aim to make each block obviously cohesive — and consider leaving a short comment on why splitting it would hurt.

Files are expected to be large in RTK because each module keeps its tests and fixtures alongside the implementation. When a file becomes hard to navigate, split responsibilities across multiple files where possible. If it isn't possible, a big file is acceptable for now.

Imports and Dependencies Copy Chapter

RTK is a low-dependency project. Before adding a crate, check whether the functionality is already covered by std, an existing dependency, or src/core/utils.rs. If a few lines of straightforward code will do the job, prefer that over a new dependency.

When a new dependency is genuinely needed, justify it in the PR description. For non-trivial additions, it's worth opening a discussion with maintainers first.

Error Handling Copy Chapter

Use anyhow::Result everywhere, and always attach context with .context("description")? or .with_context(|| format!(...)).

Never silently swallow errors (Err(_) => {}). Either log with eprintln! and fall back to raw output (the common case for filters), or propagate the error.

Example of the standard fallback pattern for a filter:

let filtered = filter_output(&output.stdout)
    .unwrap_or_else(|e| {
        eprintln!("rtk: filter warning: {}", e);
        output.stdout.clone() // passthrough on failure — never block the user
    });

For the full error-handling architecture (propagation chain, exit code preservation), see ARCHITECTURE.md — Error Handling.

Testing Copy Chapter

See CONTRIBUTING.md — Testing for the full strategy. In short, for a new filter you typically want:

• Unit + snapshot tests in the same file, using the insta crate.
• A savings assertion verifying the filter hits the ≥20% target on a real fixture. The target is a reduction in bash output, measured with RTK's token estimator rather than a real tokenizer.

Minimal example:

#[cfg(test)]
mod tests {
    use super::*;
    use insta::assert_snapshot;

    fn count_tokens(s: &str) -> usize { s.split_whitespace().count() }

    #[test]
    fn filter_git_log_snapshot() {
        let input = include_str!("../../../tests/fixtures/git_log_raw.txt");
        let output = filter_git_log(input);
        assert_snapshot!(output);
    }

    #[test]
    fn filter_git_log_savings() {
        let input = include_str!("../../../tests/fixtures/git_log_raw.txt");
        let output = filter_git_log(input);
        let savings = 100.0 - (count_tokens(&output) as f64 / count_tokens(input) as f64 * 100.0);
        assert!(savings >= 20.0, "expected ≥20% output reduction, got {:.1}%", savings);
    }
}

Fixtures go in tests/fixtures/ and should be captured from real command output rather than hand-written.

Security Copy Chapter

RTK executes shell commands on behalf of the user, so security is a first-class concern.

Command execution. All commands go through argument arrays via Command::new().args() — never through shell string concatenation. This prevents injection. Always use resolved_command() from src/core/utils.rs instead of a raw Command::new().

Hook integrity. RTK verifies hook files via SHA-256 hashes before operational commands. If a hook has been tampered with, RTK exits with code 1. See src/hooks/integrity.rs.

Project filter trust. .rtk/filters.toml files are not loaded until the user explicitly trusts them, and content changes require re-trust. See src/hooks/trust.rs.

Permission whitelist. is_operational_command() in main.rs uses a whitelist pattern — new commands are not integrity-checked until explicitly added. This is an intentional security posture: fail-open with an audit trail is preferred over false confidence.

unsafe code. Not allowed except for Unix signal handling in proxy mode, which is correctly scoped to #[cfg(unix)].

Contributing TECHNICAL (`docs/contributing/TECHNICAL.md`) Copy Section

RTK Technical Documentation

Start here for a guided tour of how RTK works end-to-end.

• CONTRIBUTING.md — Design philosophy, PR process, branch naming, testing requirements
• ARCHITECTURE.md — Deep reference: filtering taxonomy, performance targets, architecture decisions
• Each folder has its own README.md with implementation details and file descriptions

1. Project Vision Copy Chapter

LLM-powered coding agents (Claude Code, Copilot, Cursor, etc.) consume tokens for every CLI command output they process. Most command outputs contain boilerplate, progress bars, ANSI escape codes, and verbose formatting that wastes tokens without providing actionable information.

RTK sits between the agent and the CLI, filtering outputs to keep only what matters. This reduces the bash output per command, reducing costs and increasing effective context window utilization. RTK is a single Rust binary with no runtime dependencies beyond the compiled binary itself, adding less than 10ms overhead per command.

Every percentage below measures bash output, which is one contributor to input tokens, themselves only part of a bill that also counts output tokens. RTK ships no tokenizer (src/core/tracking.rs estimates bytes / 4), so the ratios are reliable but the absolute token counts are approximate.

2. Architecture Overview Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Design principles:

• Single-threaded, no async (startup < 10ms)
• Graceful degradation: filter failure falls back to raw output
• Exit code propagation: RTK never swallows non-zero exits
• Transparent proxy: unknown commands pass through unchanged

3. End-to-End Flow Copy Chapter

This is the full lifecycle of a command through RTK, from LLM agent to filtered output.

3.1 Hook Installation (`rtk init`) Copy Section

The user runs rtk init to set up hooks for their LLM agent. This:

1. Writes a thin shell hook script (e.g., ~/.claude/hooks/rtk-rewrite.sh)
2. Stores its SHA-256 hash for integrity verification
3. Patches the agent's settings file (e.g., settings.json) to register the hook
4. Writes RTK awareness instructions (e.g., RTK.md) for prompt-level guidance

RTK supports 7 agents, each with its own installation mode. The hook scripts are embedded in the binary and written at install time.

Details: src/hooks/README.md covers all installation modes, configuration files, and the uninstall flow.

3.2 Hook Interception (Command Rewriting) Copy Section

When an LLM agent runs a command (e.g., git status):

1. The agent fires a PreToolUse event (or equivalent) containing the command as JSON
2. The hook script reads the JSON, extracts the command string
3. The hook calls rtk rewrite "git status" as a subprocess
4. rtk rewrite consults the command registry and returns rtk git status
5. The hook sends a response telling the agent to use the rewritten command
6. If anything fails (jq missing, rtk not found, no match), the hook exits silently -- the raw command runs unchanged

All rewrite logic lives in Rust (src/discover/registry.rs). Hooks are thin delegates that handle agent-specific JSON formats.

Details: hooks/README.md covers each agent's JSON format, the rewrite registry, compound command handling, and the RTK_DISABLED override.

Rewrite Pipeline

The rewrite pipeline is how RTK intercepts and rewrites commands. The call chain is:

hook shell → rewrite_cmd.rs → rewrite_command() → rewrite_compound() → rewrite_segment() → classify_command()

Traced step by step for cargo fmt --all && cargo test 2>&1 | tail -20:

/* Detailed source-code truncated for AI context efficiency. */

Key design decisions:

• Lexer-based tokenization: A single-pass state machine (lexer.rs) handles all shell constructs (quotes, escapes, redirects, operators). Used for both compound splitting and redirect stripping.
• Segment-level rewriting: Compound commands are split by operators, each segment rewritten independently. Bash recombines them at execution time.
• Conservative shell-wrapper recursion: Only exact quoted sh|bash|zsh|fish -c wrappers enter one level of inner rewriting. The parser hands back byte ranges instead of a decoded script, so the wrapper's own bytes are never re-quoted, and it reports the shell it matched so the script is attested under that shell's grammar rather than under bash's.
• Pipe semantics: Producers and intermediate stages of | remain raw. Only an argument-safe final stage whose rule has pipeline_final_safe may be rewritten; initially this is limited to ordinary grep and rg invocations. Search pattern-file forms (-f/--file) defer because they can consume pipeline stdin as configuration. |& is recognized separately and its complete pipeline stays raw.
• Double env prefix handling: classify_command() strips env prefixes to match the underlying command against rules. rewrite_segment() extracts the same prefix separately to re-prepend it to the rewritten command.
• Fallback contract: If any segment fails to match, it stays raw. rewrite_command() returns None only when zero segments were rewritten.

3.3 CLI Parsing and Routing Copy Section

Once the rewritten command reaches RTK:

1. Telemetry: telemetry::maybe_ping() fires a non-blocking daily usage ping
2. Clap parsing: Cli::try_parse() matches against the Commands enum
3. Hook check: hook_check::maybe_warn() warns if the installed hook is outdated (rate-limited to 1/day)
4. Integrity check: integrity::runtime_check() verifies the hook's SHA-256 hash for operational commands
5. Routing: A match cli.command dispatches to the specialized filter module

If Clap parsing fails (command not in the enum), the fallback path runs instead.

3.4 Filter Execution Copy Section

RTK has two filter systems:

Rust Filters: Compiled modules in src/cmds/ that execute the command, parse its output, and apply specialized transformations (regex, JSON, state machines).

TOML DSL Filters: Declarative filters in src/filters/*.toml that apply regex-based line filtering, truncation, and section extraction. Applied in run_fallback() when no Rust filter matches.

Each filter module follows the same pattern:

1. Start a timer (TimedExecution::start())
2. Execute the underlying command (std::process::Command)
3. Apply filtering (strip boilerplate, group errors, truncate)
4. On filter error, fall back to raw output
5. Track token savings to SQLite
6. Propagate exit code

Details: src/cmds/README.md covers the common pattern, ecosystem organization, cross-command dependencies, and how to add new filters.

3.5 Fallback Path Copy Section

When Clap parsing fails (unknown command):

1. Guard: check if the command is an RTK meta-command (gain, init, etc.) -- if so, show Clap error
2. Look up TOML DSL filters via toml_filter::find_matching_filter()
3. If TOML match: capture stdout, apply filter pipeline, track savings
4. If no match: pure passthrough with Stdio::inherit, track as 0% output reduction

Command received
  -> Clap parse succeeds?
     -> Yes: Route to Rust filter module
     -> No:  run_fallback()
              -> TOML filter match?
                 -> Yes: Capture stdout, apply filter, track savings
                 -> No:  Passthrough (inherit stdio, track 0% reduction)

Details: src/core/README.md covers the TOML filter engine, filter pipeline stages, and trust-gated project filters.

3.6 Token Tracking Copy Section

Every command execution records metrics to SQLite (~/.local/share/rtk/tracking.db):

• Input tokens (raw output size) and output tokens (filtered size)
• Savings percentage, execution time, project path
• 90-day automatic retention cleanup
• Token estimation: ceil(chars / 4.0) approximation

Analytics commands (rtk gain, rtk cc-economics, rtk session) query this database to produce dashboards and ROI reports.

Details: src/analytics/README.md covers the analytics modules, and src/core/README.md covers the tracking database schema.

3.7 Output Recovery (recall store) Copy Section

On command failure (non-zero exit code) — or when a filter truncates a long list:

1. Raw unfiltered output is stored in a content-addressed sqlite database (~/.local/share/rtk/recall.db, gzip, byte-faithful)
2. A hint line is printed: [full output: rtk recall 3f9c2a81d4e7b05a] (failures) or [+N hidden: rtk recall <hash>] (truncated lists)
3. LLM agents run rtk recall <hash> to get back exactly what was elided instead of re-running the command

The mode is selectable via rtk config recall <sqlite|tee|disabled> — tee keeps the legacy per-file behavior (~/.local/share/rtk/tee/{epoch}_{slug}.log). Recovery never affects command output or exit code. rtk gain --recalls reports how often elided output is actually consulted, per filter.

Details: src/core/README.md covers the recall store, tee mode configuration, and the rotation strategy.

4. Folder Map Copy Chapter

Start here, then drill down into each README for file-level details.

`src/` — Rust source code Copy Section

`hooks/` — Deployed hook artifacts (root directory) Copy Section

5. Hook System Summary Copy Chapter

RTK supports the following LLM agents through hook integrations:

Details: hooks/README.md has the full JSON schemas for each agent. src/hooks/README.md covers installation, integrity verification, and the rewrite command.

6. Filter Pipeline Summary Copy Chapter

Rust Filters (cmds/**) Copy Section

Compiled filter modules for complex transformations.

Details: src/cmds/README.md and each ecosystem subdirectory README.

TOML DSL Filters (src/filters/*.toml) Copy Section

Declarative filters with an 8-stage pipeline: strip ANSI, regex replace, match output, strip/keep lines, truncate lines, head/tail, max lines, on-empty message. Loaded from three tiers: built-in (compiled), global (~/.config/rtk/filters/), project-local (.rtk/filters/, trust-gated).

Details: src/core/README.md covers the TOML filter engine.

7. Performance Constraints Copy Chapter

Achieved through:

• Zero async overhead (single-threaded, no tokio)
• Lazy regex compilation (LazyLock)
• Minimal allocations (borrow over clone)
• No config file I/O on startup (loaded on-demand)

8. Testing Copy Chapter

Tests live in the module file itself inside a #[cfg(test)] mod tests block (e.g., tests for src/cmds/cloud/container.rs go at the bottom of that same file).

How to Write Tests Copy Section

1. Create a fixture from real command output (not synthetic data):

kubectl get pods > tests/fixtures/kubectl_pods_raw.txt

2. Write your test in the same module file (#[cfg(test)] mod tests):