Pełna analiza mechanizmu Claude Code Hooks: pięć typów zdarzeń, kontrola kodów wyjścia i cztery rzeczywiste konfiguracje dla audytowalnych, przechwytywanych i automatyzowanych działań AI.
Za każdym razem, gdy Claude Code czyta plik, pisze kod lub wykonuje polecenie, w tle działa system zdarzeń. Hooks to interfejs do podłączenia się do tego systemu — możesz wstrzykiwać własną logikę w dowolnym momencie: automatycznie uruchamiać linery, rejestrować operacje, blokować niebezpieczne działania lub wyzwalać dowolne polecenia shell.
Ten artykuł w pełni omawia mechanizm Hooks, konfigurację i praktyczne zastosowanie.
Hooks to polecenia shell skonfigurowane w settings.json, które Claude Code wykonuje automatycznie po wystąpieniu określonych zdarzeń.
Najlepsza analogia: git hooks. Git może wyzwalać skrypty przed i po operacjach takich jak commit czy push. Claude Code Hooks działają dokładnie tak samo — różnica polega na tym, że punktami wyzwalającymi są wywołania narzędzi AI.
Dlaczego to ważne?
Im bardziej rozbudowany staje się Claude Code, tym bardziej potrzebujesz deterministycznej warstwy kontroli. Hooks zapewniają:
- Gwarancje wykonania niezależne od promptu (Claude może ignorować instrukcje, ale hook zawsze się wykona)
- Audytowalne dzienniki operacji
- Zautomatyzowane sprawdzanie jakości
| Typ | Wyzwalacz | Typowe zastosowanie |
|---|---|---|
PreToolUse |
Przed wywołaniem narzędzia | Blokowanie niebezpiecznych operacji |
PostToolUse |
Po wywołaniu narzędzia | Auto-lint, uruchamianie testów |
PreCompact |
Przed kompaktowaniem kontekstu | Zapisanie migawki stanu |
Notification |
Gdy Claude wysyła powiadomienie | Powiadomienia desktop, Slack |
Stop |
Gdy Claude kończy odpowiedź | Podsumowanie logów |
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{"type": "command", "command": "npm run lint --silent"}]
}
]
}
}
Trzy kluczowe pola: matcher — regex dla nazw narzędzi; type — tylko "command"; command — dowolne polecenie shell.
| Kod | Znaczenie |
|---|---|
0 |
Sukces, kontynuuj wykonanie |
2 |
Blokada: anuluj wywołanie narzędzia, przekaż stderr do Claude |
| Inny niezerowy | Zarejestruj błąd, kontynuuj |
Automatyczne formatowanie po zapisie plików — PostToolUse na Write|Edit, uruchamia rubocop dla .rb.
Zakaz usuwania katalogów — PreToolUse na Bash, przy rm .*/migrations zwraca kod 2.
Dziennik audytu — PostToolUse na Write|Edit|Bash, dopisuje do ~/.claude/audit.log.
Powiadomienie po zakończeniu — Stop hook, osascript lub notify-send.
Globalny (~/.claude/settings.json): reguły dla wszystkich projektów. Poziom projektu (.claude/settings.json): sprawdzenia specyficzne dla projektu. Oba zestawy łączą się i oba są wykonywane. Zaleca się commitowanie settings.json projektu do git.
Write to nie writeecho "triggered" >> /tmp/hook.logGłówna wartość Hooks to połączenie nieprzewidywalnego zachowania AI z deterministycznymi standardami inżynieryjnymi. Zacznij od jednego hooka: auto-lint po zapisie plików.