MCPInstall

debug-hooks

by parcadeiCode Quality & Workflow

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

Installs
499
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/parcadei/continuous-claude-v3 --skill debug-hooks
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads debug-hooks automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

4. Test Hook Manually

# 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

5. Check for Silent Failures

If using detached spawn with stdio: 'ignore':

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

Fix: Add temporary logging:

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

6. Rebuild After Edits

If you edited TypeScript source, you MUST rebuild:

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

Source edits alone don't take effect - the shell wrapper runs the bundled .mjs.

Common Issues

SymptomLikely CauseFix
Hook never runsNot registered in settings.jsonAdd to correct event in settings
Hook runs but no outputDetached spawn hiding errorsAdd logging, check manually
Wrong session IDUsing "most recent" queryPass ID explicitly
Works locally, not in CIMissing dependenciesCheck npx/node availability
Runs twiceRegistered in both global + projectRemove duplicate

Debug Checklist

  • Outputs exist? (ls -la .claude/cache/)
  • Registered? (grep -A10 '"hooks"' .claude/settings.json)
  • Files exist? (ls .claude/hooks/*.sh)
  • Bundle current? (ls -la .claude/hooks/dist/)
  • Manual test works? (echo '{}' | ./hook.sh)
  • No silent failures? (check for stdio: 'ignore')

Source Sessions

Derived from 10 sessions (83% of all learnings):

  • a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c

FAQ

What does the debug-hooks skill do?

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

How do I install debug-hooks?

Run npx skills add https://github.com/parcadei/continuous-claude-v3 --skill debug-hooks in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debug-hooks/ (personal) or .claude/skills/debug-hooks/ (project).

Which AI agents can use debug-hooks?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is debug-hooks safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains debug-hooks?

It is published by parcadei in parcadei/continuous-claude-v3. It has 499 recorded installs.

More from parcadei/continuous-claude-v3

View all →

discovery-interview

parcadei/continuous-claude-v3

Deep interview process to transform vague ideas into detailed specs. Works for technical and non-technical users.

4.1K installs

premortem

parcadei/continuous-claude-v3

Identify failure modes before they occur using structured risk analysis

886 installs

math

parcadei/continuous-claude-v3

Unified math capabilities - computation, solving, and explanation. I route to the right tool.

Education & Science876 installs

github-search

parcadei/continuous-claude-v3

Search GitHub code, repositories, issues, and PRs via MCP

AI & Agents732 installs

dead-code

parcadei/continuous-claude-v3

Find unused functions and dead code in the codebase

Code Quality & Workflow730 installs

refactor

parcadei/continuous-claude-v3

Code refactoring workflow - analyze → plan → implement → review → validate

Code Quality & Workflow621 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs