Claude Code hooks po polsku, 10 praktycznych przykładów 2026

Spis treści

• Czym są hooks
• 5 typów hooków
• Konfiguracja w settings.json
• Twój pierwszy hook
• 10 praktycznych hooków
• Matchery i tool patterns
• Zmienne środowiskowe w hookach
• Antywzorce
• Troubleshooting
• Co dalej
• FAQ

Aktualizacja: wrzesień 2026. Hooks to najbardziej niedocenione feature Claude Code. Pozwalają zamienić CLI z "lepszego chatu z kodem" w prawdziwy agentic system z gwarancjami: brak destrukcyjnych komend, automatyczna formatowanie, custom validation, audit log. W tym tutorialu pokazuję 5 typów hooków, syntax w settings.json i 10 gotowych przykładów do skopiowania.

Czym są hooks w Claude Code

Hooks to konfigurowalne triggery uruchamiane w określonych momentach sesji Claude Code. Każdy hook to wpis w settings.json, który mówi: "kiedy stanie się X, wykonaj komendę Y". Jeśli Y zakończy się kodem 2, Claude Code zablokuje akcję X (na eventach, które da się blokować, np. PreToolUse).

Analogicznie do git hooków (pre-commit, post-receive), tylko że tutaj triggerami są nie operacje git, tylko operacje agenta: użycie narzędzia (PreToolUse / PostToolUse), wysłanie prompta (UserPromptSubmit), koniec odpowiedzi Claude (Stop), początek sesji (SessionStart).

Realnie hooks są tym, co zamienia Claude Code z "AI chat w terminalu" w prawdziwy system, który zatrzymuje agenta przed zrobieniem czegoś głupiego (jak rm -rf node_modules bez backup), albo automatyzuje workflow, którego inaczej trzeba pilnować ręcznie (jak format po każdej edycji).

5 najważniejszych typów hooków w Claude Code

5 najczęściej używanych eventów hooków, kiedy się uruchamiają

Typ hooka	Kiedy się uruchamia	Typowy use case
PreToolUse	Przed wywołaniem narzędzia (Bash, Edit, Write)	Blokuj destrukcyjne komendy, validation
PostToolUse	Po wywołaniu narzędzia	Auto-format, lint, generation derived files
UserPromptSubmit	Gdy użytkownik wysyła prompt	Wzbogacenie kontekstu (branch name, autor)
Stop	Gdy Claude kończy odpowiedź (co turę; koniec całej sesji to osobny event SessionEnd)	Uruchom testy, generuj summary, audit log
SessionStart	Na początku sesji	Ładuj env vars, sprawdzaj prereq

Konfiguracja w settings.json

Hooks definiujesz w .claude/settings.json w roocie projektu (per-projekt) lub ~/.claude/settings.json (globalnie). Format:

{
  "hooks": {
    "TypHooka": [
      {
        "matcher": "PatternMatcher",
        "hooks": [
          {
            "type": "command",
            "command": "shell command tutaj"
          }
        ]
      }
    ]
  }
}

matcher to filter, który decyduje, dla jakich narzędzi/promptów hook ma się uruchomić. Dla PreToolUse i PostToolUse matcher to nazwa narzędzia (Bash, Edit, Write, Glob, Grep, Read). Dla UserPromptSubmit i Stop matcher zazwyczaj jest pusty (uruchamia się zawsze).

Twój pierwszy hook, blokowanie rm -rf

Zacznijmy od najprostszego i najużyteczniejszego hooka, blokady niebezpiecznego rm -rf.

Plik .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'rm -rf|sudo rm'; then echo 'BLOCKED: destructive rm command' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

Od teraz każda próba Claude'a użycia rm -rf w Bash kończy się blokadą: hook czyta JSON ze stdin (pole tool_input.command), a exit 2 plus komunikat na stderr "BLOCKED: destructive rm command" trafia do Claude, który przejdzie do alternatywnej strategii (np. git rm, mv do trash). Zmiany w pliku ustawień Claude Code zwykle wyłapuje automatycznie, bez restartu.

10 praktycznych hooków do skopiowania

1. Blokuj rm -rf i destrukcyjne bash

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'rm -rf|sudo rm|chmod 000|dd if='; then echo 'BLOCKED destructive command' >&2; exit 2; fi"
    }]
  }]
}

2. Auto-format po Edit (Prettier / Ruff)

{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "FILE=$(jq -r '.tool_input.file_path'); if [[ \"$FILE\" == *.ts ]] || [[ \"$FILE\" == *.js ]]; then npx prettier --write \"$FILE\"; elif [[ \"$FILE\" == *.py ]]; then ruff format \"$FILE\"; fi"
    }]
  }]
}

3. Blokuj edit plików .env i secrets

{
  "PreToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "FILE=$(jq -r '.tool_input.file_path // empty'); if echo \"$FILE\" | grep -qE '\\.env|secrets|credentials|\\.pem$'; then echo 'BLOCKED: edit on secrets file' >&2; exit 2; fi"
    }]
  }]
}

4. Auto-uruchom testy, gdy Claude kończy odpowiedź (Stop)

{
  "Stop": [{
    "hooks": [{
      "type": "command",
      "command": "if [ -f package.json ]; then npm test --silent 2>&1 | tail -20; elif [ -f pyproject.toml ]; then pytest -q 2>&1 | tail -20; fi"
    }]
  }]
}

5. Dodaj branch i autor do każdego prompta (UserPromptSubmit)

{
  "UserPromptSubmit": [{
    "hooks": [{
      "type": "command",
      "command": "echo \"Kontekst: branch=$(git branch --show-current), autor=$(git config user.email)\""
    }]
  }]
}

