patch
Skill50 starsChanged 4 months agoMITView on GitHub
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.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- jmusick/skillstheir own version, first seen Nov 8, 2026
- wheslleyrimar/BuildCLI-Agentstheir own version, first seen Oct 22, 2026
- air-gapped/skillstheir own version, first seen Oct 19, 2026
- krixon/skillstheir own version, first seen Oct 11, 2026
- scadastrangelove/rust-in-peacetheir own version, first seen Aug 3, 2026
- anthropics/defending-code-reference-harnesstheir own version, first seen Jul 16, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- anthropics/defending-code-reference-harness★ 7.5ksame name
- scadastrangelove/rust-in-peace★ 25same name
- stefanwebb/named-pipes★ 15same name
- Megaprompting/torque-loop★ 10same name
- air-gapped/skills★ 6same name
- wheslleyrimar/BuildCLI-Agents★ 3same name
- IvandoNascimento/skills★ 1same name
- krixon/skills★ 1same name
- enigmatic-saini/AI_WAY_OF_BUILDING_V1★ 0same name
- jmusick/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- AGENTS.mdAGENTS.md
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 98
Still failing after a repair: read the plugin's _hooks/hooks.map.json and run claude --debug hooks.
“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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, a hook script, or the 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 script 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 hook entry whose target is the interpreter name instead of the script | 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 .cmd (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 has no entry in the hook map |
wrapper_broken | A hook entry names a target that cannot run |
wrapper_orphan | A file in the hook directory that nothing dispatches |
cmd_missing | The dispatcher is missing from the hook directory, or older than the shipped one |
recursive_wrapper | A hook script 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 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: read the plugin's
_hooks/hooks.map.jsonand runclaude --debug hooks. If the entry runs a shell script, confirm Git Bash atC:\Program Files\Git\bin\bash.exe, or setWH_BASH_EXEfor a non-standard install. - 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-pluginsapplies it (CASE-13/26).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.