docs: CLAUDE_CODE_GIT_BASH_PATH required for hooks on Windows not clearly documented

Summary

When using Claude Code on Windows with Git-Bash, hooks fail with the error:

'$HOME' is not recognized as an internal or external command, operable program or batch file.

This is because Claude Code defaults to using cmd.exe for hook execution on Windows, which cannot interpret Unix shell syntax ($HOME, .sh files).

The Fix

Setting the environment variable CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe resolves the issue by telling Claude Code to use Git-Bash for all shell execution including hooks.

Documentation Gap

The current documentation mentions CLAUDE_CODE_GIT_BASH_PATH in the context of "portable Git installations" but does not clearly indicate that:

1. It is required for hooks to work on Windows when using Git-Bash
2. Without it, hooks execute via cmd.exe which breaks any hook using Unix shell syntax
3. Plugin hooks are also affected (e.g., session-start.sh hooks from plugins)

Suggested Documentation Update

Add to the hooks documentation (and/or Windows setup section):

Windows Users: If you're using Git-Bash, set the CLAUDE_CODE_GIT_BASH_PATH environment variable to your Git-Bash executable path (e.g., C:\Program Files\Git\bin\bash.exe). Without this, hooks will execute via cmd.exe which cannot interpret Unix shell syntax.

Environment

• OS: Windows 11
• Shell: Git-Bash (MINGW64)
• Claude Code: Latest version

Related

• Hooks feature documentation
• Windows setup/installation guide