6. Wymuszaj że każdy commit ma conventional commit prefix

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'git commit'; then if ! echo \"$CMD\" | grep -qE '(feat|fix|chore|docs|refactor|test|style|perf|build|ci)(\\(.*\\))?:'; then echo 'BLOCKED: commit message must start with conventional prefix' >&2; exit 2; fi; fi"
    }]
  }]
}

7. Audit log wszystkich tool uses (PostToolUse)

{
  "PostToolUse": [{
    "hooks": [{
      "type": "command",
      "command": "jq -c '{t: (now | todate), tool: .tool_name, input: .tool_input}' >> .claude/audit.log"
    }]
  }]
}

8. SessionStart, sprawdź czy CLAUDE.md istnieje

{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "if [ ! -f CLAUDE.md ]; then echo 'Uwaga: w repo brak CLAUDE.md, zaproponuj /init'; fi"
    }]
  }]
}

9. Blokuj wywołania zewnętrznego curla do unknown domains

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE '^curl '; then DOMAIN=$(echo \"$CMD\" | grep -oE 'https?://[^/ ]+' | head -1); ALLOWED='api.github.com|api.linear.app|api.anthropic.com'; if ! echo \"$DOMAIN\" | grep -qE \"$ALLOWED\"; then echo \"BLOCKED curl to: $DOMAIN\" >&2; exit 2; fi; fi"
    }]
  }]
}

10. PostToolUse, regeneracja plików derived (np. types z OpenAPI)

{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "FILE=$(jq -r '.tool_input.file_path'); if [[ \"$FILE\" == *openapi.yaml ]] || [[ \"$FILE\" == *schema.prisma ]]; then npm run generate --silent 2>&1 | tail -10; fi"
    }]
  }]
}

Matchery i tool patterns

Matcher dla PreToolUse i PostToolUse to nazwa narzędzia. Możesz użyć pipe | żeby objąć kilka narzędzi: "matcher": "Edit|Write". Najczęstsze nazwy:

• Bash, wywołania shell
• Edit, edycja istniejącego pliku
• Write, utworzenie nowego pliku
• Read, odczyt pliku
• Glob, szukanie plików po wzorze
• Grep, szukanie w treści plików
• WebFetch, fetch URL
• WebSearch, search web

Dla MCP tools matcher to mcp__<server_name>__<tool_name>, np. mcp__github__create_issue.

Dane wejściowe hooka (JSON na stdin)

Claude Code nie przekazuje kontekstu operacji w zmiennych środowiskowych, tylko jako JSON na standardowe wejście (stdin) hooka. Najważniejsze pola:

• session_id, cwd, hook_event_name, transcript_path, wspólne dla wszystkich eventów
• tool_name, nazwa narzędzia (np. "Bash", "Edit"), w PreToolUse i PostToolUse
• tool_input, wejście narzędzia, np. tool_input.command dla Bash albo tool_input.file_path dla Edit/Write
• tool_response, wynik narzędzia (tylko w PostToolUse)

W skrypcie hooka czytasz je przez jq, np. CMD=$(jq -r '.tool_input.command'). Ze zmiennych środowiskowych dostępne są m.in. $CLAUDE_PROJECT_DIR (katalog projektu), przydatny do ścieżek do skryptów hooków.

Antywzorce, czego unikać

1. Zbyt rygorystyczne blokady, jeśli zablokujesz rm całkowicie, Claude nie usunie node_modules przed reinstall. Bądź selektywny (rm -rf na critical paths).
2. Slow hooks, hook PreToolUse który trwa 5s blokuje każdą operację o 5s. Trzymaj hooki pod 1s. Wszystko cięższe (testy, lint full) → Stop hook.
3. Niedeterministyczne hooks, hook który czasem fail, czasem pass = nieprzewidywalny Claude. Każdy hook powinien być reprodukowalny.
4. Brak echo w blokadach, jeśli blokujesz coś, zawsze drukuj wyjaśnienie na stderr i kończ kodem 2, wtedy trafi do Claude jako powód blokady.
5. Hardcoded paths, używaj zmiennych env i $(pwd), hook ma działać niezależnie od lokalizacji.

Troubleshooting

Najczęstsze problemy z hookami i jak je naprawić:

• Hook nie odpala się, sprawdź syntax JSON (npx jsonlint .claude/settings.json). Najczęstsza przyczyna 90% problemów.
• Hook nie blokuje, choć powinien, sprawdź, czy kończy się exit 2 (exit 1 to błąd nieblokujący), i zapisz wejście do pliku (cat > /tmp/hook-input.json), żeby zobaczyć, jakie pola naprawdę dostajesz.
• Hook za wolny, profiluj time <komenda>. Sprawdź czy używasz cache (npm install, prettier --check zamiast --write na dużej liście plików).
• Permission denied, hook to dowolny shell, więc musi być wykonywalny. Skrypty Python/Node potrzebują shebang lub explicit interpreter.
• Logi nigdzie nie idą, uruchom Claude Code z flagą --debug, log sesji trafia do ~/.claude/debug/.

Co dalej

Hooks to początek. Pełen workflow z Claude Code to hooks + slash commands + MCP servers + Agent SDK + Anthropic API. Każda warstwa ma swoją niszę:

• Claude Code tutorial po polsku, kompletny przewodnik
• Claude Code MCP Server po polsku (nadchodzące)
• Claude Agent SDK po polsku (nadchodzące)
• Claude Code vs Cursor

Najczęściej zadawane pytania

Powiązane artykuły

Claude Code•12 min

Claude Code cena 2026: cennik w zł i czy jest darmowy

Ile kosztuje Claude Code: Pro 20 USD (ok. 78 zł), Max 100 i 200 USD, API od kilku dolarów. Czy jest darmowy, co dostajesz za 0 zł i co wybrać przy jakim użyciu.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj