Debug Hooks

When your hooks aren't firing or silently failing, this gives you a systematic debugging workflow instead of guessing. It walks through checking outputs first, verifying registration in settings.json, testing hooks manually with echo, and catching the silent failure pattern where detached spawn with stdio ignore hides all errors. The rebuild reminder is critical since editing TypeScript source does nothing until you rebundle to .mjs. Built from 10 actual debugging sessions, so the common issues table covers real problems like hooks registered twice or wrong session IDs. Saves you from the frustrating cycle of edit, wonder why nothing changed, repeat.

skills.sh installs: 501
GitHub stars: 3.9K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add parcadei/continuous-claude-v3 --skill debug-hooks --agent claude-code

Installs into .claude/skills of the current project.

Files

Debug Hooks

Systematic workflow for debugging Claude Code hooks.

When to Use

"Hook isn't firing"
"Hook produces wrong output"
"SessionEnd not working"
"PostToolUse hook not triggering"
"Why didn't my hook run?"

Workflow

1. Check Outputs First (Observe Before Editing)

# Check project cache
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/

# Check specific outputs
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/

# Check for debug logs
tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null

# Also check global (common mistake: wrong path)
ls -la ~/.claude/cache/ 2>/dev/null

2. Verify Hook Registration

# Project settings
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

# Global settings (hooks merge from both)
cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

3. Check Hook Files Exist

# Shell wrappers
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh

# Compiled bundles (if using TypeScript)
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs