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

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 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 to ~/.config/rtk/hooks/, which your login shell (bash, zsh, etc.) sources automatically.

As implemented in 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, detects this environment and automatically switches to CLAUDE.md injection mode.

Instead of installing the shell hook, RTK creates a static 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):

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

# 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 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).
• 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}