rtk init --global does not install the hook on Windows

[ala-dojo]

Context: What rtk init --global does on Unix

When you run rtk init --global on macOS or Linux, RTK sets up a full system-level
integration with Claude Code. Four things happen:

1. ~/.claude/settings.json is updated with a PreToolUse hook entry:

   {
     "hooks": {
       "PreToolUse": [{
         "matcher": "Bash",
         "hooks": [{ "type": "command", "command": "~/.claude/hooks/rtk-rewrite.sh" }]
       }]
     }
   }

   This tells Claude Code: before executing any Bash command, run this hook first.

2. ~/.claude/hooks/rtk-rewrite.sh is created — the hook script that intercepts
   every command Claude Code is about to run, rewrites it through RTK if applicable,
   and returns the rewritten command transparently.

3. ~/.claude/RTK.md is created — a slim (10-line) awareness file describing
   RTK's meta commands (rtk gain, rtk discover, etc.).

4. ~/.claude/CLAUDE.md is updated with a reference @RTK.md, so Claude Code
   automatically loads the awareness file in every session.

The result: command rewriting is enforced at the system level. When Claude Code
issues git status, the hook intercepts it and silently rewrites it to rtk git status
before it ever executes. The LLM has no role in this — it happens unconditionally.

---

What happens on Windows

Running rtk init --global on Windows produces:

⚠️  Hook-based mode requires Unix (macOS/Linux).
    Windows: use --claude-md mode for full injection.
    Falling back to --claude-md mode.
✅ Created CLAUDE.md with rtk instructions
   Claude Code will now use rtk in all sessions

Only CLAUDE.md is updated. It receives a full ~137-line block of instructions
telling Claude to always prefix commands with rtk. Steps 1, 2, and 3 above are
skipped entirely — no hook, no settings.json update, no RTK.md.

This means on Windows, RTK relies entirely on the LLM reading the CLAUDE.md instructions
and choosing to follow them. There is no system-level enforcement. Claude may prefix
commands correctly most of the time, but it is not guaranteed — the model can forget,
deprioritize the instruction under long context, or simply not apply it consistently.

---

Why the hook cannot be installed on Windows

The hook mechanism has three Unix-specific dependencies that have no native Windows equivalent:

1. Bash — rtk-rewrite.sh is a bash script. Windows has no native bash shell.
   Git Bash and WSL exist, but they are not guaranteed to be present or configured
   in the environment where Claude Code runs hooks.

2. jq — the hook script uses jq to parse and build the JSON that Claude Code's
   PreToolUse protocol requires. jq is not available by default on Windows.

3. Unix file permissions (chmod 755) — the hook file must be executable.
   Setting executable permissions uses std::os::unix::fs::PermissionsExt, a Rust
   trait that is only available on Unix targets and does not compile on Windows at all.

Because of these three blockers, the hook installer in src/init.rs is gated behind
#[cfg(unix)]. The non-Unix code path warns and falls back to CLAUDE.md injection,
which is the only mechanism that works cross-platform today.

---

Work in progress

There is an open pull request actively working on a solution to this limitation:
PR #150 — Windows-native hook support

---

The reliability gap

Setup	Mechanism	Reliability
Unix rtk init --global	PreToolUse hook — OS-level interception	~100% enforced
Windows rtk init --global	CLAUDE.md instructions — LLM follows text	~70-80% best effort

Windows users get the awareness of RTK but not the enforcement. The token savings
RTK promises (60-90%) depend on consistent command rewriting — which is only
guaranteed in hook mode.

[skymat]

I hit this exact problem and built a working PowerShell workaround. Sharing it here in case it helps others (or informs PR #150).

The workaround

A PowerShell script as a PreToolUse hook that bypasses all three Unix dependencies (no bash, no jq, no POSIX permissions). PowerShell's ConvertFrom-Json / ConvertTo-Json replaces jq, and the script runs natively on Windows.

Hook script: ~/.claude/hooks/rtk-rewrite.ps1

# RTK PreToolUse hook — Windows PowerShell
[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
}

exit 0

Hook declaration in ~/.claude/settings.json

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "powershell -NoProfile -File '/c/Users/<user>/.claude/hooks/rtk-rewrite.ps1'"
      }
    ]
  }
]

Important: the script path must use Unix-style forward slashes inside single quotes. Bash eats backslashes silently.

Don't forget: permissions

Add "Bash(rtk:*)" to your permissions.allow list in settings.json. Without it, every rewritten rtk ... command triggers a permission prompt — defeating the purpose.

Watch out: project-level 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. You must duplicate the RTK hook entry in each project that declares its own hooks.

Tip: add a rule in your CLAUDE.md so the AI checks at session start and auto-injects the missing hook into the project's settings.

Still run rtk init --global

The hook handles mechanical rewriting (100% reliability). But rtk init --global injects useful CLAUDE.md instructions for commands RTK doesn't rewrite, plus rtk gain, rtk discover, etc. Both are complementary.

Results

After a full day of dev work (Next.js project, 200+ tests):

Total commands:    127
Tokens saved:      187.6K (93.9%)
Top: vitest run — 161K saved (98.6%) across 11 runs

Bugs I had to solve

6 Windows-specific bugs, all undocumented:

1. Backslashes in paths — bash strips \ from C:\Users\.... Fix: use '/c/Users/...' (Unix format, single quotes).
2. Hook JSON format changed — the old {"tool_input": {"command": "..."}} format no longer works. Must use hookSpecificOutput with permissionDecision and updatedInput.
3. PowerShell UTF-16 output — PowerShell 5 writes UTF-16LE by default. Claude Code expects UTF-8. Fix: [Console]::OutputEncoding = [System.Text.Encoding]::UTF8.
4. Project hooks override global hooks — Claude Code does NOT merge hooks. A project with its own PreToolUse completely replaces the global one. Must duplicate the RTK hook in each project's .claude/settings.json.
5. Async hooks don't receive stdin — "async": true closes the stdin pipe before the process starts. The hook must be synchronous.
6. BOM encoding in log files — Set-Content -Encoding UTF8 in PowerShell 5 writes UTF-8 with BOM. Fix: use [System.IO.File]::WriteAllText() with [System.Text.UTF8Encoding]::new($false).

Notes

This is obviously a temporary workaround until PR #150 lands native Windows support. But it works today, with 100% mechanical reliability (vs ~70-80% with CLAUDE.md-only mode).

Happy to help if this is useful for the PR.