Windows WSL workaround for rtk init -g hook installation

[kockono]

RTK Hook Setup on Windows — Complete Guide

Three working approaches to get rtk init -g hook behavior on Windows,
eliminating the /!\ No hook installed warning and enabling transparent
command rewriting in Claude Code.

Related: Discussion #671 ·
Issue #330 ·
PR #150

---

The Problem

rtk init -g installs a PreToolUse hook for Claude Code by writing a bash
script (rtk-rewrite.sh) and patching ~/.claude/settings.json. However, the
hook installation explicitly blocks on Windows:

[warn] Hook-based mode requires Unix (macOS/Linux).
    Windows: use --claude-md mode for full injection.

This means Windows users always see:

[rtk] /!\ No hook installed — run `rtk init -g` for automatic token savings

even though the rest of RTK works fine. Only CLAUDE.md gets updated — no
hook, no settings.json entry, no RTK.md. RTK then relies entirely on the
LLM reading the instructions and choosing to follow them (~70-80% reliability
vs ~100% with a hook).

---

Root Cause

Three Unix-specific dependencies block hook installation on Windows
(src/hooks/init.rs is gated behind #[cfg(unix)]):

1. Bash — rtk-rewrite.sh is a bash script. No native bash on Windows.
2. jq — the hook uses jq to parse/build JSON. Not available by default on Windows.
3. Unix file permissions — chmod 755 uses std::os::unix::fs::PermissionsExt,
   a Rust trait that doesn't compile on Windows at all.

---

Three Working Approaches

Pick the one that matches your setup:

Approach	Requirements	Reliability	RTK detects hook?
Option A — Git Bash	Git for Windows	✅ 100%	⚠️ partial
Option B — PowerShell	PowerShell 7+	✅ 100%	⚠️ partial
Option C — WSL	WSL2 + Ubuntu	✅ 100%	✅ full

"RTK detects hook" refers to rtk init --show showing all [ok] with no
warning. Options A and B will still show [warn] Hook outdated because RTK
compares file content against its embedded Unix script. The hook works
correctly in all three cases — the warning is cosmetic.

---

Option A — Git Bash (Simplest)

Prerequisites: Git for Windows installed (provides bash and jq-less
alternative). Discovered by @cobrabr.

Claude Code on Windows uses Git Bash internally to run hook commands, so a
.sh file works directly — no WSL needed.

Step 1 — Create the hook directory and script

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\hooks"

Download the official hook script from the RTK repo and save it to
~/.claude/hooks/rtk-rewrite.sh:

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/rtk-ai/rtk/master/hooks/claude/rtk-rewrite.sh" `
  -OutFile "$env:USERPROFILE\.claude\hooks\rtk-rewrite.sh"

Step 2 — Install jq (required by the hook)

The hook script uses jq to parse JSON. Install it via
Chocolatey:

choco install jq -y

Or download the binary from jqlang.github.io/jq
and place it anywhere in your PATH.

Step 3 — Patch settings.json

Add the hook entry to ~/.claude/settings.json. Use forward slashes in the
path — Git Bash strips backslashes silently:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash '/c/Users/<YOUR_USERNAME>/.claude/hooks/rtk-rewrite.sh'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Step 4 — Create RTK.md manually

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/rtk-ai/rtk/master/hooks/claude/rtk-awareness.md" `
  -OutFile "$env:USERPROFILE\.claude\RTK.md"

Then add @RTK.md to ~/.claude/CLAUDE.md (create the file if it doesn't exist).

Step 5 — Test

$json = '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"git status"}}'
$json | bash '/c/Users/<YOUR_USERNAME>/.claude/hooks/rtk-rewrite.sh'

Expected:

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

---

Option B — PowerShell (No Extra Tools)

Prerequisites: PowerShell 7+ (built into Windows). No Git Bash, no WSL, no
jq. Discovered by @skymat.

PowerShell's ConvertFrom-Json / ConvertTo-Json replaces jq, and the
script runs natively without any additional dependencies.

Step 1 — Create the hook script

Create ~/.claude/hooks/rtk-rewrite.ps1:

# RTK PreToolUse hook — Windows PowerShell
# Requires: rtk >= 0.23.0
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

$json = [Console]::In.ReadToEnd()

try {
    $data = $json | ConvertFrom-Json
} catch {
    exit 0
}

$cmd = $data.tool_input.command
if (-not $cmd) { exit 0 }

$rewritten = & rtk rewrite $cmd 2>$null
$exitCode = $LASTEXITCODE

if ($exitCode -eq 0 -and $rewritten -and $rewritten -ne $cmd) {
    @{
        hookSpecificOutput = @{
            hookEventName      = "PreToolUse"
            permissionDecision = "allow"
            updatedInput       = @{ command = $rewritten }
        }
    } | ConvertTo-Json -Compress -Depth 5
} elseif ($exitCode -eq 3 -and $rewritten -and $rewritten -ne $cmd) {
    # Ask rule — rewrite but let Claude Code prompt the user
    @{
        hookSpecificOutput = @{
            hookEventName = "PreToolUse"
            updatedInput  = @{ command = $rewritten }
        }
    } | ConvertTo-Json -Compress -Depth 5
}

exit 0

Why [Console]::OutputEncoding? PowerShell 7 writes UTF-16LE by default.
Claude Code expects UTF-8. Without this, the JSON output is unreadable.

Step 2 — Patch settings.json

Add -ExecutionPolicy Bypass to avoid script execution policy errors
(@sguryev):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File C:\\Users\\<YOUR_USERNAME>\\.claude\\hooks\\rtk-rewrite.ps1",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Step 3 — Test

$json = '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"git status"}}'
$json | powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\hooks\rtk-rewrite.ps1"

Expected:

{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"rtk git status"}}}

