patch

name	patch
description	Diagnoses and fixes Claude Code / Codex plugin hook failures on Windows. Use this skill when: - a hook fails at SessionStart, UserPromptSubmit, PostToolUse, Stop, or any other event ("hook error", "훅 에러") - "Hook load failed", "JSON Parse error", or "Unrecognized token" appears while hooks load - the user asks to fix or patch hooks ("fix hooks", "훅 수정", "플러그인 호환성") - plugins were just installed or updated on Windows Do NOT use on macOS or Linux, where hooks work natively.
argument-hint	Optional host to check (claude or codex; omit for both)
allowed-tools	["Bash","Read"]

Patch Windows Plugin Hooks

Nearly every Windows hook failure has one of two causes: a .sh script cmd.exe cannot run, or a bare Unix command or interpreter that is not resolvable when the hook launches. One command fixes both. The tables below only name what is being seen; root-cause write-ups live in AGENTS.md as CASE-NN.

Recognizing the error

Symptom	Cause	CASE
JSON Parse error: Unrecognized token '' · :: command not found · #!/bin/bash: No such file or directory · <<(을)를 지정된 경로를 찾지 못했습니다 (mojibake <<��(��) ...)	UTF-8 BOM in a hooks.json, wrapper, or polyglot .cmd	CASE-01
Hook load failed: JSON Parse error	BOM, CRLF, or otherwise invalid hooks.json	CASE-01/02/05
SyntaxError from python3/node on a .py/.js hook file	a bash wrapper named .py/.js calling the interpreter on itself	CASE-22
No such file or directory for a hook command	a .sh script or bare command cmd.exe cannot run	CASE-07/08
MODULE_NOT_FOUND in a Node hook	a backslash C:\... path mangled in settings.json	CASE-20
'node' is not recognized... / 'node'은(는) 내부 또는 외부 명령... (mojibake 'node'��...)	a bare interpreter in settings.json not on cmd.exe's PATH	CASE-23
bash: .../<interpreter>: No such file or directory	a generated wrapper execs a bogus $PLUGIN_ROOT/<interpreter> target	CASE-24
Python was not found; run without arguments to install from the Microsoft Store	bare python3 resolving to the Store alias stub	CASE-09

The two CP949-garbled errors look alike but are not: <<(을)를 지정된 경로... is a BOM-corrupted polyglot wrapper (CASE-01), 'node'...내부 또는 외부 명령 is a bare interpreter in settings.json (CASE-23).

Run it

Confirm the platform is win32 first; on macOS and Linux there is nothing to repair and this skill does not apply.

node "$(cat ~/.claude/win-hooks/root)/bin/win-hooks.mjs" patch $ARGUMENTS

$ARGUMENTS is optionally claude or codex; with neither, both are done. If the root file is missing, win-hooks has never run - use npx @lilmgenius/win-hooks patch instead.

The command reports what it found, repairs whatever is not healthy, and re-reports to prove the result. Running it again on a healthy host changes nothing.

Read the output

Each host section lists how many hook files were scanned, then one line per problem. A section headed after repair is the proof pass; healthy means there is nothing left to do. The line prefixes are a closed vocabulary:

Line prefix	Meaning
incompatible	A hook that needs patching but has not been patched yet
bom	A UTF-8 BOM in a hook file (breaks JSON, shebangs, and cmd.exe)
json_crlf	CRLF line endings in hooks.json
json_invalid	hooks.json is not parseable
wrapper_missing	A patched hook points at a wrapper that no longer exists
wrapper_broken	A wrapper execs a target that cannot exist
cmd_missing	run-hook.cmd is gone from the wrapper directory
recursive_wrapper	A wrapper calls an interpreter on itself and loops
python3_stub	A python hook with no working interpreter installed
backslash_path	A settings.json hook command with Windows backslash paths
bare_command	A settings.json hook command cmd.exe cannot resolve

The last runs block is the heartbeat: one line per run with its duration and how many plugins were scanned and patched. It does not prove the hook ran, since a hand-run repair writes the same line. win-hooks heals at every SessionStart, announcing the result in one line so a clean run is distinguishable from a hook that never fired (CASE-32). It heals again silently on the next prompt after a plugin's hooks change (CASE-26). No lines at all means it never dispatched - usually the plugin is disabled, Git Bash is missing, or Node is not on PATH. On Codex there is one more cause: an upgrade changes the hook manifest, which invalidates the trust hash Codex recorded for it, and an untrusted hook is skipped with no message at all (CASE-33). Running patch by hand still repairs everything; re-trusting the hook is the user's call, never win-hooks'.

Report back

Summarize as a table: Plugin | Issue | Detail. A repair lands on disk, but the running session has already cached its hook config - tell the user to run /reload-plugins, or it applies in the next session (CASE-13).

Troubleshooting

• Still failing after a repair: confirm Git Bash at C:\Program Files\Git\bin\bash.exe (or set WH_BASH_EXE for a non-standard install), inspect the generated wrapper, and run claude --debug hooks.
• Only the Microsoft Store python3 stub is installed: install a real Python from python.org and restart.
• A plugin update reverted a repair: expected. win-hooks re-patches on the next prompt; /reload-plugins applies it (CASE-13/26).