Hooki w Claude Code – automatyzacja workflowów programisty

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.