Known gotchas (PowerShell)

Bug	Cause	Fix
JSON output garbled	PowerShell 7 defaults to UTF-16LE	Add [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
Hook silently blocked	Execution policy	Use -ExecutionPolicy Bypass
Async hook gets no stdin	"async": true closes stdin pipe	Keep hook synchronous (no "async" field)
BOM in log files	Set-Content -Encoding UTF8 adds BOM	Use [System.IO.File]::WriteAllText() with UTF8Encoding($false)

---

Option C — WSL (Full Native Compatibility)

Prerequisites: WSL2 installed with Ubuntu. This is the only approach that
makes rtk init --show report all [ok] with no warnings, because RTK runs
its own installer via WSL and generates the integrity hash for the real
rtk-rewrite.sh bash script.

The key challenge: Windows $PATH breaks WSL bash

When WSL inherits the Windows environment, paths like
C:\Program Files (x86)\... become /mnt/c/Program Files (x86)/.... The
parentheses are valid bash syntax — (x86) is interpreted as a subshell
expression — causing:

bash: syntax error near unexpected token `('

The fix is env -i: start WSL with a completely empty environment, then
explicitly set only what bash needs.

Step 1 — Install RTK inside WSL

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

Step 2 — Install jq inside WSL

wsl -u root bash -c 'apt-get install -y jq'

Step 3 — Run rtk init -g targeting the Windows home directory

WSL mounts C: at /mnt/c. Override HOME so RTK installs into the Windows
~/.claude/ directory instead of the WSL home:

wsl bash -c 'HOME=/mnt/c/Users/<YOUR_USERNAME> /home/<WSL_USER>/.local/bin/rtk init -g --auto-patch'

This creates:

• ~/.claude/hooks/rtk-rewrite.sh — the real bash hook script
• ~/.claude/hooks/.rtk-hook.sha256 — integrity hash (what silences the warning)
• ~/.claude/RTK.md — slim RTK awareness file
• Updates ~/.claude/CLAUDE.md with @RTK.md reference

Step 4 — Patch settings.json with env -i

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "wsl env -i PATH=/home/<WSL_USER>/.local/bin:/usr/bin:/bin HOME=/home/<WSL_USER> bash /mnt/c/Users/<YOUR_USERNAME>/.claude/hooks/rtk-rewrite.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Why env -i? Prevents Windows $PATH (with Program Files (x86)) from
being inherited by WSL, which would crash bash with a syntax error on the
parentheses.

Step 5 — Verify

rtk init --show

Expected (all green, no warning):

[ok] Hook: C:\Users\<YOUR_USERNAME>\.claude\hooks\rtk-rewrite.sh (exists)
[ok] RTK.md: C:\Users\<YOUR_USERNAME>\.claude\RTK.md (slim mode)
[ok] Integrity: hook hash verified
[ok] Global (~/.claude/CLAUDE.md): @RTK.md reference
[ok] settings.json: RTK hook configured

Step 6 — Test end-to-end

$json = '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"git status"}}'
$json | wsl env -i PATH=/home/<WSL_USER>/.local/bin:/usr/bin:/bin HOME=/home/<WSL_USER> bash /mnt/c/Users/<YOUR_USERNAME>/.claude/hooks/rtk-rewrite.sh

Expected:

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

---

Common Gotchas (All Approaches)

Project hooks override global hooks

Claude Code does not merge hooks. If a project has its own PreToolUse in
.claude/settings.json, it completely replaces the global one — RTK
silently disappears for that project.

Fix: duplicate the RTK hook entry in each project-level settings.json
that declares its own hooks.

permissions.allow for rewritten commands

If defaultMode is not bypassPermissions, add a rule to avoid a permission
prompt on every rewritten command:

"permissions": {
  "allow": ["Bash(rtk *)"]
}

---

Updating RTK in the Future

Option A (Git Bash)

Re-download the hook script (Step 1) to get the latest version.

Option B (PowerShell)

No update needed — the PowerShell script calls rtk rewrite at runtime, so it
picks up new rewrite rules automatically with each RTK binary update.

Option C (WSL)

# Update RTK binary in WSL
wsl bash -c 'curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh'

# Reinstall hook + regenerate integrity hash
wsl bash -c 'HOME=/mnt/c/Users/<YOUR_USERNAME> /home/<WSL_USER>/.local/bin/rtk init -g --auto-patch'

---

What Native Support Could Look Like

For rtk init -g to work natively on Windows, src/hooks/init.rs would need
a #[cfg(windows)] path that auto-detects the available runtime and picks the
best approach:

#[cfg(windows)]
fn run_default_mode(...) -> Result<()> {
    if wsl_available() {
        install_via_wsl(...)   // Option C: full compatibility
    } else if git_bash_available() {
        install_via_git_bash(...)  // Option A: simplest
    } else {
        install_powershell_hook(...)  // Option B: no deps
    }
}

A --wsl flag on rtk init -g could also make the WSL approach explicit and
opt-in for users who prefer it.

Success

[caiomioto2]

thanks that worked here