debug-hooks
/debug-hooks
Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.
- Author
- kyuna0312 ↗
- Repository
- context_forge ↗
- Licence
- MIT
- Last repository change
- 06.09.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 06.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/validate-hooks.sh
What it does and when to use it
Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.
Triggers from the description
Original author description
Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.
How it works
- Common Hook Errors
- Full Diagnostic Procedure
- Fix Hook Schema Errors
- Remove Broken Hook
- LTX Schema
- Additional Resources
SKILL.md preview
---
name: debug-hooks
description: Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.
---
# Debug Hooks
Diagnose and fix Claude Code hook errors. Covers startup hook failures, broken MCP configs, missing dependencies, and invalid hook schemas.
## Common Hook Errors
### Error: `node:internal/modules/cjs/loader`
Cause: Hook script references a Node.js file that doesn't exist or has bad require/import.
Fix procedure:
1. Read `~/.claude/settings.json` — find `SessionStart` hooks
2. Locate the referenced script path
3. Check if file exists: `ls [script-path]`
4. If missing: recreate or remove the hook entry
5. If exists: check for bad `require()` paths inside
### Error: `startup hook error`
Cause: Hook command fails on session start.
Fix procedure:
1. Run the hook command manually in terminal
2. Read error output
3. Common causes:
- Missing npm package → `npm install [package]`
- Wrong node version → check `node --version`
- Bad file path → fix path in settings.json
- Permission denied → `chmod +x [script]`
### Error: Hook silently does nothing
Cause: Wrong event matcher or hook not registered.
Fix procedure:
1. Read `hooks/hooks.json` or `settings.json` hooks section
2. Verify event name is exact: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `SubagentStop`, `SessionEnd`, `UserPromptSubmit`, `PreCompact`, `Notification`
3. Verify matcher regex matches tool names
4. Test with `claude --debug` to see hook execution logs
## Full Diagnostic Procedure
```bash
# Step 1: Find all hook configs
find ~/.claude -name "hooks.json" 2>/dev/null
grep -r "hooks" ~/.claude/settings.json
# Step 2: Static-check each hook script (safe — no side effects)
bash -n [script].sh
node --check [script].mjs
# Step 3: Check node/python availability
which node && node --version
which python3 && python3 --version
# Step 4: Validate JSON syntax
python3 -m json.tool ~/.claude/settings.json
```
Run a hook script manually only when it's plausibly side-effect-free — a
hook may write files or hit a database; reproduce errors with static checks
first. Or run the bundled validator, which does all of the above:
```bash
CLAUDE_PLUGIN_ROOT=[plugin-dir] bash [plugin-dir]/skills/config/debug-hooks/scripts/validate-hooks.sh [config-file]
```
## Fix Hook Schema Errors
Valid hook entry structure:
```json
{
"SessionStart": [{
"hooks": [{
"type": "command",
"command": "bash $CLAUDE_PLUGIN_ROOT/scripts/my-hook.sh",
"timeout": 30
}]
}]
}
```
Common schema mistakes:
- Missing `hooks` array wrapper
- `type` not set to `"command"`
- Hardcoded absolute path instead of `$CLAUDE_PLUGIN_ROOT`
- Timeout as string instead of number
## Remove Broken Hook
To safely remove a broken hook from settings.json:
1. Read the file
2. Identify the broken hook entry
3. Show user the entry to remove
4. Confirm before editing
5. Remove entry and validate JSON
## LTX Schema
Emit structured output as LTX rows when reporting hook validation results.
```
@v1:hook|status|error|fix
```
| Field | Description |
|-------|-------------|
| `hook` | Hook identifier or script path |
| `status` | `ok`, `warn`, `error`, `missing` |
| `error` | Short error description or `-` if none |
| `fix` | Suggested fix command/action or `-` if none |
Example:
```
@v1:hook|status|error|fix
SessionStart:session-start.sh|ok|-|-
SessionStart:broken-hook.sh|error|file not found|recreate or remove hook entry
```
## Additional Resources
- **`references/hook-errors.md`** — Full error catalog with root causes and fixes
- **`scripts/validate-hooks.sh`** — Script to validate all hook configs
- **`agents/hook-error-fixer.md`** — for multi-step diagnosis, hand off to this agent instead of debugging inline
Files in this package (3)
- SKILL.md 4 KB
- references/hook-errors.md 3 KB
- scripts/validate-hooks.sh 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · kyuna0312/context_forge | 100 | MIT |
| vibeeval/vibecosystem | 100 | MIT |
Database snapshot: 13.11.2026 · package version 35f40ce12ae1 (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
- 100claude-code-hook-development
This skill should be used when the user asks to "create a hook", "add a hook", "write a hook", or mentions Claude Code hooks. Also suggest this skill when the user asks to "automatically do X" or "run X before/after Y" as these are good candidates for hooks. - 100write-hook
Use when Claude Code should do something by itself - at session start (`SessionStart`), on every prompt (`UserPromptSubmit`), or after each response (`Stop`) - or when that automation misbehaves. Symptoms: a hook script that runs but whose output never reaches the model, a… - 100hook-config-generator
Guide for adding a new real Claude Code hook to this framework as a .ps1/.sh pair, or .sh only for a silent advisory hook (registration in hooks/hooks.json as a shell-form chain, dispatch allowlist, tests, validation) — use when asked to create, generate, or extend a hook or quality gate. - 100working-with-claude-code
Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code - 100working-with-claude-code
Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code - 100create-hook
Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.