Hooki w Claude Code: wszystkie zdarzenia i do czego służą

01Z czego składa się hook

Konfiguracja hooka ma trzy poziomy:

1. Zdarzenie hooka, np. PreToolUse albo Stop.
2. Grupa matchera, która określa, kiedy hook się odpala, np. „tylko dla narzędzia Bash”.
3. Jeden lub więcej handlerów hooka, czyli to, co faktycznie się uruchamia.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Ten przykład uruchamia skrypt lintujący po tym, jak Claude zapisze lub zedytuje plik. Żeby dodać drugie zdarzenie, dodaj kolejny klucz w tym samym obiekcie hooks.

02Gdzie trzymać hooki

Hooki z różnych plików sumują się, a nie nadpisują. Wpisz /hooks w Claude Code, żeby zobaczyć wszystkie aktywne hooki i to, skąd pochodzą.

W sesji interaktywnej Claude Code wstrzymuje hooki, nawet twoje własne, dopóki nie zaakceptujesz okna zaufania dla danego folderu.

03Typy handlerów

Większość hooków to "type": "command", czyli uruchomienie polecenia w shellu. Są jeszcze cztery inne:

• http: wysyła JSON zdarzenia POST-em na URL i czyta treść odpowiedzi.
• mcp_tool: wywołuje narzędzie na skonfigurowanym przez ciebie serwerze MCP.
• prompt: zadaje modelowi Claude jednorazowe pytanie i odczytuje decyzję w JSON.
• agent: uruchamia subagenta, który przed decyzją może przeczytać pliki (eksperymentalne).

Hooki typu command działają z pełnymi uprawnieniami twojego użytkownika, przez sh -c na macOS i Linux oraz Git Bash (albo PowerShell) na Windows. Dodaj "async": true, żeby uruchomić hook w tle; wtedy nie może już podejmować decyzji.

04Matchery

matcher decyduje, przy których wystąpieniach zdarzenia hook się uruchomi. To, do czego jest dopasowywany, zależy od zdarzenia: nazwa narzędzia przy zdarzeniach narzędzi, typ powiadomienia przy Notification, sposób rozpoczęcia sesji przy SessionStart itd.

• "*", "" albo brak matchera pasują do wszystkiego.
• Litery, cyfry, _, -, spacje, | i , są traktowane jako dokładne nazwy. Edit|Write pasuje do obu narzędzi.
• Wszystko inne to wyrażenie regularne JavaScript, więc mcp__memory__.* pasuje do każdego narzędzia z jednego serwera MCP.

Matchery rozróżniają wielkość liter. Niektóre zdarzenia, m.in. Stop i UserPromptSubmit, ignorują matchery. Przy zdarzeniach narzędzi pole if z regułą uprawnień, np. "Bash(git *)", dodatkowo zawęża pojedynczy handler.

05Wejście: co dostaje twój hook

Każdy hook dostaje na stdin JSON z kilkoma wspólnymi polami, m.in. session_id, transcript_path, cwd i hook_event_name, plus polami specyficznymi dla zdarzenia. Na przykład hook PreToolUse dla wywołania Bash dostaje też tool_name i tool_input.command. Odczytasz go za pomocą jq albo dowolnego parsera JSON:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Wyjście: kody wyjścia i JSON

Hook odpowiada na jeden z dwóch sposobów.

Kody wyjścia. 0 oznacza sukces. 2 to błąd blokujący: przy zdarzeniach, które można zablokować, akcja zostaje zatrzymana, a twój stderr staje się jej powodem. Każdy inny kod, łącznie z typowym 1, to błąd nieblokujący, więc akcja jest wykonywana dalej, a ty widzisz komunikat o błędzie hooka. Jeśli hook ma wymuszać jakąś regułę, zwracaj 2, a nie 1.

JSON na stdout. Zakończ z kodem 0 i wypisz pojedynczy obiekt JSON, jeśli potrzebujesz większej kontroli. Niektóre pola działają wszędzie, np. continue: false, które całkowicie zatrzymuje Claude. Inne zależą od zdarzenia: Stop używa decision: "block" razem z reason, a PreToolUse i PermissionRequest umieszczają decyzję w hookSpecificOutput. Nie wypisuj na stdout nic więcej: jedna przypadkowa linia z profilu shella sprawi, że Claude Code nie odczyta JSON-a.

07Wszystkie zdarzenia hooków

Anthropic co jakiś czas dodaje nowe eventy, więc aktualną listę i pola wejściowe każdego eventu sprawdzisz w dokumentacji hooków.

08Które eventy są ważne dla powiadomień

Cztery eventy pokrywają niemal wszystko, o czym ludzie chcą być informowani:

• Stop dla „Claude skończył”. Zobacz poradnik o Stop hook.
• Notification dla „Claude na ciebie czeka”, z typami takimi jak permission_prompt i idle_prompt. Zobacz poradnik o Notification hook.
• PermissionRequest, żeby dostać powiadomienie albo odpowiedzieć w chwili, gdy potrzebne jest uprawnienie. Zobacz poradnik o PermissionRequest.
• PreToolUse na narzędziu AskUserQuestion, żeby widzieć pytania wielokrotnego wyboru od Claude i na nie odpowiadać. Zobacz odpowiadanie na pytania z telefonu.

Jeśli chcesz gotową konfigurację na desktop do wklejenia, zacznij od tego, jak dostać powiadomienie, gdy Claude Code skończy.

09Gdzie pasuje Claude Code Notifier

Claude Code Notifier jest w całości zbudowany na tych hookach. Jego darmowe narzędzie CLI, ccn, działa na Macu, Windows i Linux. Instalacja dodaje siedem wpisów hooków do ~/.claude/settings.json, każdy uruchamia ccn hook, i jednorazowo robi kopię zapasową pliku. ccn działa kilka milisekund na event i się kończy, więc nic nie zostaje uruchomione w tle.

Samo w sobie pokazuje powiadomienia na desktopie. Po sparowaniu aplikacji na iPhone lub Android te same hooki przekazują z powrotem twoje odpowiedzi: zezwolisz na uprawnienie lub je odrzucisz, odpowiesz na pytanie albo wyślesz kolejne polecenie, gdy Claude się zatrzyma. To niezależny projekt, nie stworzony przez Anthropic. Jeśli potrzebujesz tylko logu albo lintowania, prościej napisać kilka własnych linijek. Szczegóły znajdziesz na stronie ccn.

10FAQ