# RTK on Windows WSL vs Native Windows: Key Differences and Setup Guide

> Explore RTK on Windows WSL vs native Windows. Discover key differences in auto-rewrite hooks, setup, and identical filters/analytics. Get the RTK guide for your environment.

- Repository: [rtk-ai/rtk](https://github.com/rtk-ai/rtk)
- Tags: how-to-guide
- Published: 2026-04-24

---

**RTK (Rust Token Killer) provides full auto-rewrite hook functionality on Windows WSL but falls back to CLAUDE.md injection on native Windows due to POSIX shell dependencies, while filters and analytics work identically on both platforms.**

Understanding how **RTK on Windows WSL and native Windows environments** differs is critical for maximizing token savings. The `rtk-ai/rtk` repository supports both platforms, but the installation behavior and hook capabilities vary significantly depending on whether you run inside a Linux subsystem or native Windows terminals. This guide breaks down the architectural differences, setup procedures, and feature parity between these two environments.

## Feature Comparison: WSL vs Native Windows

RTK operates with different capabilities depending on your Windows environment:

- **Filters (cargo, git, etc.)** – Fully functional on both platforms. The same Rust-based filter modules process commands identically whether running in WSL or native Command Prompt.

- **Auto-rewrite hook** – **Enabled** on WSL using the [`rtk-rewrite.sh`](https://github.com/rtk-ai/rtk/blob/main/rtk-rewrite.sh) shell hook that intercepts and rewrites commands before AI assistants process them. **Disabled** on native Windows because the hook requires a POSIX-compatible shell; RTK instead uses *CLAUDE.md injection* (prompt-level instructions) as a fallback.

- **`rtk init -g` behavior** – On WSL, this installs the full POSIX hook mode. On native Windows, it automatically deploys the CLAUDE.md fallback mode without the shell hook.

- **Analytics** – All features including `rtk gain`, `discover`, `proxy`, and `verify` collect data identically on both platforms.

## Architectural Differences

### How the Auto-Rewrite Hook Works

The **auto-rewrite hook** relies on POSIX shell integration. When you run `rtk init -g` inside WSL, RTK installs [`rtk-rewrite.sh`](https://github.com/rtk-ai/rtk/blob/main/rtk-rewrite.sh) to `~/.config/rtk/hooks/`, which your login shell (bash, zsh, etc.) sources automatically.

As implemented in [`src/hooks/rewrite_cmd.rs`](https://github.com/rtk-ai/rtk/blob/main/src/hooks/rewrite_cmd.rs), this script intercepts every command line and forwards it to the RTK binary. The binary then decides whether to filter, rewrite, or pass through the output. This mechanism requires POSIX-compatible shells available only in WSL, allowing commands like `git status` to automatically rewrite to `rtk git status` without manual intervention.

### Native Windows Fallback Mechanism

On native Windows terminals (Command Prompt, PowerShell, Windows Terminal), the POSIX shell is unavailable. The `rtk init -g` command, handled in [`src/hooks/init.rs`](https://github.com/rtk-ai/rtk/blob/main/src/hooks/init.rs), detects this environment and automatically switches to **CLAUDE.md injection** mode.

Instead of installing the shell hook, RTK creates a static [`CLAUDE.md`](https://github.com/rtk-ai/rtk/blob/main/CLAUDE.md) file in your project root containing instructions for AI assistants to prepend `rtk` to relevant commands. This provides token-saving benefits through filters and explicit `rtk` prefixes, but **no automatic rewrite** occurs for ad-hoc commands—you must manually type `rtk` before commands to engage filtering.

## Installation and Setup Differences

The setup experience diverges immediately based on your environment.

Inside WSL (full hook mode):

```bash

# Installs the POSIX hook to ~/.config/rtk/hooks/rtk-rewrite.sh

$ rtk init -g

# Commands automatically rewrite through the filter

$ rtk cargo test       # Explicit invocation

$ git status           # Automatically rewritten to 'rtk git status'

```

Inside native Windows CMD/PowerShell (fallback mode):

```powershell

# Falls back to CLAUDE.md injection; no hook installed

> rtk init -g

# Filter runs only when explicitly invoked

> rtk cargo test       # Filter runs, manual prefix required

> git status           # Runs raw git; no automatic rewrite occurs

```

You can verify which mode is active by checking for `~/.config/rtk/hooks/rtk-rewrite.sh` (WSL hook mode) or the presence of [`CLAUDE.md`](https://github.com/rtk-ai/rtk/blob/main/CLAUDE.md) in your repository (native Windows fallback).

## Core Functionality Shared Across Platforms

Despite the hook differences, RTK maintains **identical core behavior** across environments. The filtering logic resides in the Rust crate under `src/parser/` and `src/hooks/`, compiling to the same binary (`rtk` or `rtk.exe`) regardless of platform.

Analytics collection, token calculation algorithms, and filter definitions remain consistent. Whether running `rtk gain` in WSL or native Windows, the underlying Rust implementation in `src/` processes your commands with the same efficiency and accuracy.

## Summary

- **WSL provides the full RTK experience** with automatic command rewriting via POSIX shell hooks ([`rtk-rewrite.sh`](https://github.com/rtk-ai/rtk/blob/main/rtk-rewrite.sh)).
- **Native Windows uses CLAUDE.md fallback** without auto-rewrite, requiring manual `rtk` prefixes for filtered commands.
- **Filters and analytics work identically** on both platforms using the shared Rust core in `src/`.
- **[`src/hooks/init.rs`](https://github.com/rtk-ai/rtk/blob/main/src/hooks/init.rs) automatically detects** your environment and chooses the appropriate installation method.
- **Verify your mode** by checking for the shell hook script (WSL) or the CLAUDE.md file (native Windows).

## Frequently Asked Questions

### Can I use RTK on native Windows without WSL?

Yes, RTK fully supports native Windows through Command Prompt and PowerShell. However, you will not get the automatic rewrite functionality. Instead, RTK uses CLAUDE.md injection to provide instructions to AI assistants, and you must manually prepend `rtk` to commands to activate filters. All analytics and core filtering features remain available.

### Why does the auto-rewrite hook require WSL?

The auto-rewrite hook depends on POSIX shell scripting via [`rtk-rewrite.sh`](https://github.com/rtk-ai/rtk/blob/main/rtk-rewrite.sh), which intercepts command execution by integrating with your login shell (bash, zsh, etc.). Native Windows lacks the POSIX-compatible shell environment required to source and execute this interception script, making WSL necessary for the transparent rewrite experience.

### Do filters and analytics work the same on both platforms?

Yes, the core Rust implementation in `src/parser/` and `src/hooks/` ensures identical behavior. Commands like `rtk gain`, `rtk discover`, and `rtk verify` process data the same way whether running on WSL or native Windows. The only difference is the automatic interception mechanism, not the filtering logic itself.

### How do I check if RTK is running in hook mode or fallback mode?

After running `rtk init -g`, check for the existence of `~/.config/rtk/hooks/rtk-rewrite.sh` to confirm hook mode (WSL), or look for a [`CLAUDE.md`](https://github.com/rtk-ai/rtk/blob/main/CLAUDE.md) file in your project root to confirm fallback mode (native Windows). The initialization output also indicates which mode was selected based on your shell environment.