Claude Code Hooks: Kompletní vývojářský průvodce s příklady připravenými pro produkci

Claude Code Hooks: Kompletní průvodce pro vývojáře s příklady připravenými pro produkci

Claude Code skvěle píše kód, ale stále jde o pravděpodobnostní systém. Můžete ho požádat, aby po každé úpravě souboru spustil Prettier. Můžete tento pokyn uvést v souboru CLAUDE.md. A občas to prostě... zapomene. Claude Code hooks to řeší tím, že vám poskytují deterministickou a zaručenou kontrolu nad tím, co se děje před, během a po každé akci, kterou Claude provede.

Během posledních několika měsíců jsem konfiguroval hooks v desítkách projektů a nenápadně se staly nejdůležitější součástí mého nastavení Claude Code. Tento průvodce pokrývá vše od základů až po produkční starter kit, který můžete nasadit do jakéhokoli projektu ještě dnes. Pokud jste používali Claude Code spolu s nástroji jako Cursor nebo Copilot, už znáte hodnotu přizpůsobení — hooks ji posouvají ještě o krok dál.

Co jsou Claude Code Hooks (a proč by vás měly zajímat)?

Claude Code hooks jsou uživatelem definované shellové příkazy, HTTP endpointy nebo LLM prompty, které se automaticky spouštějí v určitých bodech životního cyklu Claude Code. Podle oficiální dokumentace Anthropic se hooks, na rozdíl od instrukcí v promptu, které Claude může ignorovat, spouštějí deterministicky pokaždé, což vám zaručuje plnou kontrolu nad formátováním, bezpečností, oznámeními a automatizací pracovních postupů.

Pravděpodobnostní problém

Věc se má s instrukcemi v CLAUDE.md takto: jsou to doporučení, ne smlouvy. Do kontextu projektu můžete napsat „vždy po úpravě souborů TypeScriptu spusť npx prettier --write" a Claude se tím bude řídit většinu času. Jenže „většinu času" nestačí, když vymáháte formátování kódu napříč týmem, blokujete push do produkce nebo logujete každý shellový příkaz kvůli bezpečnostnímu auditu.

Tohle je základní napětí každého AI nástroje pro psaní kódu. Claude je jazykový model – pracuje s pravděpodobností. Vaše inženýrství kontextu dokáže chování usměrnit, ale nedokáže ho zaručit.

Jak to hooky řeší

Hooky LLM zcela obcházejí. Jde o shellové skripty, HTTP volání nebo AI evaluace, které se spouštějí při konkrétních událostech životního cyklu – před spuštěním nástroje (PreToolUse), po jeho dokončení (PostToolUse), při zobrazení oznámení, na začátku relace nebo když se Claude zastaví. Představte si je jako Git hooky, ale pro vašeho AI programovacího asistenta.

Existují čtyři typy hooků: command (shellové skripty), HTTP (POST requesty webhooku), prompt (jednotahové evaluace ano/ne od Claudu) a agent (vytvoří subagenta s přístupem k nástrojům). Každý z nich si později rozebereme – command hooky pokrývají zhruba 90 % toho, co budete potřebovat.

Jak fungují hooky Claude Code: průběh životního cyklu

Hooky Claude Code se vykonávají v definovaném životním cyklu: nejprve se vyvolá událost (např. PreToolUse), matcher zkontroluje, zda se hook vztahuje na danou situaci, poté se spustí skript hooku, který na standardním vstupu (stdin) obdrží JSON, a návratový kód určí, co se stane dál. Návratový kód 0 znamená pokračovat, návratový kód 2 znamená zablokovat akci. Tento průběh je stejný bez ohledu na to, jaký typ hooku používáte.

Událost -> Matcher -> Hook -> Návratový kód (4krokový průběh)

Takto funguje každé spuštění hooku:

1. EVENT FIRES          e.g., PreToolUse(Write)
       |
2. MATCHER CHECKS       Does "Write" match the hook's matcher pattern?
       |
3. HOOK EXECUTES        Shell script runs, receives JSON via stdin
       |
4. EXIT CODE DECIDES    0 = proceed | 2 = block | other = error

JSON, který dorazí na standardní vstup, obsahuje vše o dané události: tool_name, tool_input (cestu k souboru, obsah, příkaz) a metadata relace. Váš skript tento JSON přečte, provede potřebnou logiku a ukončí se s příslušným návratovým kódem.

