# Hooks Doctor

> 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.

- Skill: `dataplat/hooks-doctor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dataplat/hooks-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dataplat/hooks-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dataplat (https://skillmd.com/u/dataplat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dataplat/hooks-doctor

---


# Hooks Doctor

Run the diagnostic and interpret it for the user:

```bash
bash .claude/hooks/hooks-doctor.sh
```

Present the results conversationally:

1. **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).
2. **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.
3. **Hook errors in the transcript** — if the user reports `hook error` messages, check:
   - Hook paths in [.claude/settings.json](../../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
4. **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.