| name | diagnose-hooks |
| description | Troubleshoot hook errors. Use when user sees 'PreToolUse hook error', 'PostToolUse error', or asks to 'diagnose hooks'. Identifies and fixes plugin hook failures. |
| version | 11.0.0 |
Diagnose Hook Errors
Troubleshoot Claude Code hook errors (PreToolUse, PostToolUse, etc.)
When to Use
- See "PreToolUse:* hook error" or "PostToolUse:* hook error"
- Hooks silently failing
- Plugin not working as expected
Diagnosis Steps
1. Check Python Alias (Windows)
python3 --version 2>&1
If not found:
cp "C:/Users/Marcus Gollahon/AppData/Local/Programs/Python/Python311/python.exe" \
"C:/Users/Marcus Gollahon/AppData/Local/Programs/Python/Python311/python3.exe"
2. Find Hooks Using python3
grep -r "python3" ~/.claude/plugins/marketplaces --include="*.json" 2>/dev/null
3. Check Enabled Plugins
grep -A 20 '"enabledPlugins"' ~/.claude/settings.json
4. Test Hook Manually
For a hook command like:
python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py
Test with:
cd ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/security-guidance
echo '{"tool_name":"Write","tool_input":{"file_path":"test.txt"}}' | python3 hooks/security_reminder_hook.py
5. Common Fixes
| Error | Fix |
|---|
python3 not found | Create alias (see step 1) |
ModuleNotFoundError | pip install <module> |
Permission denied | Check file permissions |
Hook timeout | Increase timeout in plugin.json |
Quick Disable
To disable a problematic plugin temporarily:
"security-guidance@claude-plugins-official": false
Then restart Claude Code session.
