hook-debugging

What problem does it solve?

Claude Code hook debugging is a structured method to identify why a hook does not fire in a real session, isolating issues from startup failures, stdin handling, or import errors.

Core Features & Use Cases

• Canary-based startup verification to confirm the hook process is actually invoked.
• File-based logging to capture diagnostics across runs and environments.
• Manual stdin testing and subprocess wrappers to validate inputs and execution paths.
• A comprehensive diagnostic checklist guiding step-by-step investigation during debugging.
• Clear guidance to avoid creating hooks or debugging known Claude Code bugs.

Quick Start

Run the canary test to verify the hook starts, then review logs and perform a manual stdin test to reproduce and diagnose the issue.