U hooků PreToolUse je klíčový návratový kód 2 – ten akci zcela zablokuje a odešle vaši zprávu ze standardního výstupu zpět Claudovi jako zpětnou vazbu. Claude vaši zprávu uvidí a může svůj postup upravit.

Konfigurační rozsahy: uživatel, projekt a místní

Hooky se umisťují do settings.json na třech úrovních:

Projektová nastavení jsou pro týmy nejužitečnější. Umístěte hooky do .claude/settings.json, commitněte soubor a každý vývojář v týmu automaticky získá stejná ochranná pravidla.

Pole if: Detailní filtrování

Od verze Claude Code v2.1.85 hooky podporují pole if, které umožňuje filtrovat podle argumentů nástroje, nejen podle názvů nástrojů. Jak je zdokumentováno v referenční příručce k hookům Anthropic, znamená to, že můžete napsat hook, který se spustí pouze u příkazů Bash odpovídajících git push, místo aby se spouštěl při každém jednotlivém vyvolání Bash.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

Šlo o velké vylepšení. Před if jste buď shodovali příliš široce (každý příkaz Bash), nebo filtrovali uvnitř skriptu (nepřehledné).

Všechny hook události Claude Code: Rychlá referenční tabulka

Claude Code nabízí více než 20 hook událostí v průběhu svého životního cyklu, jak je zdokumentováno v oficiální referenční příručce k hookům a v seznamu změn Claude Code. Nejčastěji se používají PreToolUse, PostToolUse, Notification a Stop, ale novější události jako ConfigChange a FileChanged otevírají pokročilé vzory automatizace.

Zde je kompletní přehled:

Profesionální tip: PreToolUse a PostToolUse využijete u 80 % svých hooků. SessionStart je další nejužitečnější — je ideální pro vložení kontextu projektu, který Claude potřebuje na začátku každé relace.

Vysvětlení 4 typů hooků Claude Code

Claude Code podporuje čtyři typy handlerů hooků: command hooky spouštějí shellové skripty, HTTP hooky posílají POST požadavky na URL, prompt hooky pokládají Claudovi otázku ano/ne a agent hooky spouštějí subagenta s přístupem k nástrojům. Podle našich zkušeností pokryjí command hooky 90 % případů použití. HTTP použijte pro externí integrace, prompt a agent hooky pro nuancovaná rozhodnutí vyžadující úsudek AI.

Příkazové hooky (pracovní koně)

Příkazové hooky spustí shellový příkaz a podle návratového kódu určí výsledek. Data události v JSONu obdrží na standardním vstupu (stdin).

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

Právě tohle budete používat pro formátování, ochranu souborů, notifikace a většinu automatizace. Rychlé, jednoduché a předvídatelné.

HTTP hooky (externí integrace)

HTTP hooky odesílají POST požadavek na danou URL s JSON události v těle. Stavový kód odpovědi určuje výsledek (200 = pokračovat, 403 = zablokovat).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Skvělé pro posílání událostí do Slacku, Discordu, PagerDuty nebo na vlastní dashboard. Dá se to využít i k dotazování externího policy enginu před povolením spuštění nástroje.

Prompt hooky (rozhodování řízené AI)

Prompt hooky předávají data události přímo Claudovi k jednorázovému vyhodnocení ano/ne. Claude vrátí odpověď JSON s "decision": "allow" nebo "decision": "block" spolu s odůvodněním.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

Používejte je střídmě. Zvyšují latenci (plné volání LLM při každém spuštění hooku) i náklady. Pro skutečně subjektivní bezpečnostní kontroly, jako je „vypadá tato databázová migrace destruktivně?", je ale těžké je překonat. Pokud vás zajímá přepínání modelů Claude Code, model používaný pro prompt hooky se řídí modelem vaší aktuální relace.

Agent Hooks (ověřování pomocí nástrojů)

Agent hooks spustí subagenta s přístupem k nástrojům Read, Grep a Glob. Subagent může před rozhodnutím prozkoumat soubory.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

Jde o nejvýkonnější typ hooku, ale zároveň nejpomalejší. Vyhraďte si ho pro kritické kontroly, u kterých pro správné rozhodnutí potřebujete kontext souborů.

7 příkladů hooků pro Claude Code připravených k produkčnímu nasazení (připravené ke zkopírování)

