Windows Support

This plugin is tested and supported on Windows, macOS, and Linux (Ubuntu).

On Windows, Claude Code runs hook scripts via Git Bash (MINGW64), which ships with Git for Windows. This provides a POSIX-compatible environment where the plugin’s bash scripts work correctly.

What works out of the box

Most GNU utilities that the plugin depends on are included with Git Bash:

Tool	Used for	Git Bash status
bash	Hook script execution	Included
mktemp	Atomic file writes	Included
date -u	UTC timestamps	Included (GNU date)
sed -E	Regex parsing	Included (GNU sed)
grep -E	Pattern matching	Included (GNU grep)
awk	Score calculations	Included (GNU awk)
wc, tr, cut, xargs	Text processing	Included

Required: jq

The one dependency not included with Git Bash is jq, a JSON processor used by all hook scripts for reading and writing game data.

Without jq: Most plugin skills (/guide:onboard, /guide:ask, /guide:migrate-to-claude) work normally. Game Mode hooks will silently skip tracking — no errors, but no usage data will be collected. When you run /guide:game-mode or /guide:level-up, Claude will detect jq is missing and show installation instructions.

Installing jq on Windows

Option 1 — Download to your user bin directory (Git Bash):

mkdir -p ~/bin
curl -sL https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-windows-amd64.exe -o ~/bin/jq.exe
chmod +x ~/bin/jq.exe

Git Bash includes ~/bin in PATH by default. Verify with:

jq --version

Option 2 — Chocolatey:

choco install jq

Option 3 — Ask Claude:

Just tell Claude: “install jq” — it will handle the download.

Installing jq on other platforms

Platform	Command
macOS	brew install jq
Ubuntu/Debian	sudo apt install jq
Fedora/RHEL	sudo yum install jq

Windows-specific adjustments

The plugin includes the following adjustments for Windows compatibility:

Path normalization

Claude Code on Windows provides file paths with backslashes (e.g., C:\Users\you\.claude\plans\file.md). The hook scripts normalize these to forward slashes before pattern matching, so features like plan-file detection work correctly on all platforms.

Affected file: hooks/scripts/track-usage.sh

Graceful jq fallback

All hook scripts check for jq availability before running. If jq is not installed, hooks exit silently with no error output. This ensures the plugin never disrupts your workflow — hooks install automatically with the plugin and should never produce unexpected errors.

Affected files: All scripts in hooks/scripts/

File locking

The plugin uses flock for file locking when it is available. If flock is unavailable (for example, in default Windows or macOS setups), locking is gracefully skipped. This is safe because hook invocations within a single Claude Code session are sequential, and the game data file is low-risk (worst case: a counter is off by one).

Affected files: All tracking scripts in hooks/scripts/

Troubleshooting

Symptom	Cause	Fix
Game mode shows zero counts after use	jq not installed	Install jq (see above)
Hook errors in terminal	Unexpected — hooks are designed to fail silently	Check jq --version; if missing, install it
Plan-file writes tracked as “editing” instead of “planning”	Path normalization issue	Update to latest plugin version

Platform test matrix

Platform	Shell	Status
Windows 11	Git Bash (MINGW64)	Tested
macOS	zsh / bash	Tested
Ubuntu Linux	bash	Tested