debug-hooks
installsforks
How to install debug-hooks?
parcadei/continuous-claude-v3/debug-hooks
$npx -y skills add parcadei/Continuous-Claude-v3 --skill debug-hooksSystematic hook debugging workflow. Use when hooks aren't firing, producing wrong output, or behaving unexpectedly.
SKILL.md
| 1 | # Debug Hooks |
| 2 | |
| 3 | Systematic workflow for debugging Claude Code hooks. |
| 4 | |
| 5 | ## When to Use |
| 6 | |
| 7 | - "Hook isn't firing" |
| 8 | - "Hook produces wrong output" |
| 9 | - "SessionEnd not working" |
| 10 | - "PostToolUse hook not triggering" |
| 11 | - "Why didn't my hook run?" |
| 12 | |
| 13 | ## Workflow |
| 14 | |
| 15 | ### 1. Check Outputs First (Observe Before Editing) |
| 16 | |
| 17 | ```bash |
| 18 | # Check project cache |
| 19 | ls -la $CLAUDE_PROJECT_DIR/.claude/cache/ |
| 20 | |
| 21 | # Check specific outputs |
| 22 | ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/ |
| 23 | |
| 24 | # Check for debug logs |
| 25 | tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null |
| 26 | |
| 27 | # Also check global (common mistake: wrong path) |
| 28 | ls -la ~/.claude/cache/ 2>/dev/null |
| 29 | ``` |
| 30 | |
| 31 | ### 2. Verify Hook Registration |
| 32 | |
| 33 | ```bash |
| 34 | # Project settings |
| 35 | cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"' |
| 36 | |
| 37 | # Global settings (hooks merge from both) |
| 38 | cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"' |
| 39 | ``` |
| 40 | |
| 41 | ### 3. Check Hook Files Exist |
| 42 | |
| 43 | ```bash |
| 44 | # Shell wrappers |
| 45 | ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh |
| 46 | |
| 47 | # Compiled bundles (if using TypeScript) |
| 48 | ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs |
| 49 | ``` |
| 50 | |
| 51 | ### 4. Test Hook Manually |
| 52 | |
| 53 | ```bash |
| 54 | # SessionEnd hook |
| 55 | echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \ |
| 56 | $CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh |
| 57 | |
| 58 | # PostToolUse hook (Write tool example) |
| 59 | echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \ |
| 60 | $CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh |
| 61 | ``` |
| 62 | |
| 63 | ### 5. Check for Silent Failures |
| 64 | |
| 65 | If using detached spawn with `stdio: 'ignore'`: |
| 66 | |
| 67 | ```typescript |
| 68 | // This pattern hides errors! |
| 69 | spawn(cmd, args, { detached: true, stdio: 'ignore' }) |
| 70 | ``` |
| 71 | |
| 72 | **Fix:** Add temporary logging: |
| 73 | |
| 74 | ```typescript |
| 75 | const logFile = fs.openSync('.claude/cache/debug.log', 'a'); |
| 76 | spawn(cmd, args, { |
| 77 | detached: true, |
| 78 | stdio: ['ignore', logFile, logFile] // capture stdout/stderr |
| 79 | }); |
| 80 | ``` |
| 81 | |
| 82 | ### 6. Rebuild After Edits |
| 83 | |
| 84 | If you edited TypeScript source, you MUST rebuild: |
| 85 | |
| 86 | ```bash |
| 87 | cd $CLAUDE_PROJECT_DIR/.claude/hooks |
| 88 | npx esbuild src/session-end-cleanup.ts \ |
| 89 | --bundle --platform=node --format=esm \ |
| 90 | --outfile=dist/session-end-cleanup.mjs |
| 91 | ``` |
| 92 | |
| 93 | Source edits alone don't take effect - the shell wrapper runs the bundled `.mjs`. |
| 94 | |
| 95 | ## Common Issues |
| 96 | |
| 97 | | Symptom | Likely Cause | Fix | |
| 98 | |---------|--------------|-----| |
| 99 | | Hook never runs | Not registered in settings.json | Add to correct event in settings | |
| 100 | | Hook runs but no output | Detached spawn hiding errors | Add logging, check manually | |
| 101 | | Wrong session ID | Using "most recent" query | Pass ID explicitly | |
| 102 | | Works locally, not in CI | Missing dependencies | Check npx/node availability | |
| 103 | | Runs twice | Registered in both global + project | Remove duplicate | |
| 104 | |
| 105 | ## Debug Checklist |
| 106 | |
| 107 | - [ ] Outputs exist? (`ls -la .claude/cache/`) |
| 108 | - [ ] Registered? (`grep -A10 '"hooks"' .claude/settings.json`) |
| 109 | - [ ] Files exist? (`ls .claude/hooks/*.sh`) |
| 110 | - [ ] Bundle current? (`ls -la .claude/hooks/dist/`) |
| 111 | - [ ] Manual test works? (`echo '{}' | ./hook.sh`) |
| 112 | - [ ] No silent failures? (check for `stdio: 'ignore'`) |
| 113 | |
| 114 | ## Source Sessions |
| 115 | |
| 116 | Derived from 10 sessions (83% of all learnings): |
| 117 | - a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
