Claude Code Windows Hooks Kit — hook-doctor + 8 tested PowerShell/Git Bash hooks

Your Claude Code hooks probably don't fire on Windows — and when they do, half of them fail open. This kit gives you a 60-second way to know, plus 8 hooks that were actually run on Windows PowerShell 5.1 and Git Bash before they were zipped.

hook-doctor (PowerShell 5.1 + bash)

• Finds ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json; flags hooks placed in ~/.claude.json or a standalone hooks.json (the docs: "There is no standalone hooks file for project or user config").
• Checks every handler against the guide's 21-row Windows failure-mode matrix: array matcher (rejects the whole file), lowercase bash, comma matcher on Claude Code < 2.1.191, Bash-only matcher where the PowerShell tool is the primary shell ("A hook that matches only Bash never fires there"), exec form pointing at a .cmd shim ("can't be spawned without a shell"), shell next to args ("Ignored when args is set"), if with &&, unquoted ${CLAUDE_PROJECT_DIR}, missing script, missing pwsh.exe with shell:"powershell" (issue #90077), allowManagedHooksOnly / disableAllHooks anywhere in the settings hierarchy (the real cause behind issue #88896), a workspace you never accepted the trust dialog for, and more.
• Dry-runs each hook by piping the events Claude Code would send: rm -rf ./build, Remove-Item -Recurse, git push --force, Write C:\proj\.env (backslashes, as the docs say Windows delivers), a file containing a fake ghp_ token, Stop with stop_hook_active true and false, Notification, SessionStart. Verdict per row: BLOCKS / ASKS / ALLOWS / FAIL-OPEN. Exit 1 on FAIL-OPEN, JSON report — drop it into CI.
• -Live: writes a canary PreToolUse hook into a temp project and runs claude -p. The only real answer to "do hooks fire on this box".
• Found and fixed while building: a powershell.exe child with no console decodes stdin with the OEM code page, so the docs' [Console]::In.ReadToEnd() pattern mangles CJK paths and chokes on a BOM. Every hook here reads raw UTF-8 bytes instead.

8 hooks, each as hook.ps1 and hook.sh, with README, exec-form fragment and if-rule fragment

1. block-destructive — rm -rf, Remove-Item -Recurse, rd /s, git push --force (not --force-with-lease), git reset --hard, git clean -fd, Format-Volume, diskpart, mkfs, fork bomb → deny + exit 2
2. protect-paths — .env*, *.pem, *.key, id_rsa*, /secrets/, /.git/ + your list; the regression test for issue #94256
3. secret-scan-on-edit — AWS / GitHub / Anthropic / OpenAI / Slack / Google / Stripe keys and PRIVATE KEY blocks in anything Claude writes → Claude is told to remove it
4. format-on-edit — prettier via node .../prettier.cjs (never the .cmd shim), ruff/black, gofmt; only if installed, never blocks
5. git-guard — no commits on main/master (deny or ask), ask before pushing with a dirty tree
6. test-gate-on-stop — runs your test command before Claude stops; honours stop_hook_active and the 8-block cap
7. notify-toast — a real Windows toast from PowerShell 5.1 (WinRT), not a MessageBox hiding behind the terminal
8. session-context-windows — tells Claude which shells exist, whether Git Bash is present, git state, and the encoding facts — honestly, including what it cannot change

Also included

• 3 presets (strict, balanced, wsl) wiring all 8 hooks; install.ps1 merges them in one command.
• GUIDE.pdf (8 chapters + zh-CN summary): how a hook resolves on Windows, the 21-row failure-mode matrix with the doc line or issue behind each row, exit codes and JSON, reading /hooks and the debug log, paths with spaces/CJK, version notes (2.1.47 … 2.1.257), encoding, presets and the -Live test.
• CHEATSHEET.pdf: one page, what runs where.
• A Claude Code skill (hook-doctor) that runs the doctor, explains each row and proposes the settings.json fix, with an unedited run transcript.
• Test suites (run-tests.ps1: 50 assertions, run-tests.sh: 26) so you can re-verify on your machine.

Honesty

Authored with Claude Code assistance; every hook and the doctor were executed on Windows 11 (Windows PowerShell 5.1 and Git Bash) against Claude Code v2.1.251 before release. The -Live canary was exercised up to the claude -p spawn on the build machine (a nested session that cannot log in); the dry-run path is covered by the automated tests. Issue #88896 ("PreToolUse hooks never fire on Windows") is described as what it turned out to be: closed by its own reporter, who traced it to an org policy (allowManagedHooksOnly in ~/.claude/remote-settings.json), not a Claude Code bug — the doctor checks that key. .sh hooks were run in Git Bash, not in WSL, in this release; the jq code path was not exercised on the build machine (no jq installed there), only the node and sed paths. Not affiliated with Anthropic. cc-safe-setup (yurukusa, MIT) is the large free Bash/WSL hook library and ships audit/fire.sh; this kit is the PowerShell-5.1-native set with interpreter/fail-open detection and a live in-session canary test.

Free tier

hook-doctor, block-destructive, protect-paths, notify-toast, the skill and the cheat sheet are MIT on GitHub: github.com/Suyann/claude-code-windows-hooks. The kit adds the other 5 hooks, the presets, the installer, the tests and the guide.

Refunds

If hook-doctor.ps1 cannot run on Windows 10/11 with Windows PowerShell 5.1 or PowerShell 7 and Claude Code 2.1.191+, message me within 7 days with the output for a full refund. Licence: single user, no resale.