Workbranch › Poradniki

Jak używać hooków w Claude Code

Chcesz, żeby coś działo się za każdym razem, na przykład formatowanie pliku po edycji przez Claude albo powiadomienie, gdy Claude na ciebie czeka, bez liczenia na to, że Claude o tym pamięta. Właśnie do tego służą hooki. Ten poradnik wyjaśnia, czym są, przeprowadza przez pierwszy hook i pokazuje, gdzie je umieścić.

Zaktualizowano 30 października 2026

Nazwy zdarzeń, lokalizacje plików i działanie opisane poniżej pochodzą z dokumentacji Claude Code od Anthropic z października 2026. Claude Code często się zmienia, więc jeśli czegoś brakuje, uruchom claude update.

Czym są hooki i jak pomagają

Instrukcje w prompcie czy w pliku CLAUDE.md to sugestie: Claude zwykle ich przestrzega, ale to on decyduje. Hook działa inaczej. Sam Claude Code uruchamia twoje polecenie za każdym razem, gdy wystąpi zdarzenie, więc działanie jest deterministyczne. Typowe zastosowania z poradnika Anthropic:

• Powiadomienia, gdy Claude czeka na zgodę lub twoją odpowiedź.
• Automatyczne formatowanie każdego pliku po tym, jak Claude go zmieni lub zapisze.
• Blokowanie zmian we wrażliwych plikach, takich jak .env, lub w czymkolwiek w .git/.
• Dodawanie kontekstu, na przykład przypominanie Claude o konwencjach projektu po skompaktowaniu rozmowy.

Do najczęściej używanych zdarzeń należą SessionStart (sesja się zaczyna lub zostaje wznowiona), UserPromptSubmit (wysyłasz prompt), PreToolUse (przed wywołaniem narzędzia; hook może je zablokować), PostToolUse (po udanym wywołaniu narzędzia), Notification, Stop (Claude kończy odpowiedź), PreCompact i SessionEnd. Pełna lista w dokumentacji hooków jest dużo dłuższa.

Pierwszy hook: powiadomienie na pulpicie

Ten przykład, oparty na instrukcji Anthropic, powiadamia cię na macOS za każdym razem, gdy Claude Code potrzebuje twojej uwagi.

1. Otwórz ~/.claude/settings.json w edytorze tekstu. Jeśli plik nie istnieje, utwórz go.
2. Dodaj obiekt hooks z wpisem Notification. W środku umieść listę grup dopasowań; każda ma matcher (zostaw pusty ciąg, żeby hook działał przy każdym powiadomieniu) i listę hooks z jednym elementem "type": "command".
3. Jako polecenie ustaw osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. W systemie Linux przykład Anthropic używa zamiast tego notify-send. Pamiętaj, żeby w JSON poprzedzić wewnętrzne cudzysłowy ukośnikiem wstecznym.
4. Jeśli plik ma już klucz hooks, dodaj Notification obok istniejących zdarzeń zamiast zastępować cały obiekt.
5. W Claude Code wpisz /hooks. Przeglądarka hooków powinna pokazać nowy hook pod Notification. Naciśnij Esc, żeby wrócić.
6. Poproś Claude o coś, co wymaga zgody, i przełącz się na inne okno. Powinno pojawić się powiadomienie.

Drugi przykład: formatowanie plików po edycji

W przypadku hooka projektu umieść konfigurację w .claude/settings.json w głównym folderze projektu. Użyj zdarzenia PostToolUse z matcherem Edit|Write, żeby hook działał tylko po narzędziach edytujących pliki. Przykładowe polecenie Anthropic odczytuje ścieżkę zmienionego pliku z JSON, który Claude Code przekazuje na standardowe wejście, i przekazuje ją do Prettiera: jq -r '.tool_input.file_path' | xargs npx prettier --write. Wymaga zainstalowanego jq. Udany hook nie pokazuje niczego w rozmowie; po prostu zobaczysz sformatowany plik.

Gdzie konfiguruje się hooki

Żeby wyłączyć hooki, ustaw "disableAllHooks": true w pliku ustawień. Hooki z ustawień zarządzanych działają dalej, chyba że ta opcja jest ustawiona także tam.

Jak hook odpowiada

Gdy wystąpi zdarzenie, Claude Code wysyła jego szczegóły jako JSON na standardowe wejście twojego polecenia. Polecenie odpowiada kodem wyjścia:

• Kod 0: kontynuuj. Przy niektórych zdarzeniach, takich jak SessionStart, zwykły tekst wypisany na standardowe wyjście jest dodawany do kontekstu Claude.
• Kod 2: zablokuj działanie, jeśli zdarzenie na to pozwala. Powód wypisz na standardowe wyjście błędów; przy PreToolUse Claude go otrzymuje i może zmienić kierunek.
• Inne kody: zwykle traktowane jako błąd nieblokujący; działanie jest kontynuowane, a w transkrypcie pojawia się błąd hooka.

Żeby mieć dokładniejszą kontrolę, zakończ z kodem 0 i zamiast tego wypisz obiekt JSON. Dla jednego hooka wybierz jedno podejście.

Warto wiedzieć

• Hooki poleceń nie mogą same uruchamiać poleceń slash ani wywoływać narzędzi.
• Domyślny limit czasu hooków poleceń to 10 minut, dla kilku zdarzeń krótszy; żeby go zmienić, ustaw timeout (w sekundach) dla danego hooka.
• PostToolUse nie może niczego cofnąć, bo narzędzie już zadziałało. Żeby zapobiec działaniu, użyj PreToolUse.
• Stop uruchamia się za każdym razem, gdy Claude kończy odpowiedź, a nie tylko po zakończeniu zadania.

Jeśli to nie działa

• Hook nigdy się nie uruchamia: uruchom /hooks i sprawdź, czy jest na liście pod właściwym zdarzeniem. Matchery rozróżniają wielkość liter i muszą dokładnie pasować do nazwy narzędzia, na przykład Edit, a nie edit.
• „/hooks” nic nie pokazuje: sprawdź, czy JSON jest poprawny (bez przecinków na końcu i bez komentarzy) i czy jest we właściwym pliku. Zmiany zwykle wczytują się automatycznie; jeśli nie, uruchom sesję ponownie.
• „hook error” w transkrypcie: przetestuj skrypt, przekazując mu przykładowy JSON przez potok, i sprawdź echo $?. Dla skryptów używaj ścieżek bezwzględnych lub $CLAUDE_PROJECT_DIR, zainstaluj jq, jeśli go brakuje, i nadaj skryptom prawo wykonywania przez chmod +x.
• Brak powiadomienia na macOS: uruchom raz polecenie osascript w Terminalu, a potem włącz Allow Notifications (Zezwalaj na powiadomienia) dla Script Editor (Edytor skryptów) w System Settings > Notifications (Ustawienia systemowe > Powiadomienia).

Śledź, co każda sesja zostawia otwarte

Wtyczka Workbranch dla Claude Code korzysta z podsumowania na starcie sesji: w folderze połączonym z projektem Workbranch pokazuje na początku sesji, co jest jeszcze otwarte, a po słowach „save this to Workbranch” (zapisz to w Workbranch) zapisuje zadania, decyzje i otwarte pytania z sesji w tym projekcie. Zobacz Workbranch dla Claude. Dopiero zaczynasz z Claude Code? Zacznij od poradnika jak zacząć pracę z Claude Code.

Źródła

• Use Claude Code with your Pro or Max plan (Centrum pomocy Claude, sprawdzono 30 października 2026)
• Automate actions with hooks (Claude Code docs, sprawdzono 30 października 2026)

Najczęściej zadawane pytania