hook-debugging

To debug Claude Code hooks that fail to run, you can use a structured diagnostic workflow involving canary tests, file-based logging, and manual stdin testing to isolate startup, import, or input handling failures.

A Claude Code hook might not fire due to startup failures, incorrect stdin handling, or import resolution errors. Running a canary test verifies if the hook process is actually invoked during the session.

The best way to capture diagnostics for hook debugging across environments is file-based logging, which records execution details across runs to help reproduce and fix hook issues reliably.

You can test stdin handling for Claude Code hooks by performing manual stdin tests and using subprocess wrappers to validate inputs and trace execution paths before applying fixes.

No, you should not create new hooks while debugging Claude Code hook issues. Safe diagnostics limit debugging to known, non-production steps using a structured checklist to avoid altering the environment.

Yes, hook debugging works for isolating import resolution errors by combining canary-based startup verification and subprocess wrappers to identify where the hook process fails during execution.