debug-hooks
/debug-hooks
Diagnozuje niedziałające hooki Claude Code: błędy hooka przy starcie, błędy loadera Node i hooki, które milczą, z wyłączeniem błędów serwerów MCP.
- Autor
- kyuna0312 ↗
- Repozytorium
- context_forge ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 06.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 3
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 06.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/validate-hooks.sh
Co robi i kiedy
Diagnozuje niedziałające hooki Claude Code: błędy hooka przy starcie, błędy loadera Node i hooki, które milczą, z wyłączeniem błędów serwerów MCP.
Wyzwalacze z opisu
Oryginalny opis (EN)
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.
Jak działa
- Common Hook Errors
- Full Diagnostic Procedure
- Fix Hook Schema Errors
- Remove Broken Hook
- LTX Schema
- Additional Resources
Podgląd SKILL.md
---
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
Pliki w paczce (3)
- SKILL.md 4 KB
- references/hook-errors.md 3 KB
- scripts/validate-hooks.sh 5 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · kyuna0312/context_forge | 100 | MIT |
| vibeeval/vibecosystem | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 35f40ce12ae1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100claude-code-hook-development
Pomaga tworzyć hooki Claude Code oraz sugeruje je przy prośbach o automatyczne wykonanie czegoś przed lub po innej akcji. - 100write-hook
Konfiguruje hooki Claude Code uruchamiane na początku sesji, przy każdym poleceniu lub po odpowiedzi i diagnozuje ich błędy. - 100hook-config-generator
Prowadzi przez dodanie nowego hooka Claude Code do frameworka jako pary .ps1 i .sh: rejestracja w hooks.json, lista dozwolonych wywołań, testy i walidacja. - 100working-with-claude-code
Dostarcza dokumentację Claude Code: CLI, wtyczki, hooki, serwery MCP, skille i konfigurację. - 100working-with-claude-code
Opisuje Claude Code: instalację, wtyczki, hooki, MCP, skille i ustawienia na podstawie oficjalnej dokumentacji. - 100create-hook
Tworzy hooki Cursor: plik hooks.json i skrypty automatyzujące zachowanie wokół zdarzeń agenta.