| name | hooks-doctor |
| description | Diagnose the Claude Code hook environment for this repo — which tools are present, what each absence disables, and how to fix it. Use when hooks error, block unexpectedly, or seem to do nothing. |
Hooks Doctor
Run the diagnostic and interpret it for the user:
bash .claude/hooks/hooks-doctor.sh
Present the results conversationally:
- All OK — say the hook environment is fully functional and list the active gates (style validation, read-before-edit, destructive-command guard, registration/TODO/verify Stop gates, codex auto-review).
- Something MISSING — explain what that specific absence disables (the script prints it) and give the one-line install fix. Every hook fails open, so a missing tool never breaks the session — it just silently removes that protection.
- Hook errors in the transcript — if the user reports
hook error messages, check:
- Hook paths in .claude/settings.json must use
"$CLAUDE_PROJECT_DIR" (hooks run in the session cwd, not the repo root — relative paths break)
- Line endings: hook scripts must be LF (enforced via
.gitattributes); CRLF causes bad interpreter on Linux
claude --debug hooks records each hook's exit code and stderr
- User wants to opt out — per-developer opt-outs, in increasing scope:
CLAUDE_CODEX_REVIEW=off / CLAUDE_STOP_VERIFY=off (env, per session)STOP_GUARD_MAX_BLOCKS=1 to shrink blocking budgets.claude/settings.local.json with {"disableAllHooks": true} (gitignored, personal)
Never suggest editing the checked-in .claude/settings.json to opt out — that changes the gates for every developer.
