Hook Diagnostics

hook-diagnostics

Surface Claude Code hook execution status, failures, and overhead from the current session.

Hook Sources

See references/hooks-registry.md for the full hook inventory, failure causes, and log path.

Checking Hook Status

To list currently loaded hooks, run in Claude Code:

/hooks

Reading Failure Logs

tail -n 10 $HOME/.claude/hooks/failures/failures.jsonl 2>/dev/null || echo "No failures recorded"

Each entry contains: timestamp, hook_name, exit_code, command, stderr.

Diagnosing a Specific Hook Failure

1. Identify the hook name from the failure log

2. Locate the hook script:

   ls $HOME/.claude/hooks/
   

3. Run the hook directly with sample input to reproduce the failure:

   echo '{"tool_name": "Bash", "tool_input": {"command": "echo test"}}' | \
     bash $HOME/.claude/hooks/<hook-name>.sh
   echo "Exit: $?"
   

4. For .nu hooks, run with nu instead of bash:

   echo '{"tool_name": "Edit", "tool_input": {"file_path": "/tmp/test.rs"}}' | \
     nu $HOME/.claude/hooks/<hook-name>.nu
   

5. Check stderr for error messages — most hooks write diagnostics to stderr

Identifying False Positives

Pre-commit and pre-push hooks use pattern detection (grep, regex) that can false-positive on test data, string literals, and documentation content.

When a hook blocks a commit unexpectedly:

1. Do NOT modify test/doc content to work around the hook
2. Run the hook chain with verbose output to identify the exact pattern match:

   bash -x $HOME/.claude/hooks/<hook-name>.sh < /dev/null 2>&1 | head -30
   

3. Add a minimum exclusion to the allowlist for the matched path
4. Never guess which hook is the culprit — identify it first

Hook Overhead

rtk gain

Hook execution time is not directly measured, but claude --debug shows hook timing in the debug output. The rtk gain command shows cumulative token savings from the rtk-rewrite.sh hook.

Common Hook Issues

Verifying Hook Registration

Hooks are registered in ~/.claude/settings.json. To verify:

# Read the hooks section of settings.json

Use the Read tool on $HOME/.claude/settings.json — never cat it (may contain sensitive values in redact-sensitive output).

Additional Resources

• references/hooks-registry.md — full hook inventory (global + plugin), common failure causes, failure log format and path