Win-Hooks Diagnostics

Diagnose and fix Claude Code plugin hook compatibility issues on Windows.

Common Error Patterns

"JSON Parse error: Unrecognized token ''" / ":: command not found" / "#!/bin/bash: No such file or directory" / "<<(을)를 지정된 경로를 찾지 못했습니다"

Root cause: UTF-8 BOM (EF BB BF) in any hook file. In hooks.json it causes JSON parse errors; in

run-hook.cmd

it breaks bash's

:

builtin AND it pushes the leading

:

off line-start so cmd.exe stops recognizing it as a label and instead parses the polyglot's

<<

heredoc opener as redirection (mojibake:

<<��(��) ������� �ʾҽ��ϴ�

); in wrapper scripts it breaks shebang parsing. Typically caused by Windows editors or PowerShell

Out-File

. Fix: Run

/win-hooks:fix

—

verify --fix

strips BOM from every file in

hooks/

,

_hooks/

, and any file referenced from

hooks.json

(e.g.,

scripts/run-hook.cmd

shipped by ralph-loop).

"Hook load failed: JSON Parse error"

Root causes (check in order):

1. UTF-8 BOM in hooks.json
2. CRLF line endings causing parser issues
3. Corrupted hooks.json from interrupted patching
4. Invalid JSON syntax from bad text replacement

Fix: Run

/win-hooks:fix

which runs the full pipeline including

verify --fix

.

"SyntaxError" from python3/node on a .py/.js hook file

Root cause: Plugin ships bash wrapper scripts with

.py

/

.js

extension that call the interpreter on themselves (e.g.,

pretooluse.py

is

#!/bin/bash

but contains

python3 pretooluse.py

). Python/Node can't parse bash syntax. Fix: Run

/win-hooks:fix

—

verify --fix

disables recursive wrappers with

exit 0

.

"No such file or directory" for hook command

Root cause: Hook references a

.sh

script or bare command that doesn't exist on Windows. Fix: Run

/win-hooks:fix

to create polyglot wrappers.

"MODULE_NOT_FOUND" in Node.js hooks

Root cause: Windows backslash paths in

settings.json

hook commands get mangled during execution — backslashes are interpreted as escape characters, producing paths like

Userssmsme.configaincreport-usage.js

. Fix: Run

/win-hooks:fix

which converts

C:\...

to

C:/...

in settings.json hooks via

fix-backslash-paths

.

"'node' is not recognized as an internal or external command" / "'node'은(는) 내부 또는 외부 명령... 아닙니다" on Stop/SessionStart hooks

Root cause:

settings.json

hook command starts with a bare interpreter (

node

,

python

,

python3

,

npx

,

npm

) that's on Git Bash's PATH but not resolvable by cmd.exe at hook launch. Error text may appear CP949-garbled (e.g.

'node'��(��) ���� �Ǵ� �ܺ� ����...

). Note: the similar-looking

<<(을)를 지정된 경로를 찾지 못했습니다

(mojibake

<<��(��) ������� �ʾҽ��ϴ�

) is a different error — that one is BOM-corrupted polyglot wrapper (see the BOM section above). Fix: Run

/win-hooks:fix

—

fix-bare-commands

rewrites the command to a quoted absolute path like

"C:/Program Files/nodejs/node.exe" <script>

.

Why Hooks Break on Windows

Most Claude Code plugins are developed on Unix. Their hooks use:

• .sh

  scripts called directly (cmd.exe cannot execute these)
• Bare Unix commands not in Windows PATH (e.g.,

  semgrep

  ,

  shellcheck

  )

• ${CLAUDE_PLUGIN_ROOT}

  path with

  .sh

  extension (triggers Claude Code's auto-detection)
• Unix-specific shell syntax (

  $(...)

  , pipes, etc.)

Diagnosis Procedure

Step 1: Identify Platform

Check that platform is

win32

. If not, this skill does not apply.

Step 2: Find win-hooks install path

sed '1s/^\xEF\xBB\xBF//' ~/.claude/plugins/installed_plugins.json | awk '
  /win-hooks/ { found=1 }
  found && /"installPath"/ {
    sub(/.*"installPath"[[:space:]]*:[[:space:]]*"/, "")
    sub(/".*/, "")
    print
    exit
  }
' | sed 's/[\\][\\]*/\//g'

Save the output path as PLUGIN_ROOT.

Step 3: Run health check

bash "<PLUGIN_ROOT>/scripts/verify"

This detects:

Issue Type	Meaning
bom	UTF-8 BOM in any hook file (hooks/, _hooks/, or any file referenced from hooks.json)
json_invalid	hooks.json is not valid JSON
json_crlf	CRLF line endings in hooks.json
wrapper_missing	Patched hook references nonexistent wrapper script
cmd_missing	_hooks/run-hook.cmd is missing
recursive_wrapper	Bash wrapper (.py/.js) calls python3/node on itself
backslash_path	settings.json hook command has Windows backslash paths
bare_command	settings.json hook command uses bare interpreter not resolvable by cmd.exe

Step 4: Run incompatibility scanner

bash "<PLUGIN_ROOT>/scripts/find-incompatible"

Step 5: Report Findings

Present a table:

| Plugin | Issue | Detail | Status |
|--------|-------|--------|--------|
| name   | type  | info   | OK/FIX |

Fix Procedure

Automatic (recommended)

bash "<PLUGIN_ROOT>/hooks/patch-all"

This runs the full pipeline:

1. find-incompatible

   → detects incompatible hooks

2. apply-patches

   → creates wrappers, patches hooks.json (sanitizes BOM/CRLF, validates JSON)

3. verify --fix

   → auto-repairs any remaining encoding issues

Manual repair for specific files

For BOM/CRLF issues only:

bash "<PLUGIN_ROOT>/scripts/verify" --fix

For restoring a broken hooks.json from backup:

cp <plugin>/hooks/hooks.json.bak <plugin>/hooks/hooks.json

Then re-run patch-all.

Hook Event Types

Any of these can have incompatible commands:

Category	Events
Session	SessionStart, SessionEnd, InstructionsLoaded
User Input	UserPromptSubmit
Tools	PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest
Agents	SubagentStart, SubagentStop, Stop, TeammateIdle, TaskCompleted
Context	PreCompact, PostCompact, ConfigChange
Integration	Notification, Elicitation, ElicitationResult
Worktree	WorktreeCreate, WorktreeRemove

Automatic Prevention

The win-hooks plugin runs its patcher at every SessionStart. If you install or update a plugin, simply restart Claude Code - the patcher will detect and fix new incompatibilities automatically.

Rollback

# Restore a plugin's original hooks.json
cp <plugin>/hooks/hooks.json.bak <plugin>/hooks/hooks.json

Troubleshooting

Hook still errors after patching:

• Check if Git Bash is installed at

  C:\Program Files\Git\bin\bash.exe

• Verify the wrapper script has correct content:

  cat <plugin>/_hooks/<wrapper-name>

• Run with debug:

  claude --debug hooks

  to see hook execution details

python3 not found (other plugins):

• win-hooks automatically copies

  python.exe

  →

  python3.exe

  if

  python3

  is missing
• If Python is not installed at all, plugins that require Python will still fail

Plugin update overwrites fix:

• This is expected. Restart Claude Code and win-hooks will re-patch automatically.