Pozwalają programistom i soloprzedsiębiorcom wymusić formatowanie kodu, uruchomić testy, wysłać powiadomienie lub zablokować niebezpieczne polecenie - bez polegania na tym, czy LLM „sam zdecyduje" się to zrobić. Hooks to deterministyczna warstwa automatyzacji nad inteligentnym asystentem.
Spis treści
Hooki (haki) to najprostszy sposób na dodanie deterministycznej logiki do pracy z Claude Code. Zamiast ufać, że model „pamięta" o uruchomieniu lintera przed każdym commit, definiujesz regułę raz - i hook wykonuje ją automatycznie, za każdym razem.
W przeciwieństwie do CLAUDE.md (który jest instrukcją dla modelu) i skilli (które są na żądanie), hooki są zawsze wymuszane. Jeśli hook zwróci błąd - akcja zostaje przerwana. To kluczowa różnica: CLAUDE.md to prośba, hook to zasada.
Hooki konfiguruje się w plikach settings.json Claude Code. Każdy hook ma trzy elementy: zdarzenie (np. PostToolUse), matcher (wzorzec pasujący do narzędzia lub ścieżki) oraz akcję (polecenie, zapytanie HTTP, prompt lub subagent).
Dostępne zdarzenia (hook events)
Claude Code udostępnia kilkanaście punktów zaczepienia w cyklu życia sesji. Najważniejsze z perspektywy soloprzedsiębiorcy i programisty:
- PreToolUse - wykonuje się przed każdym użyciem narzędzia (np. przed edycją pliku, uruchomieniem terminala). Idealny do blokowania niebezpiecznych komend.
- PostToolUse - wykonuje się po użyciu narzędzia. Najczęściej używany: formatowanie kodu po każdej edycji, lintowanie, logowanie.
- Notification - gdy Claude czeka na Twoją odpowiedź. Przydatny do powiadomień pulpitowych, żeby nie zerkać ciągle w terminal.
- SessionStart - przy starcie sesji. Możesz wstrzyknąć kontekst, sprawdzić wersje zależności lub wysłać webhook.
- Permission - przy żądaniu zgody na wykonanie potencjalnie niebezpiecznej operacji. Możesz automatycznie odrzucić lub zatwierdzić.
Jak skonfigurować hooka - praktyczny przykład
Hooki definiuje się w pliku ~/.claude/settings.json (globalne) lub .claude/settings.json (projektowe). Oto przykład hooka, który po każdej edycji pliku JavaScript/TypeScript uruchamia Prettier:
{"hooks":{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"jq -r ".tool_input.file_path" | xargs npx prettier --write"}]}]}}
Po dodaniu tej konfiguracji, Claude Code automatycznie formatuje kod po każdej zmianie. To samo możesz zrobić dla ESLinta, testów, optymalizacji obrazów - czegokolwiek, co powinno dziać się zawsze.
Hook może też blokować - nie tylko formatować. PreToolUse z walidacją bash command może odrzucić rm -rf / lub curl z podejrzanym URL-em, zanim Claude zdąży go wykonać. Przykład z oficjalnego repozytorium Anthropic pokazuje walidator w Pythonie.
Rodzaje hooków: command, HTTP, prompt i subagent
Poza podstawowym typem command, hooki obsługują trzy inne tryby:
- HTTP - wysyła żądanie do zewnętrznego API. Możesz logować zdarzenia do własnego backendu, wywołać webhook w n8n lub zapisać metryki. Odpowiedź serwera może blokować lub zatwierdzać operację.
- Prompt - wykonuje zapytanie do modelu Claude. Zamiast twardej reguły („zablokuj wszystko co zawiera rm"), możesz spytać model: „czy to polecenie jest bezpieczne w kontekście tego projektu?" To daje elastyczność kosztem dodatkowego tokena.
- Subagent - uruchamia osobnego agenta w izolowanym kontekście, który zwraca podsumowanie. Przydatne, gdy chcesz, żeby niezależny model zweryfikował kod, który właśnie powstał (ang. second opinion).
Typowe zastosowania dla soloprzedsiębiorcy i małego zespołu
- Automatyczne formatowanie i lintowanie - Claude edytuje plik, a hook od razu poprawia formatowanie. Bez twojego udziału. Kod w repozytorium jest zawsze czysty.
- Blokowanie kosztownych operacji - jeśli pracujesz na produkcji, hook PreToolUse może sprawdzać, czy polecenie dotyczy stagingu czy produkcji, i żądać potwierdzenia.
- Powiadomienia - hook Notification wywołuje osascript (macOS), notify-send (Linux) lub Windows Toast, gdy Claude skończy pracę. Nie musisz siedzieć i patrzeć na terminal.
- Integracja z CI/CD - hook PostToolUse może wywołać webhook w GitHub Actions, Trigger.dev lub n8n, uruchamiając deployment po spełnieniu warunków.
- Rejestrowanie zmian - każda edycja pliku może być logowana do pliku lub zewnętrznego API. Przydatne przy rozliczaniu czasu lub audycie zmian.
Ograniczenia i bezpieczeństwo
Hooki działają w shellu nieinteraktywnym. To oznacza, że aliasy z ~/.zshrc nie są dostępne - musisz używać pełnych ścieżek lub polegać na tym, co jest w PATH standardowego shella. Jeśli twój profil logowania wywołuje echo, może ono zostać zinterpretowane jako JSON i zablokować hooka.
Hook typu command to kod wykonywany lokalnie. Nie używaj hooków do pobierania i uruchamiania skryptów z nieznanych źródeł. Jeśli pracujesz w zespole, hooki projektowe w .claude/settings.json są commitowane do repozytorium - każdy członek zespołu może je zobaczyć i zmienić. Do wrażliwych reguł używaj globalnego ~/.claude/settings.json.
Po 8 kolejnych blokadach tego samego hooka, Claude Code nadpisuje go i kończy turę. To zabezpieczenie przed zapętleniem, ale warto o nim wiedzieć - jeśli hook konsekwentnie blokuje poprawną operację, dostosuj matcher, a nie polegaj na tym, że „Claude sobie poradzi".
Debugowanie hooków
Widok transcript (Ctrl+O) pokazuje jednowierszowe podsumowanie każdego hooka: sukces jest cichy, błędy blokujące pokazują stderr, a błędy nieblokujące wyświetlają pierwszą linię błędu. Do pełnego debugowania użyj flagi --debug-file /tmp/claude.log przy starcie Claude Code lub komendy /debug w trakcie sesji.
Najczęstsze pytania
Czym różni się hook od wpisu w CLAUDE.md?
CLAUDE.md to instrukcja dla modelu - Claude może, ale nie musi, jej przestrzegać, oceniając kontekst. Hook to deterministyczna reguła wykonywana przez system: jeśli warunek jest spełniony, polecenie wykonuje się zawsze. CLAUDE.md to prośba, hook to wymóg. W praktyce używa się obu: CLAUDE.md do konwencji kodu i architektury, hooki do wymuszenia formatowania, bezpieczeństwa i automatyzacji.
Czy hooki w Claude Code działają też w VS Code?
Tak. Claude Code dostępny jest jako rozszerzenie VS Code oraz jako samodzielne CLI. Hooki skonfigurowane w settings.json działają w obu środowiskach. Różnica jest taka, że w VS Code niektóre zdarzenia (jak Notification) mogą być obsłużone przez interfejs rozszerzenia zamiast powiadomienia pulpitowego. Sama logika hooków - command, HTTP, prompt, subagent - pozostaje taka sama.
Ile kosztuje używanie hooków typu prompt lub subagent?
Hooki typu command i HTTP są darmowe po stronie Claude Code (płacisz tylko za infrastrukturę, do której wysyłasz żądanie). Hooki typu prompt i subagent zużywają tokeny z twojego planu Claude - prompt wykonuje pojedyncze zapytanie do modelu, a subagent uruchamia osobną sesję z własnym kontekstem. W praktyce hooki typu prompt są tanie (kilkaset tokenów na walidację), subagenci mogą być drożsi przy dużych kontekstach. Używaj command i HTTP tam, gdzie logika jest deterministyczna, a prompt/subagent tylko do decyzji wymagających oceny modelu.
