A hook that "isn't working" usually means one of two very different problems: it isn't running at all, or it's running but not doing what you expect. Treating those as the same problem wastes time — here's how to tell them apart and fix each one.
Before touching anything related to Claude Code's configuration, run the hook script directly from your terminal with realistic input. If it doesn't behave correctly on its own — wrong output, crashes, wrong exit code — that's the actual bug, and no amount of adjusting the integration will fix it. This single step rules out the most common wasted-debugging path: assuming the problem is in how Claude Code calls the script when it's actually in the script itself.
Hooks that are meant to block an action typically signal pass/fail through the script's exit code — not through what got printed. A script can print a clear error message and still exit 0 (success) if that's not handled explicitly, which means the hook "ran," printed the right thing, and still let the action through. This is the single most common cause of "the hook detected the problem but didn't actually block anything."
# Wrong — prints an error but still exits successfully
echo "Error: forbidden file"
# (no explicit exit — defaults to the last command's status, often 0)
# Right — the failure is actually signaled
echo "Error: forbidden file" >&2
exit 1Add a temporary, unmistakable side effect to the script — appending a line to a log file, or writing a distinct marker somewhere you can check — then trigger the exact action you expect to fire it. If that marker never appears, the hook isn't attached to the event you think it is, which is a configuration problem, not a logic bug. This step alone prevents a lot of wasted time debugging script logic that was never actually running.
A script that isn't executable, has an incorrect shebang line, or assumes a working directory that isn't guaranteed can fail silently or behave inconsistently depending on where it's invoked from. These are boring, unglamorous causes — which is exactly why they're worth checking directly rather than assumed away in favor of a more interesting explanation.
This assumes you're already using hooks day to day. If you're just getting oriented, the Hooks overview covers what they are and when to reach for one.
Read Claude Code Hooks →Test the script directly from your terminal first, completely outside of Claude Code, with realistic input. If it doesn't behave correctly on its own, the problem is in the script, not the integration — fix that before looking anywhere else.
The most common cause is the exit code, not the logic. A script can print an error message and still exit with a success code if that's not handled explicitly — and hooks typically signal pass/fail by exit code, not by what got printed.
Add a temporary, obvious side effect — write a line to a log file, echo a distinct message — and trigger the action you expect the hook to respond to. If nothing shows up, the hook isn't firing for that event at all, which points at configuration rather than script logic.
Yes — a script that isn't executable, has an incorrect shebang line, or assumes a working directory that isn't guaranteed can all fail silently or behave unexpectedly. Verify these basics directly before assuming the problem is more complex than it is.