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.

[sguryev]

I had to add -ExecutionPolicy Bypass in order to make it work.
"command": "powershell -NoProfile -ExecutionPolicy Bypass -File '/c/Users/<user>/.claude/hooks/rtk-rewrite.ps1'"

Also there is a workaround with GIT bash and jq tool installed here: #330 (comment)

[tphillips-ict]

This is quite frustrating, rtk is meant to be saving us tokens but every call on Windows produces "[rtk] /!\ No hook installed — run rtk init -g for automatic token savings". Suppress the warning if we can't install the hook on Windows.

[cobrabr]

For what it's worth, the way the configuration ends up looking like on Linux does work on Windows. Claude Code uses Git Bash on Windows, so .sh scripts run fine. If you set the hook up manually and create the .sh file under ~/.claude/hooks/, it will trigger properly. You can also remove the massive update it does to CLAUDE.md, create the RTK.md file manually (the contents of which you can find at https://github.com/rtk-ai/rtk/blob/master/hooks/claude/rtk-awareness.md) and just add the @RTK.md line to CLAUDE.md manually.

[seanwmodonnell-sudo]

** AI CODE** This worked for me - What fixed RTK for Windows Codex:

The Codex instruction path was already basically correct
C:\Users"USER".codex\AGENTS.md points to:

@C:\Users"USER".codex\RTK.md
and RTK.md exists. So the main problem was not a missing Codex RTK file.

RTK was installed and on PATH
Verified with:

rtk --version
Result:

rtk 0.35.0
The real blocker was RTK’s tracking database path
rtk gain originally failed because RTK could not open its SQLite DB. The default/user config DB path was outside the Codex sandbox’s writable area.

Fix was to set RTK’s database path to a writable workspace location:

[tracking]
database_path = '(where ever its installed.rtk\history.db'
in:

C:\Users"USER"\AppData\Roaming\rtk\config.toml
After that, rtk gain started working.

rtk test -d was the wrong command
Codex saw “always prefix commands with rtk” and turned shell builtin checks into:

rtk test -d ./src
But rtk test is RTK’s test-suite wrapper, not the POSIX shell test builtin.

Fix was to update:

C:\Users"USER".codex\RTK.md
with rules saying:

Use rtk proxy for shell builtins, PowerShell cmdlets, cmd builtins, and shell syntax.
Do not use rtk test -d or rtk test -f.
Windows bash was pointing to WSL, but WSL had no distro
On this machine:

where bash -> C:\Windows\System32\bash.exe
That is the WSL launcher, but:

wsl -l -v
showed no installed Linux distributions.

Git Bash was installed at:

C:\Program Files\Git\bin\bash.exe
So the fix was to tell Codex to use Git Bash explicitly:

rtk proxy C:\Progra~1\Git\bin\bash.exe -lc "test -d ./src && echo exists"
instead of plain:

bash -lc ...
rtk proxy is the Windows escape hatch
For PowerShell checks:

rtk proxy powershell -NoProfile -Command "Test-Path -LiteralPath './src' -PathType Container"
For Git Bash/POSIX checks:

rtk proxy C:\Progra~1\Git\bin\bash.exe -lc "test -d ./src"
For cmd builtins:

rtk proxy cmd /c "if exist .\src (echo exists) else (echo missing)"
Verification that it worked
Running:

rtk env
rtk gain --history
showed the command was tracked:

Total commands: 68
04-13 19:02 ▲ rtk env -99% (897)
Bottom line: the successful Windows Codex setup was not just “run rtk init.” It needed:

AGENTS.md -> absolute RTK.md path
RTK installed on PATH
RTK DB moved to a Codex-writable location
RTK.md updated to avoid rtk test -d
Git Bash used explicitly instead of WSL bash
rtk proxy used for shell builtins and PowerShell/cmd syntax

[fajarmf10]