Mezi nejužitečnější hooky pro Claude Code patří automatické formátování pomocí Prettier nebo Black po úpravách souborů, blokování zápisů do chráněných souborů, odesílání desktopových oznámení po dokončení úlohy, vložení kontextu projektu na začátku relace, spouštění testů po změnách kódu, vynucování ochrany větví a audit veškerého použití nástrojů. Poslední tři měsíce používám různé varianty těchto hooků ve všech svých projektech.

Každý příklad níže je kompletní úryvek settings.json, který můžete vložit do svého .claude/settings.json. Komunitní sbírky jako awesome-claude-code obsahují ještě více vzorů.

1. Automatické formátování při uložení

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

Toto se spustí po každém Write nebo Edit, extrahuje cestu k souboru z JSON na stdin a spustí příslušný formátovač. exit 0 na konci zajišťuje, že hook nikdy neblokuje — selhání formátování by Claude nemělo zastavit.

Tip: Pokud pracujete napříč jazyky, přidejte *.go s gofmt a *.rs s rustfmt.

2. Blokování zápisů do chráněných souborů

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

Návratový kód 2 akci zablokuje a odešle JSON zprávu zpět Claudovi. Claude zpětnou vazbu uvidí a přizpůsobí se – obvykle vám dá vědět, že chtěl soubor upravit, a požádá vás, abyste to provedli ručně. Pole if zabraňuje tomu, aby se to spustilo při každém volání Write.

3. Desktop Notification on Completion

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

Funguje na macOS (osascript) i na Linuxu (notify-send). Prázdný matcher znamená, že se spustí při všech oznámeních. To se opravdu hodí, když spustíte dlouhou úlohu a přepnete se do jiného okna.

4. Vstřikování kontextu na začátku relace

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

Tímto se do každé relace vloží název aktuálního projektu, větev Gitu a poslední commit. Claude tento kontext obdrží automaticky, není potřeba mu říkat, na které větvi se nacházíte.

5. Automatické spouštění testů po úpravách kódu

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

Pokud existuje odpovídající soubor s testy, spustí se automaticky poté, co Claude upraví zdrojový kód. Příkaz tail -5 udržuje výstup stručný a časový limit zabraňuje nekontrolovanému běhu testovacích sad. To se dobře doplňuje s pracovním postupem kontroly kódu pomocí AI.

6. Vynucení ochrany větví (pokročilé)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

Toto zablokuje jakýkoli git push mířící na větve main, master nebo production. Claude obdrží zpětnou vazbu a navrhne místo toho vytvořit feature větev.

7. Protokolování auditu zabezpečení (pokročilé)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Zaznamenává každý příkaz Bash, který Claude spustí, do souboru auditu s časovým razítkem UTC. Neocenitelné pro bezpečnostní kontroly a pochopení toho, co Claude během relace skutečně dělal. Ponechte .claude/audit.log ve svém .gitignore.

Hooks vs MCP vs Skills vs CLAUDE.md: Kdy co použít

Hooks používejte pro deterministickou automatizaci, která musí běžet vždy (formátování, blokování, upozornění). MCP používejte, když chcete Claudovi poskytnout přístup k externím nástrojům a datům. Skills používejte pro znovu použitelné balíčky promptů. CLAUDE.md používejte pro pokyny k chování a kontext projektu. Hooks jsou zaručené; vše ostatní je pravděpodobnostní. Tohle je zdaleka nejdůležitější rozdíl a neustále se k němu vracím, když radím týmům.

Rozhodovací matice

Podrobný přehled o MCP najdete v našem průvodci MCP. Pokud přecházíte z Cursoru, systém pravidel Cursoru je zhruba analogický k CLAUDE.md, ale Cursor nemá nic podobného hookům.

Když se překrývají (a jak si vybrat)

Tady je schéma, které používám:

• „Musí se tohle stát pokaždé, bez výjimek?", Hook. Formátování kódu, blokování chráněných souborů, odesílání oznámení. Žádná nejednoznačnost.
• „Potřebuje Claude novou SCHOPNOST, kterou nemá?", MCP server. Přístup k databázi, volání API, prohledávání externích dokumentů.
• „Chci znovu použitelné POKYNY pro konkrétní pracovní postup?", Skill (slash příkaz). Šablony pro code review, checklisty pro nasazení.
• „Chci ovlivnit CHOVÁNÍ Claudu v tomto projektu?", CLAUDE.md. Standardy kódování, architektonická rozhodnutí, preferované knihovny.

