Skip to content
Skills Library
AI & agents · Analysis

debug-hooks

/debug-hooks

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

Licence
MIT
Last repository change
08.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Original author description

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

How it works

  1. When to Use
  2. Workflow
  3. Common Issues
  4. Debug Checklist
  5. Source Sessions
Original SKILL.md headings · 119 lines, 431 words
SKILL.md preview
---
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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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'`:

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

**Fix:** Add temporary logging:

```typescript
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:

```bash
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

| 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 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

Versions

RepositoryScoreLicence
This page · vibeeval/vibecosystem100MIT
kyuna0312/context_forge100MIT

Identical content appears in 3 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 96ea1190e55c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90diagnosing-hooks
    Use when a DeepSeek Harness hook does not fire, fires twice, or is blocked by trust.
  • 100output-debug-workflow
    Debug Output SDK workflow issues. Use when user reports a workflow failing, erroring, hanging, producing wrong results, or asks to debug, troubleshoot, or investigate a workflow execution.
  • 100writing-hooks
    Guide for writing, configuring, and debugging Claude Code hooks. Use when adding, writing, or debugging hooks — including silent failures and permission errors.
  • 100diagnosing-hooks
    Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds…
  • 100debug
    Systematic debugging workflow: reproduce first, write failing test, then fix. Use when encountering bugs, unexplained errors, or unexpected behavior.
  • 82hooks-author
    Write or fix .devin/hooks.v1.json hook files. Use when creating Devin CLI hooks (tool-call guards, lifecycle events, commit hooks) or debugging why a hook isn't firing.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.