Thanks @skymat for the PowerShell workaround, it pointed me in the right direction. I tried following your PS1 approach first but still hit "Hook outdated" on every call, plus the hook was silently not firing. Ended up going down the Git Bash path instead and had to solve two more undocumented Windows bugs to get it fully clean. Sharing the end-to-end tutorial in case it helps others, and as additional input for PR #150.

Environment

Item	Value
OS	Windows 11 Pro (10.0.26200)
Shell	Git Bash (MINGW64) — Claude Code spawns hooks via bash.exe on Windows
Claude Code	VS Code extension
RTK	v0.37.1, installed via cargo install --git https://github.com/rtk-ai/rtk (commit 5c9e1ac6)

rtk --version output:

rtk 0.37.1

cargo install --list | grep rtk:

rtk v0.37.1 (https://github.com/rtk-ai/rtk#5c9e1ac6):
    rtk.exe

What I tried first (and what went wrong)

Attempt 1 — rtk init -g --auto-patch

Still falls back to CLAUDE.md mode on 0.37.1, same as @iappwebdev reported in #502. PR #905 is not in this release yet, so the Windows gate remains.

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

Attempt 2 — @skymat's PowerShell workaround

Copied rtk-rewrite.ps1 and registered it in settings.json with -ExecutionPolicy Bypass (per @sguryev). Two silent failures:

• The PreToolUse block landed at the top level of settings.json (that is what the snippet in this thread shows). Claude Code ignores it there — it must be nested inside "hooks": { ... }. No error, no log, the hook just never fires.
• powershell -File '/c/Users/<your-username>/.claude/hooks/rtk-rewrite.ps1' — Git Bash-style forward-slash path passed directly to PowerShell. PowerShell does not reliably resolve that. C:\... works; mixed-style doesn't.

Once those were both fixed, the PS1 hook worked, but every single rtk invocation still printed [rtk] /!\ Hook outdated — run \rtk init -g` to update— becausertk init -g` never runs on Windows and so never writes the baseline hash or version tag.

Attempt 3 — Git Bash hook from issue #502

Used @san-tekart's bash script from issue #502. Hit the same Windows-specific bug:

• rtk rewrite "git status" on Windows exits with code 3 (because its own integrity check cannot find the baseline — chicken-and-egg). The issue's script has if [ $? -ne 0 ] ... exit 0, so the hook silently aborts even though stdout contains a correct rewrite.

Fix: guard on [ -z "$REWRITTEN" ] instead of exit code. The stderr warning is already suppressed by 2>/dev/null.

Final working setup

1. Hook script — ~/.claude/hooks/rtk-rewrite.sh

Save with LF line endings (CRLF breaks the heredoc). The # rtk-hook-version: 3 tag on line 2 is what RTK's hook_check::status() scans for — without it, version parses as 0 and RTK shows "Hook outdated" forever.

#!/bin/bash
# rtk-hook-version: 3
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//')

if [ -z "$COMMAND" ] || [[ "$COMMAND" == rtk\ * ]]; then
  exit 0
fi

REWRITTEN=$(rtk rewrite "$COMMAND" 2>/dev/null)
if [ -z "$REWRITTEN" ] || [ "$REWRITTEN" = "$COMMAND" ]; then
  exit 0
fi

REWRITTEN_ESCAPED=$(echo "$REWRITTEN" | sed 's/\\/\\\\/g; s/"/\\"/g')
cat <<ENDJSON
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"rtk: token-optimized","updatedInput":{"command":"$REWRITTEN_ESCAPED"}}}
ENDJSON
exit 0

2. Register in ~/.claude/settings.json

The hooks wrapper is mandatory. $HOME expansion works from Git Bash, no Windows-style path needed.

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

3. Write the baseline hash file

This is what Unix rtk init -g does automatically via integrity::store_hash(). On Windows we have to do it by hand. Without this file, rtk verify reports no baseline hash found.

HASH=$(sha256sum ~/.claude/hooks/rtk-rewrite.sh | awk '{print $1}')
printf '%s  rtk-rewrite.sh\n' "$HASH" > ~/.claude/hooks/.rtk-hook.sha256

Format is sha256sum -c compatible: <64-hex> rtk-rewrite.sh\n. If you ever edit the hook, recompute and overwrite — otherwise the next runtime integrity check will report Tampered.

4. Verify

$ rtk verify
PASS  hook integrity verified
      sha256:33f14f9f107188c250349ccb943a2426b6b9dea26f0899b80849f7d849fec3af
      C:\Users\<your-username>\.claude\hooks\rtk-rewrite.sh
145/145 tests passed

$ rtk rewrite "git status"
rtk git status

$ rtk gain
RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════
Total commands:    52
Input tokens:      359.8K

No [rtk] /!\ Hook outdated anywhere. Clean output.

5. End-to-end hook test (simulating what Claude Code pipes in)

$ echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"vitest run"}}' \
    | bash ~/.claude/hooks/rtk-rewrite.sh
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"rtk: token-optimized","updatedInput":{"command":"rtk vitest"}}}

Passthrough (no double-wrap) also works:

$ echo '{"tool_input":{"command":"rtk git status"}}' | bash ~/.claude/hooks/rtk-rewrite.sh
(empty output — correct)

Latency: ~175 ms per Bash tool call on my machine (cold rtk.exe start dominates). Fine for vitest/next build, pure overhead for git status. Net win on any output-heavy command.

Summary of the three undocumented Windows bugs

1. Schema placement. PreToolUse must be nested under "hooks": { ... }. Top-level is silently ignored.
2. rtk rewrite exits non-zero on Windows. The official-style hook script aborts on exit code. Guard on stdout emptiness instead.
3. No version tag + no baseline hash = permanent "Hook outdated". Add # rtk-hook-version: 3 to the script and write ~/.claude/hooks/.rtk-hook.sha256 by hand.

Items 2 and 3 are what PR #150 will presumably handle, but the manual recipe above is fully functional on 0.37.1 today.

[vinozganic]

For anyone landing here on Windows: I followed @cobrabr's manual pattern + @fajarmf10's exact hook script, everything looked correct per the docs, but Claude Code wouldn't actually run the hook. Every Bash call threw:

PreToolUse:Bash hook error
Failed with non-blocking status code: /usr/bin/bash: line 1:
C:UsersJakov.claudehooksrtk-rewrite.sh: command not found

All backslashes silently dropped. Took me a while to figure out: Claude Code on Windows dispatches hook commands through /usr/bin/bash -c, and bash interprets \U, \J, \., \h as escape sequences and eats them — turning C:\Users\Jakov\.claude\hooks\rtk-rewrite.sh into C:UsersJakov.claudehooksrtk-rewrite.sh.

The fix is just changing the command value in ~/.claude/settings.json from a Windows path to POSIX form:

"command": "/c/Users/Jakov/.claude/hooks/rtk-rewrite.sh"

Not C:\\Users\\..., not even C:/Users/... (might work via MSYS path conversion but I didn't trust it). After that the hook fires on every Bash call, including in projects that already have their own PreToolUse Bash hook. rtk just lives as a second entry in the same array alongside the existing one. Getting around 60% savings on mixed git/ls workloads now. Wasted half an evening assuming cmd.exe was the dispatcher and writing a .cmd wrapper before I clocked the bash-escape thing.

Hopefully this saves someone else the detour.

[vinozganic]

Quick question for anyone watching #1635: What's the cleanest way to actually know when the official Windows fix lands in a published release? Subscribing to the PR + the release notes feed, or is there a better channel?

And related: when it does ship and I run rtk init -g on the new version, will the installer detect and gracefully replace this kind of manual setup, or do I need to tear down ~/.claude/hooks/rtk-rewrite.sh + the global settings.json PreToolUse entry myself first to avoid ending up with duplicate hook entries?