Reálné příklady, které vyjasňují hranice:

• „Vždy formátuj pomocí Prettieru" = Hook (musí se to stát pokaždé)
• „Používej Prettier pro formátování" v CLAUDE.md = Doporučení (Claude by mohl zapomenout)
• „Prohledej naše firemní dokumenty" = MCP (nová schopnost)
• „Při review kódu se řiď naším style guidem" = Skill nebo CLAUDE.md

Jak je popsáno v oznámení Anthropic o pluginech, hooky jsou jednou součástí širšího ekosystému pluginů, který zahrnuje také MCP a Skills. Jsou navrženy tak, aby se navzájem doplňovaly, nikoli spolu soupeřily.

Startovací sada: hotová konfigurace hooků pro Claude Code do jakéhokoli projektu

Startovací konfigurace hooků pro Claude Code by měla zahrnovat automatické formátování při úpravě souboru, notifikaci po dokončení úlohy, ochranu citlivých souborů, vložení kontextu relace a stop hook pro úklid. Přesně tuto konfiguraci vkládám do každého nového projektu, přizpůsobenou danému stacku, ale struktura zůstává stejná.

Konfigurace

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

Jak si přizpůsobit pro váš stack

V konfiguraci výše nahraďte příkazy pro formátování a testování tak, aby odpovídaly vašemu stacku. Struktura zůstává stejná.

Ověření funkčnosti hooků

Existují tři způsoby, jak potvrdit, že jsou hooky aktivní:

1. Příkaz /hooks – zadejte v Claude Code příkaz /hooks a zobrazí se všechny registrované hooky, jejich matchery a jejich stav.
2. Kontrola přepisu – poté, co se hook spustí, zkontrolujte přepis relace. Spuštění hooků se zobrazí včetně jejich výstupu a návratového kódu.
3. Rychlé přepnutí – přidejte do souboru settings.json položku "disableAllHooks": true a dočasně tak všechny hooky zakážete, aniž byste museli konfiguraci mazat. Odeberte ji (nebo nastavte na false) a znovu je povolíte.

Integrace CI/CD: Hooky Claude Code v bezhlavém režimu

Hooky Claude Code fungují v bezhlavém režimu (claude -p) s určitými rozdíly: Notifikační hooky se stále spouštějí, ale měli byste je přesměrovat do logování namísto desktopových upozornění. Hooky PreToolUse s návratovým kódem 2 mohou pozastavit bezhlavé relace pro lidskou kontrolu. GitHub Actions používá anthropics/claude-code-action@v1 společně s hooky pro automatizované pracovní postupy.

Chování v headless režimu

Velké překvapení v headless režimu: hooky PreToolUse, které skončí s kódem 2, neselžou jen tiše. Pozastaví relaci a umožní vám pokračovat pomocí --resume, což vám dává vzor human-in-the-loop pro CI pipeline.

Integrace GitHub Actions

Zde je minimální workflow GitHub Actions, které používá Claude Code s hooky. Jak je popsáno v oficiálním průvodci GitHub Actions:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Hooky v souboru .claude/settings.json cestují spolu s repozitářem, takže se v CI spustí přesně tak jako lokálně. Jen se ujistěte, že hooky spoléhající na nástroje specifické pro desktop (například osascript) mají fallbacky nebo podmíněné větvení.

Správa hooků v týmu

Vzorec, který se v týmech osvědčil:

• .claude/settings.json (commitováno), Týmově sdílené hooky: ochrana souborů, formátovače, ochrana větví. Tyto získá každý.
• .claude/settings.local.json (ignorováno gitem), Osobní hooky: předvolby oznámení, vlastní logování, experimentální hooky.
• ~/.claude/settings.json (globální pro uživatele), Vaše výchozí nastavení napříč všemi projekty: styl oznámení, osobní předvolby formátování.

To odráží způsob, jakým funguje .editorconfig (commitováno) a lokální nastavení IDE (osobní). Jak uvádí průvodce CI/CD od Angela Limy, týmy, které se standardizují na sdílených hoocích, se u Claude Code setkávají s menším počtem problémů typu „u mě to funguje".

Řešení problémů s hooky Claude Code a časté chyby

