Hooki w Claude Code - automatyzacja przy zdarzeniach

Claude Code

Hooki w Claude Code - automatyzacja przy zdarzeniach

W skrócie

Hooki to mechanizm, dzięki któremu Claude Code, oficjalne narzędzie CLI od Anthropic, przestaje być tylko reaktywny i zaczyna automatycznie wykonywać Twoje reguły. Zamiast prosić za każdym razem o uruchomienie testów czy przypominać o formatowaniu, definiujesz raz skrypt, który odpala się sam w wybranym momencie. Pokazujemy, jak działają zdarzenia, jak skonfigurować hook i jak nim zablokować niepożądaną akcję.

Jak to wygląda w praktyce

Powtarzają się drobne, ręczne czynności: po każdej edycji pliku chcesz uruchomić linter, przed commitem sprawdzić politykę repozytorium, a niektóre komendy (na przykład kasujące dane) powinny być w ogóle nie do wykonania. Robienie tego ręcznie za każdym razem jest zawodne - łatwo zapomnieć. Bez automatyzacji przy zdarzeniach polegasz na tym, że sam albo agent o czymś pamięta, a to prędzej czy później zawodzi.

Dlaczego Claude Code tak działa

Claude Code udostępnia punkty zaczepienia w cyklu swojej pracy - hooki. To skrypty powłoki, które uruchamiają się automatycznie w określonych momentach: między innymi przed użyciem narzędzia (PreToolUse), po jego użyciu (PostToolUse), na starcie sesji czy przy jej zatrzymaniu. Definiujesz je w pliku settings.json, wskazując zdarzenie oraz - dla zdarzeń narzędziowych - dopasowanie narzędzia w polu matcher (na przykład Bash albo Edit|Write).

Hook dostaje na wejściu (przez standardowe wejście) dane w formacie JSON o tym, co Claude Code właśnie chce zrobić, więc może podjąć decyzję. Kluczowa jest konwencja kodów wyjścia: kod 0 nie podejmuje decyzji i akcja idzie normalnym trybem uprawnień, a kod 2 blokuje akcję, przy czym to, co skrypt wypisze na standardowe wyjście błędów, wraca do Claude jako informacja zwrotna. Dzięki temu hookiem można nie tylko coś uruchomić, ale też zatrzymać niepożądaną komendę.

Jak to rozwiązać krok po kroku

1. Zdecyduj, w którym momencie hook ma działać. Formatowanie i testy po zmianie kodu to PostToolUse; blokowanie ryzykownych komend przed wykonaniem to PreToolUse.
2. Otwórz plik ustawień .claude/settings.json (w projekcie) lub ~/.claude/settings.json (globalnie) i dodaj sekcję "hooks".
3. Wpisz zdarzenie i dopasowanie narzędzia. Na przykład dla lintera po edycji: zdarzenie PostToolUse, "matcher": "Edit|Write", a w środku wpis { "type": "command", "command": "./scripts/run-linter.sh" }.
4. Napisz skrypt powłoki i nadaj mu prawo wykonywania (na Linux i macOS chmod +x). W skrypcie możesz odczytać dane wejściowe z JSON na standardowym wejściu, żeby wiedzieć, czego dotyczy akcja.
5. Aby blokować niebezpieczne komendy, w hooku PreToolUse z "matcher": "Bash" sprawdź komendę i zakończ skrypt kodem 2, gdy jest zakazana. Tekst wypisany na standardowe wyjście błędów wróci do Claude jako wyjaśnienie.
6. Zawęź hook, jeśli ma reagować tylko na wybrane komendy. Możesz użyć pola if ze składnią reguł uprawnień, na przykład "if": "Bash(git *)", żeby hook odpalał się tylko dla poleceń gita, a nie każdego wywołania powłoki.
7. Do ścieżek w komendzie używaj zmiennej $CLAUDE_PROJECT_DIR, żeby hook działał niezależnie od katalogu, z którego wystartowała sesja.

Jak sprawdzić, że zadziałało

Wywołaj akcję, która ma uruchomić hook - na przykład zleć edycję pliku, jeśli podpiąłeś linter pod PostToolUse - i sprawdź, czy skrypt się wykonał (najprościej, dodając do niego tymczasowy zapis do logu). Dla hooka blokującego spróbuj wykonać zakazaną komendę: Claude Code powinien zostać zatrzymany, a w rozmowie pojawi się komunikat, który wypisałeś na standardowe wyjście błędów. Jeśli hook nie reaguje, sprawdź poprawność JSON w settings.json oraz prawo wykonywania skryptu.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5