Claude Code Hooks Not Working? Mine Ran 130,193 Times

A hook I registered on ten events had zero records in my transcripts. Not a failure, not an error line, nothing at all. I had 2,902 transcript files on disk covering 2,867 sessions, and a full-corpus scan turned up 130,193 hook records without a single one belonging to that hook.

It was running the whole time. Finding out how it hides took a controlled experiment, and the answer generalizes: the surface you are looking at almost certainly under-reports your hooks.

A silent hook and a loud hook, same event, same run

I wrote two shell scripts and registered both on PreToolUse with a * matcher. Each appends a nanosecond timestamp to a log file that Claude Code knows nothing about, so the log is the ground truth. The only difference is that one prints a JSON line on the way out and one prints nothing.

# silent.sh
#!/bin/sh
cat >/dev/null
echo "$(date +%s%N) SILENT fired" >> /tmp/hooklab/exp/proof.log
exit 0

# loud.sh — identical plus one line
printf '{"continue":true,"suppressOutput":true}\n'

I passed the config with --settings so my real ~/.claude/settings.json stayed untouched, and asked for exactly one ls:

claude -p "Run exactly one command: ls /tmp/hooklab/exp. Then reply DONE." \
  --settings /tmp/hooklab/exp/settings.json \
  --dangerously-skip-permissions --output-format json

Both lines landed in proof.log. Both hooks ran. The transcript recorded loud.sh as hook_success | PreToolUse:Bash | exit 0 | dur 548, and for silent.sh it recorded nothing. Not an empty record, not a zero-duration record. The file has no evidence that a second hook exists.

One run, three surfaces, three different counts

So I ran the same prompt three more times with different observability flags on. Eighteen hook processes execute in that run once plugins are counted, and every surface reports a different number of them.

Surface	Hook runs visible	Share of 18
--include-hook-events with --output-format stream-json	18	100%
--debug log	13	72%
transcript .jsonl attachments	11	61%
/hooks in a headless run	unavailable	0%

The event feed emits 18 hook_started records and 18 matching hook_response records, every one carrying exit_code 0 and outcome success. Five of those responses have an empty stdout. Those five are exactly the five the transcript dropped. The other two missing records were UserPromptSubmit hooks that did print JSON and were still not written to the transcript, which I cannot fully explain: the corpus does hold 339 UserPromptSubmit hook records, so the omission is not absolute.

Hooks are logged by their output, not by their execution

The mechanism shows up in the debug log format. Every hook line there is keyed on what the process printed:

[DEBUG] "Hook SessionStart:startup (SessionStart) success:\n{\"continue\":true,\"suppressOutput\":true}\n"

There is no line for the command, the path, or the exit status on its own. Grepping 380 debug lines for silent.sh returns nothing, and grepping for loud.sh also returns nothing, because the log never names either script. It names the event and quotes the output. A process that prints nothing produces no line to key.

The hooks reference states the routing rule plainly: a successful hook's stdout is never shown in the transcript and is recorded in the debug log. What the sentence does not say is that a hook with no stdout is recorded nowhere, and that the recording is what your eyes are looking for when you go checking whether the thing fired. The same page notes that suppressOutput is accepted but has no effect, which fits: output routing is doing the work that field appears to promise.

The debug filter removes the lines you wanted

My first debug run used --debug hooks and produced 380 lines, 73 of them about MCP servers. The CLI reference explains why: the filter binds only in the = form; a space-separated filter enables debug mode without filtering. So I had turned debug on and filtered nothing.

Fixing it made things worse in a useful way. --debug=hooks gives 43 clean lines with zero MCP noise, and zero Hook … success lines. Every line in the filtered output is from the output-parsing path, and the arithmetic is exact: 13 hooks that printed something, three lines each, plus four registry lines. The category named after hooks logs the parsing of hook output, so filtering to it removes the closest thing to an execution record and keeps the part that only exists when there is output to parse.

The documented way to check does not exist for unattended runs

The docs point at the /hooks menu as the read-only browser for confirming which hooks are registered and which settings file each came from. In a headless run it answers in 16 milliseconds:

$ claude -p "/hooks" --output-format json
subtype success | num_turns 0 | cost 0 | duration_ms 16
result: "/hooks isn't available in this environment."

