Was tun, wenn Hooks nicht funktionieren
Das Problem, das Sie haben
Sie haben Hooks konfiguriert, aber sie funktionieren nicht wie erwartet? Möglicherweise erleben Sie folgende Situationen:
- Der Dev-Server wird nicht daran gehindert, außerhalb von tmux zu laufen
- Sie sehen keine Logs für SessionStart oder SessionEnd
- Die automatische Prettier-Formatierung funktioniert nicht
- TypeScript-Prüfungen werden nicht ausgeführt
- Sie sehen seltsame Fehlermeldungen
Keine Sorge, diese Probleme haben in der Regel klare Lösungen. Diese Lektion hilft Ihnen, Hooks-Probleme systematisch zu diagnostizieren und zu beheben.
🎒 Vorbereitung
Voraussetzungen prüfen
Stellen Sie sicher, dass Sie:
- ✅ Die Installation von Everything Claude Code abgeschlossen haben
- ✅ Die Grundkonzepte der Hooks-Automatisierung verstehen
- ✅ Die Hooks-Konfigurationsanleitung in der Projekt-README gelesen haben
Häufiges Problem 1: Hooks werden überhaupt nicht ausgelöst
Symptome
Nach der Befehlsausführung sehen Sie keine [Hook]-Logausgabe, Hooks scheinen überhaupt nicht aufgerufen zu werden.
Mögliche Ursachen
Ursache A: Falscher hooks.json-Pfad
Problem: hooks.json befindet sich nicht am richtigen Ort, Claude Code kann die Konfigurationsdatei nicht finden.
Lösung:
Überprüfen Sie, ob hooks.json am richtigen Ort liegt:
# Sollte an einem der folgenden Orte sein:
~/.claude/hooks/hooks.json # Benutzer-Konfiguration (global)
.claude/hooks/hooks.json # Projekt-KonfigurationÜberprüfungsmethode:
# Benutzer-Konfiguration anzeigen
ls -la ~/.claude/hooks/hooks.json
# Projekt-Konfiguration anzeigen
ls -la .claude/hooks/hooks.jsonFalls die Datei nicht existiert, kopieren Sie sie aus dem Everything Claude Code Plugin-Verzeichnis:
# Angenommen, das Plugin ist in ~/.claude-plugins/ installiert
cp ~/.claude-plugins/everything-claude-code/hooks/hooks.json ~/.claude/hooks/Ursache B: JSON-Syntaxfehler
Problem: hooks.json enthält Syntaxfehler, Claude Code kann die Datei nicht parsen.
Lösung:
JSON-Format validieren:
# JSON-Syntax mit jq oder Python validieren
jq empty ~/.claude/hooks/hooks.json
# oder
python3 -m json.tool ~/.claude/hooks/hooks.json > /dev/nullHäufige Syntaxfehler:
- Fehlende Kommas
- Nicht geschlossene Anführungszeichen
- Verwendung von einfachen Anführungszeichen (es müssen doppelte sein)
- Falsches Kommentarformat (JSON unterstützt keine
//-Kommentare)
Ursache C: Umgebungsvariable CLAUDE_PLUGIN_ROOT nicht gesetzt
Problem: Hook-Skripte verwenden ${CLAUDE_PLUGIN_ROOT} für Pfadreferenzen, aber die Umgebungsvariable ist nicht gesetzt.
Lösung:
Überprüfen Sie, ob der Plugin-Installationspfad korrekt ist:
# Installierte Plugin-Pfade anzeigen
ls -la ~/.claude-plugins/Stellen Sie sicher, dass das Everything Claude Code Plugin korrekt installiert ist:
# Sie sollten ein Verzeichnis wie dieses sehen
~/.claude-plugins/everything-claude-code/
├── scripts/
├── hooks/
├── agents/
└── ...Bei Installation über den Plugin-Marktplatz wird die Umgebungsvariable nach dem Neustart von Claude Code automatisch gesetzt.
Bei manueller Installation überprüfen Sie den Plugin-Pfad in ~/.claude/settings.json:
{
"plugins": [
{
"name": "everything-claude-code",
"path": "/path/to/everything-claude-code"
}
]
}Häufiges Problem 2: Bestimmte Hooks werden nicht ausgelöst
Symptome
Einige Hooks funktionieren (z.B. SessionStart), aber andere werden nicht ausgelöst (z.B. PreToolUse-Formatierung).
Mögliche Ursachen
Ursache A: Falscher Matcher-Ausdruck
Problem: Der matcher-Ausdruck des Hooks ist fehlerhaft, die Übereinstimmungsbedingung wird nicht erfüllt.
Lösung:
Überprüfen Sie die Matcher-Syntax in hooks.json:
{
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx)$\""
}Hinweise:
- Werkzeugnamen müssen in doppelten Anführungszeichen stehen:
"Edit","Bash" - Backslashes in regulären Ausdrücken müssen doppelt escaped werden:
\\\\.statt\\. - Dateipfad-Matching verwendet das Schlüsselwort
matches
Matcher testen:
Sie können die Matching-Logik manuell testen:
# Dateipfad-Matching testen
node -e "console.log(/\\\\.(ts|tsx)$/.test('src/index.ts'))"
# Sollte ausgeben: trueUrsache B: Befehlsausführung fehlgeschlagen
Problem: Der Hook-Befehl selbst schlägt fehl, aber es gibt keine Fehlermeldung.
Lösung:
Hook-Befehl manuell zum Testen ausführen:
# In das Plugin-Verzeichnis wechseln
cd ~/.claude-plugins/everything-claude-code
# Ein Hook-Skript manuell ausführen
node scripts/hooks/session-start.js
# Auf Fehlerausgabe prüfenHäufige Fehlerursachen:
- Inkompatible Node.js-Version (Node.js 14+ erforderlich)
- Fehlende Abhängigkeiten (z.B. prettier, typescript nicht installiert)
- Skript-Berechtigungsprobleme (siehe unten)
Häufiges Problem 3: Berechtigungsprobleme (Linux/macOS)
Symptome
Sie sehen einen Fehler wie diesen:
Permission denied: node scripts/hooks/session-start.jsLösung
Ausführungsberechtigungen für Hook-Skripte hinzufügen:
# In das Plugin-Verzeichnis wechseln
cd ~/.claude-plugins/everything-claude-code
# Ausführungsberechtigungen für alle Hooks-Skripte hinzufügen
chmod +x scripts/hooks/*.js
# Berechtigungen überprüfen
ls -la scripts/hooks/
# Sie sollten etwas wie: -rwxr-xr-x session-start.js sehenAlle Skripte auf einmal reparieren:
# Alle .js-Dateien unter scripts reparieren
find ~/.claude-plugins/everything-claude-code/scripts -name "*.js" -exec chmod +x {} \;Häufiges Problem 4: Plattformübergreifende Kompatibilitätsprobleme
Symptome
Funktioniert unter Windows, aber nicht unter macOS/Linux; oder umgekehrt.
Mögliche Ursachen
Ursache A: Pfadtrennzeichen
Problem: Windows verwendet Backslash \, Unix verwendet Forward-Slash /.
Lösung:
Die Skripte von Everything Claude Code sind bereits plattformübergreifend kompatibel (verwenden das Node.js path-Modul), aber wenn Sie eigene Hooks erstellen, beachten Sie:
Falsche Schreibweise:
{
"command": "node scripts/hooks\\session-start.js" // Windows-Stil
}Richtige Schreibweise:
{
"command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start.js\" // Umgebungsvariable und Forward-Slash verwenden
}Ursache B: Shell-Befehlsunterschiede
Problem: Verschiedene Plattformen haben unterschiedliche Befehlssyntax (z.B. which vs where).
Lösung:
Die scripts/lib/utils.js von Everything Claude Code behandelt diese Unterschiede bereits. Wenn Sie eigene Hooks erstellen, orientieren Sie sich an den plattformübergreifenden Funktionen in dieser Datei:
// Plattformübergreifende Befehlserkennung in utils.js
function commandExists(cmd) {
if (isWindows) {
spawnSync('where', [cmd], { stdio: 'pipe' });
} else {
spawnSync('which', [cmd], { stdio: 'pipe' });
}
}Häufiges Problem 5: Automatische Formatierung funktioniert nicht
Symptome
Nach dem Bearbeiten von TypeScript-Dateien formatiert Prettier den Code nicht automatisch.
Mögliche Ursachen
Ursache A: Prettier nicht installiert
Problem: Der PostToolUse-Hook ruft npx prettier auf, aber es ist im Projekt nicht installiert.
Lösung:
# Prettier installieren (projektbezogen)
npm install --save-dev prettier
# oder
pnpm add -D prettier
# Oder global installieren
npm install -g prettierUrsache B: Prettier-Konfiguration fehlt
Problem: Prettier findet keine Konfigurationsdatei und verwendet Standard-Formatierungsregeln.
Lösung:
Prettier-Konfigurationsdatei erstellen:
# .prettierrc im Projektstammverzeichnis erstellen
cat > .prettierrc << 'EOF'
{
"semi": true,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "es5"
}
EOFUrsache C: Dateityp stimmt nicht überein
Problem: Die Dateierweiterung der bearbeiteten Datei ist nicht in den Matching-Regeln des Hooks enthalten.
Aktuelle Matching-Regel (hooks.json Z92-97):
{
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
"description": "Auto-format JS/TS files with Prettier after edits"
}Wenn Sie andere Dateitypen unterstützen möchten (z.B. .vue), müssen Sie die Konfiguration ändern:
{
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx|vue)$\""
}Häufiges Problem 6: TypeScript-Prüfung funktioniert nicht
Symptome
Nach dem Bearbeiten von .ts-Dateien sehen Sie keine Typprüfungs-Fehlerausgabe.
Mögliche Ursachen
Ursache A: tsconfig.json fehlt
Problem: Das Hook-Skript sucht aufwärts nach einer tsconfig.json-Datei, findet aber keine.
Lösung:
Stellen Sie sicher, dass im Projektstammverzeichnis oder einem übergeordneten Verzeichnis eine tsconfig.json existiert:
# tsconfig.json suchen
find . -name "tsconfig.json" -type f
# Falls nicht vorhanden, Basiskonfiguration erstellen
cat > tsconfig.json << 'EOF'
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
EOFUrsache B: TypeScript nicht installiert
Problem: Der Hook ruft npx tsc auf, aber TypeScript ist nicht installiert.
Lösung:
npm install --save-dev typescript
# oder
pnpm add -D typescriptHäufiges Problem 7: SessionStart/SessionEnd werden nicht ausgelöst
Symptome
Beim Starten oder Beenden einer Sitzung sehen Sie keine [SessionStart]- oder [SessionEnd]-Logs.
Mögliche Ursachen
Ursache A: Sitzungsdatei-Verzeichnis existiert nicht
Problem: Das Verzeichnis ~/.claude/sessions/ existiert nicht, das Hook-Skript kann keine Sitzungsdateien erstellen.
Lösung:
Verzeichnis manuell erstellen:
# macOS/Linux
mkdir -p ~/.claude/sessions
# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\sessions"Ursache B: Falscher Skriptpfad
Problem: Der in hooks.json referenzierte Skriptpfad ist falsch.
Überprüfungsmethode:
# Überprüfen, ob die Skripte existieren
ls -la ~/.claude-plugins/everything-claude-code/scripts/hooks/session-start.js
ls -la ~/.claude-plugins/everything-claude-code/scripts/hooks/session-end.jsFalls nicht vorhanden, überprüfen Sie, ob das Plugin vollständig installiert ist:
# Plugin-Verzeichnisstruktur anzeigen
ls -la ~/.claude-plugins/everything-claude-code/Häufiges Problem 8: Dev-Server-Blockierung funktioniert nicht
Symptome
Das direkte Ausführen von npm run dev wird nicht blockiert, der Dev-Server kann gestartet werden.
Mögliche Ursachen
Ursache A: Regulärer Ausdruck stimmt nicht überein
Problem: Ihr Dev-Server-Befehl ist nicht in den Matching-Regeln des Hooks enthalten.
Aktuelle Matching-Regel (hooks.json Z6):
{
"matcher": "tool == \"Bash\" && tool_input.command matches \"(npm run dev|pnpm( run)? dev|yarn dev|bun run dev)\""
}Matching testen:
# Testen, ob Ihr Befehl übereinstimmt
node -e "console.log(/(npm run dev|pnpm( run)? dev|yarn dev|bun run dev)/.test('npm run dev'))"Wenn Sie andere Befehle unterstützen möchten (z.B. npm start), ändern Sie hooks.json:
{
"matcher": "tool == \"Bash\" && tool_input.command matches \"(npm (run dev|start)|pnpm( run)? (dev|start)|yarn (dev|start)|bun run (dev|start))\""
}Ursache B: Nicht in tmux, aber nicht blockiert
Problem: Der Hook sollte den Dev-Server außerhalb von tmux blockieren, aber es funktioniert nicht.
Prüfpunkte:
- Bestätigen Sie, dass der Hook-Befehl erfolgreich ausgeführt wird:
# Hook-Befehl simulieren
node -e "console.error('[Hook] BLOCKED: Dev server must run in tmux');process.exit(1)"
# Sie sollten eine Fehlerausgabe sehen und der Exit-Code sollte 1 sein- Überprüfen Sie, ob
process.exit(1)den Befehl korrekt blockiert:
process.exit(1)im Hook-Befehl sollte die Ausführung nachfolgender Befehle verhindern
- Falls es immer noch nicht funktioniert, müssen Sie möglicherweise die Claude Code-Version aktualisieren (Hooks-Unterstützung erfordert möglicherweise die neueste Version)
Diagnosetools und Tipps
Detaillierte Logs aktivieren
Sehen Sie sich die detaillierten Logs von Claude Code an, um die Hook-Ausführung zu verstehen:
# macOS/Linux
tail -f ~/Library/Logs/claude-code/claude-code.log
# Windows
Get-Content "$env:APPDATA\claude-code\logs\claude-code.log" -Wait -Tail 50Hook manuell testen
Führen Sie Hook-Skripte manuell im Terminal aus, um ihre Funktionalität zu überprüfen:
# SessionStart testen
cd ~/.claude-plugins/everything-claude-code
node scripts/hooks/session-start.js
# Suggest Compact testen
node scripts/hooks/suggest-compact.js
# PreCompact testen
node scripts/hooks/pre-compact.jsUmgebungsvariablen überprüfen
Umgebungsvariablen von Claude Code anzeigen:
# Debug-Ausgabe im Hook-Skript hinzufügen
node -e "console.log('CLAUDE_PLUGIN_ROOT:', process.env.CLAUDE_PLUGIN_ROOT); console.log('COMPACT_THRESHOLD:', process.env.COMPACT_THRESHOLD)"Checkliste ✅
Überprüfen Sie die folgenden Punkte nacheinander:
- [ ]
hooks.jsonbefindet sich am richtigen Ort (~/.claude/hooks/oder.claude/hooks/) - [ ]
hooks.jsonhat korrektes JSON-Format (mitjqvalidiert) - [ ] Plugin-Pfad ist korrekt (
${CLAUDE_PLUGIN_ROOT}ist gesetzt) - [ ] Alle Skripte haben Ausführungsberechtigungen (Linux/macOS)
- [ ] Abhängige Tools sind installiert (Node.js, Prettier, TypeScript)
- [ ] Sitzungsverzeichnis existiert (
~/.claude/sessions/) - [ ] Matcher-Ausdrücke sind korrekt (Regex-Escaping, Anführungszeichen)
- [ ] Plattformübergreifende Kompatibilität (Verwendung des
path-Moduls, Umgebungsvariablen)
Wann Sie Hilfe benötigen
Wenn keine der oben genannten Methoden das Problem löst:
Diagnoseinformationen sammeln:
bash# Folgende Informationen ausgeben echo "Node version: $(node -v)" echo "Claude Code version: $(claude-code --version)" echo "Plugin path: $(ls -la ~/.claude-plugins/everything-claude-code)" echo "Hooks config: $(cat ~/.claude/hooks/hooks.json | jq -c .)"GitHub Issues durchsuchen:
- Besuchen Sie Everything Claude Code Issues
- Suchen Sie nach ähnlichen Problemen
Issue erstellen:
- Vollständige Fehlerlogs beifügen
- Betriebssystem und Versionsinformationen angeben
hooks.json-Inhalt anhängen (sensible Informationen ausblenden)
Zusammenfassung
Wenn Hooks nicht funktionieren, gibt es in der Regel folgende Ursachenkategorien:
| Problemtyp | Häufige Ursachen | Schnelle Diagnose |
|---|---|---|
| Überhaupt nicht ausgelöst | Falscher hooks.json-Pfad, JSON-Syntaxfehler | Dateispeicherort prüfen, JSON-Format validieren |
| Bestimmter Hook nicht ausgelöst | Falscher Matcher-Ausdruck, Befehlsausführung fehlgeschlagen | Regex-Syntax prüfen, Skript manuell ausführen |
| Berechtigungsprobleme | Skripte haben keine Ausführungsberechtigungen (Linux/macOS) | chmod +x scripts/hooks/*.js |
| Plattformübergreifende Kompatibilität | Pfadtrennzeichen, Shell-Befehlsunterschiede | path-Modul verwenden, utils.js als Referenz |
| Funktion funktioniert nicht | Abhängige Tools nicht installiert (Prettier, TypeScript) | Entsprechende Tools installieren, Konfigurationsdateien prüfen |
Denken Sie daran: Die meisten Probleme lassen sich durch Überprüfung der Dateipfade, Validierung des JSON-Formats und Bestätigung der installierten Abhängigkeiten lösen.
Vorschau auf die nächste Lektion
In der nächsten Lektion lernen wir MCP-Verbindungsfehler beheben.
Sie werden lernen:
- Häufige Fehler bei der MCP-Server-Konfiguration
- Wie man MCP-Verbindungsprobleme debuggt
- MCP-Umgebungsvariablen und Platzhalter-Einstellungen
Anhang: Quellcode-Referenz
Klicken zum Anzeigen der Quellcode-Positionen
Aktualisiert am: 2026-01-25
| Funktion | Dateipfad | Zeilennummer |
|---|---|---|
| Hooks-Hauptkonfiguration | hooks/hooks.json | 1-158 |
| SessionStart Hook | scripts/hooks/session-start.js | 1-62 |
| SessionEnd Hook | scripts/hooks/session-end.js | 1-83 |
| PreCompact Hook | scripts/hooks/pre-compact.js | 1-49 |
| Suggest Compact Hook | scripts/hooks/suggest-compact.js | 1-61 |
| Plattformübergreifende Hilfsfunktionen | scripts/lib/utils.js | 1-384 |
Wichtige Funktionen:
getHomeDir()/getClaudeDir()/getSessionsDir(): Konfigurationsverzeichnispfade abrufen (utils.js 19-34)ensureDir(dirPath): Sicherstellen, dass Verzeichnis existiert, bei Bedarf erstellen (utils.js 54-59)log(message): Log an stderr ausgeben (sichtbar in Claude Code) (utils.js 182-184)findFiles(dir, pattern, options): Plattformübergreifende Dateisuche (utils.js 102-149)commandExists(cmd): Prüfen, ob Befehl existiert (plattformübergreifend kompatibel) (utils.js 228-246)
Wichtige reguläre Ausdrücke:
- Dev-Server-Blockierung:
npm run dev|pnpm( run)? dev|yarn dev|bun run dev(hooks.json 6) - Dateibearbeitungs-Matching:
\\.(ts|tsx|js|jsx)$(hooks.json 92) - TypeScript-Dateien:
\\.(ts|tsx)$(hooks.json 102)
Umgebungsvariablen:
${CLAUDE_PLUGIN_ROOT}: Plugin-StammverzeichnispfadCLAUD_SESSION_ID: SitzungskennungCOMPACT_THRESHOLD: Schwellenwert für Komprimierungsvorschläge (Standard: 50)