# When to Use RTK Proxy Mode Instead of Standard Filtering > Discover when to use RTK proxy mode over standard filtering. Ideal for unfiltered output, custom tools, exact signals, and bypassing analytics while tracking usage. - Repository: [rtk-ai/rtk](https://github.com/rtk-ai/rtk) - Tags: best-practices - Published: 2026-04-24 --- **Use RTK proxy mode when you need unfiltered command output, lack a dedicated filter for your tool, require exact signal handling, or want to bypass token-saving analytics while maintaining usage tracking.** The `rtk-ai/rtk` repository provides an intelligent CLI wrapper that optimizes command output to reduce token costs, but not every scenario benefits from filtering. RTK proxy mode acts as a **passthrough execution path** that runs commands without any output filtering while still recording invocations for analytics. Understanding when to switch from standard filtering to proxy mode ensures you get the exact behavior your workflow demands. ## What Is RTK Proxy Mode? Proxy mode is a specialized execution path in [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) that bypasses the TOML-based filter lookup and generic output-filter pipeline. When you prefix a command with `rtk proxy`, the tool executes the requested command directly, relaying raw `stdout` and `stderr` streams to your terminal without truncation, deduplication, or progress bar stripping. Unlike standard filtering, proxy mode maintains the ** analytics tracking layer**. According to [`src/core/tracking.rs`](https://github.com/rtk-ai/rtk/blob/main/src/core/tracking.rs) lines [29-42], the `Tracker::record` function still creates a database entry showing 0% token savings, ensuring your usage metrics remain complete even when bypassing optimization. ## When to Use RTK Proxy Mode Instead of Filtering ### No Dedicated Filter Exists for Your Command When running custom CLIs, obscure flags, or newly released tools, the generic filter might drop useful information or fail entirely. Proxy mode guarantees raw output delivery unchanged because it skips the filter resolution step entirely. In [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2132-2142], the `Commands::Proxy` arm validates your input but does not attempt filter matching, making it the safe choice for unsupported commands. ### Exact Output Required for Downstream Tools Filters intentionally modify streams to save tokens—truncating logs, stripping ANSI codes, or removing duplicate lines. When piping output to scripts, parsing tools, or debugging utilities that expect precise formatting, use proxy mode. The implementation in [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2210-2212] spawns the child process with `stdout(Stdio::piped())` and `stderr(Stdio::piped())`, then relays bytes without transformation. This preserves every byte including ANSI escape sequences and binary-safe output. ### Debugging and Filter Verification When developing filters or troubleshooting unexpected behavior, you need a ground-truth reference. Running the same command through standard filtering and then through `rtk proxy` lets you compare optimized versus raw output to verify heuristic correctness. The verbose logging feature (lines [2167-2169]) prints the exact resolved command before execution when using `-v` or `-vv` flags, aiding debugging sessions. ### Performance-Critical Commands Standard filtering introduces pipeline overhead for token counting and stream processing. For time-sensitive operations where even minimal latency is undesirable, proxy mode bypasses the filter pipeline entirely. Only the lightweight tracking wrapper remains active, invoking your command directly through `core::utils::resolved_command` without intermediate processing steps. ### Signal Handling and Process Control Standard mode may interfere with signal propagation between parent and child processes. Proxy mode implements precise signal forwarding required for interactive or long-running tasks. In [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2171-2188], the code registers Unix signal handlers for `SIGINT` and `SIGTERM` that forward termination signals to the child process using a static `AtomicU32` to store the child PID. The `ChildGuard` struct (lines [2195-2203]) ensures the child is killed and waited on if the parent exits unexpectedly, preventing orphaned processes while maintaining exact process control semantics. ### Analytics Without Token Optimization Sometimes you want usage tracking without the savings. Proxy mode creates a `Tracker` entry showing 0% savings, keeping your analytics complete while preserving full output. This is useful when demonstrating RTK's capabilities or running commands where token costs are irrelevant, but you still want the SQLite database to record the invocation for historical analysis. ## How Proxy Mode Works Under the Hood The proxy implementation follows a strict execution flow designed for reliability: 1. **Argument Parsing**: In [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2148-2155], the `shell_split` function respects quoting rules. A command like `rtk proxy 'git log --format="%H %s"'` correctly parses into `cmd=git` with `args=["log", "--format=%H %s"]`. 2. **Process Spawning**: Lines [2210-2212] resolve the executable via `core::utils::resolved_command` and spawn the child with piped streams. 3. **Signal Management**: The static `AtomicU32` stores the child PID (lines [2171-2188]), allowing signal handlers to forward `SIGINT` and `SIGTERM` to the child before re-raising the signal to the parent. 4. **Execution Tracking**: Despite bypassing filters, the `TimedExecution` timer starts before spawning, and `core::tracking::Tracker::record` persists the run to the SQLite database with zero savings recorded. ## Practical Examples ```bash # Run a custom tool without a dedicated filter rtk proxy my-custom-cli --verbose --output json # Get exact git log format for scripting rtk proxy 'git log --format="%H %s" -n 5' # Compare filtered vs raw output for debugging rtk git log -n 5 # Filtered, token-optimized rtk proxy 'git log -n 5' # Raw, exact output # Verify tracking still occurs (shows 0% savings) rtk gain --history | grep "proxy" # Debug signal handling with verbosity rtk -vv proxy 'npm install --silent' ``` ## Summary - **Proxy mode** bypasses RTK's filter pipeline while preserving analytics tracking in [`src/core/tracking.rs`](https://github.com/rtk-ai/rtk/blob/main/src/core/tracking.rs). - Use it when **no filter exists** for your command, you need **exact output** for scripts, or you're **debugging filter behavior**. - Proxy mode provides **superior signal handling** via dedicated `SIGINT`/`SIGTERM` forwarding in [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) [2171-2188]. - The `ChildGuard` mechanism prevents orphaned processes while maintaining raw stream passthrough. - All proxy executions are logged with **0% token savings** for complete usage analytics. ## Frequently Asked Questions ### What is the difference between RTK proxy mode and standard filtering? Standard filtering processes command output through TOML-defined filters that truncate, deduplicate, or strip content to reduce token costs. Proxy mode executes commands directly without filtering, preserving raw `stdout` and `stderr` streams while still recording the invocation to the analytics database. ### Does proxy mode still track my command usage? Yes. According to [`src/core/tracking.rs`](https://github.com/rtk-ai/rtk/blob/main/src/core/tracking.rs) lines [29-42], the `Tracker::record` function creates database entries for proxy runs, recording 0% token savings. This ensures your usage history remains complete even when bypassing optimization. ### Can I use proxy mode with any shell command? Yes. The argument parser in [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2148-2155] uses `shell_split` to handle complex quoting, supporting any executable in your `PATH`, custom scripts, or multi-word commands wrapped in quotes. ### How does proxy mode handle process signals differently? Proxy mode installs dedicated Unix signal handlers in [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/src/main.rs) lines [2171-2188] that forward `SIGINT` and `SIGTERM` directly to the child process using an `AtomicU32` to store the child PID. This ensures interactive commands receive termination signals immediately, unlike standard mode which may buffer or delay signal propagation.