debug-hooks

The debug-hooks skill provides a comprehensive, step-by-step diagnostic framework for developers working with the Continuous Claude hook architecture. When automation triggers, custom file tracking, or skill auto-activation behaviors fail, this tool guides the user through the essential verification layers of the Claude Code environment. It is designed for engineers and developers maintaining complex agent workflows who need to identify silent failures, configuration mismatches, or bundle synchronization issues within their .claude/hooks directory.

• Systematic diagnosis of hook execution failures including UserPromptSubmit, SessionEnd, and PostToolUse events.

• Verification of hook registration within project and global settings.json files.

• Inspection of internal file structures, including shell wrappers and bundled .mjs files created by esbuild.

• Manual testing capabilities for individual hooks using predefined JSON payloads to simulate tool triggers.

• Advanced troubleshooting for detached processes and common stdio: 'ignore' pitfalls that lead to hidden runtime errors.

• Automated reconciliation processes for ensuring source TypeScript files are correctly bundled into the active execution environment.

• Always start by inspecting the .claude/cache/ directory to verify that logs and learnings are being generated correctly before modifying configurations.

• Ensure all shell scripts are executable and that settings.json properly maps triggers to the correct script paths.

• Remember that editing TypeScript source files requires a manual rebuild using esbuild; changes will not reflect in the environment until the .mjs bundles are updated.

• If a hook appears to run but produces no output, check for detached spawn configurations that might be suppressing stderr.

• Use the provided checklist to ensure parity between development environments and local execution, particularly regarding node and npx dependencies.

• This tool is specifically intended for technical users managing the Continuous Claude ecosystem and should be utilized when standard agent behavior deviates from the expected workflow patterns.