That result cost nothing and returned nothing, which is a shape I have hit before in the opposite direction. Reading the remaining usage limit from a script turned out to work headless after I had written that it could not, and the auto-compact threshold reads fine headless too. So the rule is not that slash commands are closed to unattended fleets. It is that each one has to be tried, and this one is closed.

What the recorded runs cost

The corpus scan covers 2,902 transcript files, 245,272 records and 654.5 MiB across 2,867 sessions, from 2026-06-16 to 2026-08-15, on versions 2.1.183 through 2.1.227. In it, 130,193 hook records, 102,743 of them carrying an exit code, and every single one of those exit codes is 0. Across 301 stop_hook_summary records the hookErrors array is empty every time. The total wall time those records account for is 19,682,398 ms, or 5.47 hours.

The interesting part is where that time goes. stop_hook_summary is the only place per-hook timings sit side by side on the same event, and my three hook sources happen to use three different runtimes:

Runtime	n	p50 ms in Claude Code	min	Standalone no-op
/bin/sh script	184	23	11	3.9 ms
compiled binary	290	41	29	—
node script (three of them)	301 each	121, 123, 130	99	37.9 ms

On this Mac mini, node -e '' takes 37.4 ms before any hook code runs, and the real plugin entry point measures 92.5 ms standalone against 138 ms inside Claude Code. The comparison is confounded, because these three hooks do different work; the standalone benchmark is what isolates the floor. A shell hook that does nothing costs 3.9 ms and a node hook that does nothing costs 37.9 ms, and that gap is charged on every tool call. My busiest hook name is PostToolUse:Bash at 32,469 records.

One sentence, 1.3 MB

Hooks also spend context, and that ledger is easier to read. Across the corpus, 27,448 injections put 3,623,009 bytes of text into conversations, drawn from 1,085 distinct strings. The single most-injected string is one sentence of advice, 117 bytes long, delivered 11,095 times for a total of 1,298,115 bytes. One sentence is 35.8 percent of everything my hooks have ever said to me.

Per session the median is modest, at 7 hook runs and 540 injected bytes, and the tail is not: p90 is 72 runs, and the worst session took 10,361 hook runs and 274,999 injected bytes. That last number is real context, spent before the model reads anything I asked for, which puts it in the same budget as the token accounting I pulled out of these same transcripts.

How to actually tell

The reason this matters is that a hook which fails to fire and a hook which fires silently look identical in every surface most people check. In issue #2891, a user reported hooks not executing despite following the documentation, and the evidence offered was that no log files appeared in /tmp/claude_hooks_*.log. That method is the right one. The issue was closed with no visible explanation.

Three things worked for me, in order of how little they cost:

1. Make the hook write to a file it controls. One echo to a log path, outside Claude Code's view, converts the question from an observability problem into an ls.
2. Make the hook print something. printf '{"continue":true}' is enough to promote it from invisible to recorded in both the transcript and the debug log, at no behavioural cost.
3. For a real audit, run --output-format stream-json --include-hook-events --verbose. The docs are explicit that the flag requires --output-format stream-json, and it was the only surface that matched my ground truth.

I have written before about a scheduled job that died silently for 20.6 hours, where silence meant failure. This is the mirror image, and it is the more annoying one, because here silence means success and the instinct it trains is to go rewrite a hook that was working. The fix in both cases is the same: do not let anything important report only through a channel you have not checked can carry it.

The corpus figures come from a scan of ~/.claude/projects/**/*.jsonl on one Mac mini running my own fleet, 16 project directories, 2026-06-16 to 2026-08-15. That is one machine's history and not a survey of Claude Code users. Claude Code deletes session transcripts on a 30-day schedule I measured separately, so the window is what survived rather than everything that happened, and 130,193 is a lower bound by the same argument this post makes: the controlled run showed the transcript recording 11 of 18 runs. Durations are Claude Code's own durationMs values, not independently timed by me, and four of them exceed 10 seconds with a maximum of 1,655,231 ms on a PreToolUse hook, which is longer than the documented 600-second default command timeout and which I cannot explain. I never observed a hook error in the corpus, so I cannot describe what a failure looks like in these surfaces. The runtime table mixes hooks doing different work; only the standalone benchmark isolates startup. The corpus also spans two different hook configurations, one replaced around 2026-08-10. All four controlled runs used version 2.1.227 and wrote only to /tmp/hooklab, with production settings passed over via --settings. Quotations are from the Claude Code hooks reference and CLI reference, read on 2026-08-15.