debug-hooks skill | PlugMCP

debug-hooks

by parcadei3.9k

Systematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly.

Install

Use withClaudeCursorCodex

The file stays in the publisher's repository. PlugMCP does not host or rewrite it.

Download skill .claude/skills/debug-hooks/SKILL.md on GitHub

Related skills

View all

Systematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly.

name: debug-hooks description: Systematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly. allowed-tools: [Bash, Read, Grep]

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

# SessionEnd hook
echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh

# PostToolUse hook (Write tool example)
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh

// This pattern hides errors!
spawn(cmd, args, { detached: true, stdio: 'ignore' })

const logFile = fs.openSync('.claude/cache/debug.log', 'a');
spawn(cmd, args, {
  detached: true,
  stdio: ['ignore', logFile, logFile]  // capture stdout/stderr
});

cd $CLAUDE_PROJECT_DIR/.claude/hooks
npx esbuild src/session-end-cleanup.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/session-end-cleanup.mjs

Symptom	Likely Cause	Fix
Hook never runs	Not registered in settings.json	Add to correct event in settings
Hook runs but no output	Detached spawn hiding errors	Add logging, check manually
Wrong session ID	Using "most recent" query	Pass ID explicitly
Works locally, not in CI	Missing dependencies	Check npx/node availability
Runs twice	Registered in both global + project	Remove duplicate

debug-hooks

Install

Related skills

name: debug-hooks description: Systematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly. allowed-tools: [Bash, Read, Grep]

Debug Hooks

When to Use

Workflow

1. Check Outputs First (Observe Before Editing)

2. Verify Hook Registration

3. Check Hook Files Exist

4. Test Hook Manually

5. Check for Silent Failures

6. Rebuild After Edits

Common Issues

Debug Checklist

Source Sessions