Mezi časté problémy s hooky Claude Code patří: hooky se nespouštějí (zkontrolujte pravopis matcheru a umístění souboru settings.json), hooky se spouštějí, ale neblokují (nesprávný návratový kód, použijte 2 místo 1), nekonečné smyčky (hook Stop spouští sám sebe) a pomalý start (příliš mnoho synchronních hooků). Nejčastější chyba, se kterou se setkávám, je záměna návratových kódů — vývojáři používají exit 1, když ve skutečnosti myslí exit 2.

Hook se nespouští

Příznaky: Přidali jste hook, ale když událost nastane, nic se neděje.

Řešení:

• Překlep v matcheru, Matchery rozlišují velikost písmen. "write" nebude odpovídat nástroji Write. Přesné názvy nástrojů zkontrolujete pomocí /hooks.
• Nesprávný soubor nastavení, Hooky v ~/.claude/settings.json se neobjeví ve výstupu /hooks pro rozsah projektu. Zkuste .claude/settings.json v kořenovém adresáři projektu.
• Syntaktická chyba JSON, Zapomenutá čárka nebo chybějící závorka tiše deaktivuje celou konfiguraci hooků. Pro ověření spusťte settings.json přes jq ..
• disableAllHooks: true, Zkontrolujte, zda tento příznak nenechal zapnutý někdo (nebo předchozí ladicí relace).

Hook se spustí, ale akci nezablokuje

Příznaky: Váš hook PreToolUse se spustí, ale akce přesto proběhne.

Řešení:

• Nesprávný návratový kód, Návratový kód 1 znamená „chyba" (hook selhal), nikoli „blokovat". K zablokování akce použijte exit 2. Nachytá to téměř každého, jak je uvedeno v oficiální dokumentaci.
• Chybějící JSON na stdout, U blokujících hooků vypište zprávu ve formátu JSON, aby Claude věděl, proč byla akce zablokována: echo '{\"message\": \"Blocked: reason\"}'

Nekonečné smyčky

Příznaky: Claude neustále opakuje stejnou akci, nebo se váš stroj podezřele zahřívá.

Řešení:

• Hook Stop spouštějící akce, Pokud váš hook Stop zapisuje do souboru nebo spouští příkaz, který způsobí, že Claude odpoví, vytvořili jste smyčku. Hooky Stop by měly vykonávat pouze pasivní činnosti: logovat, upozorňovat, uklízet.
• Hook PostToolUse způsobující úpravy, Hook PostToolUse, který upravuje soubor, spustí další událost PostToolUse. Chraňte se proti tomu pomocí specifických matcherů nebo pole if.

Problémy s výkonem

Příznaky: Spuštění Claude nebo provádění nástrojů trvá znatelně déle.

Řešení:

• Příliš mnoho hooků SessionStart – každý z nich se při spuštění provádí synchronně. Udržujte je nenáročné (každý pod 1 sekundu).
• Náročné skripty v kritických cestách – hooky na PreToolUse a PostToolUse se spouštějí často. Pokud váš skript provádí síťové požadavky nebo náročné výpočty, přidejte pole timeout (v milisekundách) a zvažte, zda by místo toho neměl být HTTP hookem.
• Žádné cachování – pokud opakovaně kontrolujete stejnou věc (například „je to chráněná větev?"), uložte výsledek do dočasného souboru místo spouštění příkazů Git při každém vyvolání hooku.

Často kladené otázky

Co jsou hooky Claude Code a jak fungují?

Hooky Claude Code jsou uživatelem definované automatizační skripty, které se spouštějí při určitých událostech životního cyklu během relace Claude Code. Konfigurují se v souboru settings.json pomocí vzoru pro shodu (matcher) a handleru (příkaz shellu, HTTP endpoint, prompt nebo agent). Když nastane odpovídající událost, hook se automaticky spustí a pomocí návratových kódů (exit codes) řídí výsledek.

Jak nakonfiguruji hooky v settings.json aplikace Claude Code?

Přidejte objekt \"hooks\" do libovolného ze tří umístění konfigurace: ~/.claude/settings.json (globální pro uživatele), .claude/settings.json (sdílené pro projekt) nebo .claude/settings.local.json (osobní pro projekt). Každý typ události se mapuje na pole definic hooků s polem matcher, volitelným polem if a polem hooks obsahujícím objekty obslužných rutin s polem type a command nebo url.

Jaký je rozdíl mezi hooky PreToolUse a PostToolUse?

PreToolUse se spouští před spuštěním nástroje a umožňuje vám jej zablokovat pomocí exit kódu 2. PostToolUse se spouští po dokončení spuštění a hodí se pro formátování, testování nebo logování. PreToolUse slouží k prevenci a řízení přístupu. PostToolUse slouží k validaci a úklidu. Oba dostávají název nástroje a vstup jako JSON na stdin.

Dokáží hooky Claude Code blokovat nebezpečné příkazy?

Ano. Hooky PreToolUse s návratovým kódem 2 zablokují spuštění jakéhokoli nástroje. Můžete ochránit citlivé soubory před zápisem, blokovat shellové příkazy odpovídající nebezpečným vzorům jako rm -rf nebo git push main a zabránit přístupu k produkčním databázím. Blokovací zpráva se odešle zpět Claudovi jako zpětná vazba, aby mohl upravit svůj postup.

Jaké hook události jsou v Claude Code k dispozici?

Claude Code nabízí více než 15 událostí: PreToolUse a PostToolUse pro spouštění nástrojů, Notification pro upozornění, Stop pro ukončení relace, SessionStart pro inicializaci, UserPromptSubmit pro filtrování vstupu, PreCompact a PostCompact pro správu kontextu a novější události jako ConfigChange, FileChanged, TaskCreated a PermissionDenied. Úplnou přehledovou tabulku najdete v sekci o hook událostech výše.

Jak se hooky liší od nástrojů MCP a Skills?

Hooky jsou deterministické – vždy se spustí při odpovídajících událostech bez ohledu na to, jak se Claude rozhodne. Nástroje MCP rozšiřují schopnosti Claudu (přístup k databázi, volání API), ale Claude si vybírá, kdy je použije. Skills jsou opakovaně použitelné balíčky instrukcí vyvolávané pomocí slash příkazů. CLAUDE.md poskytuje pokyny pro chování. Hooky použijte, když se něco musí stát pokaždé, a MCP tehdy, když Claude potřebuje nové schopnosti.

Fungují hooky Claude Code v headless režimu?

Ano, s určitými výhradami. Hooky se v headless režimu (claude -p) spouštějí normálně, ale hooky specifické pro desktop, jako jsou macOS oznámení, vyžadují záložní řešení. Důležité je, že hooky PreToolUse, které skončí s kódem 2, mohou pozastavit headless relace a čekat na lidské schválení prostřednictvím --resume. To umožňuje CI/CD pipeline s člověkem ve smyčce, kde určité akce vyžadují ruční potvrzení.

Kolik hooků je příliš mnoho? Zpomalují hooky Claude Code?

Neexistuje žádný pevný limit, ale každý synchronní hook zvyšuje latenci. Hooky SessionStart se spouštějí při startu, takže by měly být rychlé (každý pod 1 sekundu). Hooky PreToolUse a PostToolUse se spouštějí při každém odpovídajícím volání nástroje — těžké skripty se zde rychle nasčítají. Doporučuji udržovat celkový počet hooků pod 10–15, používat pole if pro zúžení rozsahu a přidávat hodnoty timeout, aby se předešlo zacykleným skriptům.

Mohu pomocí hooků automaticky formátovat kód nástroji Prettier nebo Black?

Ano, jde o nejoblíbenější případ použití hooků. Vytvořte PostToolUse hook odpovídající Write|Edit, extrahujte cestu k souboru z JSON na stdin a spusťte příslušný formátovač podle přípony souboru. Kompletní konfiguraci připravenou ke zkopírování a vložení, která zpracovává soubory TypeScript, JavaScript a Python, najdete v příkladu číslo jedna v sekci produkčních příkladů.

Jsou hooky Claude Code bezpečné? Jaká jsou bezpečnostní rizika?

Hooky běží s vašimi plnými uživatelskými oprávněními, žádný sandbox neexistuje. Škodlivý hook by mohl přečíst vaše SSH klíče, smazat soubory nebo odcizit data. Používejte pouze hooky z důvěryhodných zdrojů, každý sdílený .claude/settings.json si před převzetím do projektu zkontrolujte a pro osobní hooky, které nechcete sdílet, používejte .claude/settings.local.json. Širší vzory bezpečnosti AI najdete v našem průvodci bezpečnostními mantinely pro LLM.