Claude Code hooky: kompletní průvodce (2026)

Skill může být ignorován. To není chyba skillů, je to celý smysl designu: Claude si přečte popis, rozhodne, jestli aktuální úkol odpovídá, a tělo skillu načte jen tehdy, pokud si myslí, že ano. Většinou je tenhle úsudek správný. Někdy ne, a úkol, na kterém na tom záleží nejvíc – code review těsně před mergem, záznam v logu, který musí existovat za každou cenu – je přesně ten úkol, kde „nejspíš" nestačí.

Hooky jsou druhá polovina Claude Code. Hook je shellový příkaz, který harness spustí, když nastane konkrétní událost, ať by na to nějaký skill pomyslel, nebo ne. Mezi událostí a příkazem nesedí žádný úsudek modelu. Spustí se, pokaždé, v pořadí, a jeho návratový kód dokáže Clauda zastavit úplně. Pokud jste někdy chtěli říct „vždy naformátuj tenhle soubor po úpravě" nebo „nikdy nedovol Claudovi sáhnout na tenhle adresář", hook je nástroj postavený přesně na tuhle větu.

Tenhle průvodce pokrývá, co hooky jsou, schéma settings.json, na kterém stojí, šest receptů, které si dnes můžete rovnou vložit, jak hooky a skilly spolupracují, a chybové stavy, které vám sežerou odpoledne, pokud nevíte, kde je hledat.

Co hook vlastně je

Claude Code během session vyvolává pojmenované události: před spuštěním nástroje, po jeho spuštění, když Claude dokončí odpověď, když by se měla zobrazit notifikace. Hook naváže shellový příkaz na jednu z těchto událostí, volitelně omezenou na konkrétní nástroje. Harness spustí váš příkaz, předá mu kontext jako JSON na stdin a pak přečte návratový kód, aby rozhodl, co se stane dál.

Události, které budete používat nejčastěji:

• PreToolUse — spustí se před provedením volání nástroje. Hook tady dokáže volání rovnou zablokovat.
• PostToolUse — spustí se po dokončení volání nástroje. Dobré na formátování, testování nebo logování toho, co se právě stalo.
• Stop — spustí se, když Claude dokončí svůj tah a chystá se vrátit kontrolu zpátky vám.
• Notification — spustí se, když by vám Claude Code zobrazil systémovou notifikaci (žádosti o oprávnění, výzvy při nečinnosti).
• UserPromptSubmit — spustí se, když odešlete zprávu, ještě předtím, než ji Claude uvidí.

To je celý mechanismus. Důvod, proč na tom záleží, je garance, kterou vám dává a kterou skill strukturálně dát nemůže.

Myšlenkový model: deterministické vs. diskreční

Tohle je jedna myšlenka, kterou stojí za to si zapamatovat, i kdybyste si z tohoto průvodce nic jiného neodnesli.

Skill je diskreční. Claude si na začátku session přečte jeho popis a později, na základě vašeho požadavku, rozhodne, jestli ho načte a bude se jím řídit. Dobré skilly se spouštějí spolehlivě, ale „spolehlivě" je pořád pravděpodobnost, ne garance. Claude může nepochopit nejednoznačný prompt, nebo mohou mít dva skilly překrývající se popisy, které shodu zmatou – tenhle chybový stav rozebíráme podrobněji v našem průvodci, proč se skilly nespouští.

Hook je deterministický. Neptá se Clauda, jestli má běžet. Nečte popis a nehodnotí relevanci. Harness uvidí událost a příkaz se spustí, tečka. Pokud je událost PostToolUse na nástroji Edit, váš formátovač se spustí po každé úpravě, včetně té, kterou Claude udělal, zatímco myslel na úplně něco jiného.

Tenhle rozdíl se přímo promítá do toho, kdy po čem sáhnout:

	Skill	Hook
Spustí se, když	Claude to vyhodnotí jako relevantní	Kdykoli nastane daná událost
Lze přeskočit	Ano, špatnou shodou nebo zaneprázdněným kontextem	Ne
Nejlepší pro	Úsudek, strukturu, „jak dělat X dobře"	Vynucení, „X se musí stát vždy"
Chybový stav	Tiché nespuštění	Tichý špatný návratový kód, nebo blokování všeho

Pokud věta, kterou vynucujete, začíná „Claude by měl vždy..." nebo „Claude nesmí nikdy...", chcete hook. Pokud začíná „když Claude dělá X, měl by k tomu přistupovat jako...", chcete skill. Formátování kódu po každé úpravě je hook; psaní idiomatického Pythonu je skill. Blokování commitů do main je hook; strukturování dobré commit zprávy je skill.

Anatomie hooku v settings.json

Hooky žijí pod klíčem hooks v .claude/settings.json (na úrovni projektu) nebo ~/.claude/settings.json (na úrovni uživatele) – jiný soubor než CLAUDE.md, a stojí za to je nezaměňovat: CLAUDE.md je próza, kterou Claude čte, settings.json je konfigurace, kterou harness vykonává. Pokud jste ani jedno ještě nenastavili, náš průvodce CLAUDE.md a náš kompletní návod na nastavení pokrývají zbytek zásobníku, ve kterém tento soubor žije. Tady je minimální, ale kompletní okomentovaný příklad hooku:

{
  "hooks": {
    // The event name — PreToolUse, PostToolUse, Stop, Notification, etc.
    "PostToolUse": [
      {
        // matcher filters which tool calls trigger this hook.
        // Omit it (or use "*") to match every tool.
        "matcher": "Edit|Write",
        "hooks": [
          {
            // "command" is currently the only hook type.
            "type": "command",
            // The shell command to run. Receives event JSON on stdin.
            "command": "npx prettier --write \"$(echo $CLAUDE_TOOL_INPUT | jq -r .file_path)\"",
            // Optional: kill the command if it hangs.
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Pár věcí stojí za zmínku, protože na nich lidé zakopávají:

Pole matcher pracuje s názvem nástroje, ne s cestami k souborům nebo obsahem. "Edit|Write" odpovídá nástrojům Edit a Write; "Bash" odpovídá volání shellu. Pokud potřebujete filtrovat podle cesty k souboru nebo obsahu příkazu, udělejte to uvnitř svého skriptu čtením JSON payloadu, ne v matcheru.

Každý klíč události drží pole bloků matcherů a každý blok matcheru drží pole příkazů hooku, takže můžete připojit několik příkazů k jednomu matcheru, nebo jeden příkaz k několika matcherům, aniž byste duplikovali konfiguraci.

Příkaz dostává payload události jako JSON na stdin: název nástroje, vstup nástroje a pro PostToolUse i výsledek nástroje. Hook, který jedná podle konkrétního upravovaného souboru, čte tenhle JSON místo toho, aby předpokládal, že pracovní adresář shellu vypráví celý příběh.

Návratové kódy nesou význam. Exit 0 znamená „v pořádku, pokračuj". Nenulový exit u PreToolUse hooku zablokuje volání nástroje a stderr vrátí Claudovi zpátky jako důvod. Nenulový exit u PostToolUse se jen zaloguje; nástroj už proběhl, takže není co blokovat.

Šest receptů, které můžete použít dnes

Jsou záměrně úzké. Zkopírujte blok, upravte příkaz a ověřte na nepotřebném souboru, že dělá, co čekáte, než mu budete věřit na skutečné práci.

1. Automatické formátování po každé úpravě

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npx prettier --write . --ignore-unknown"
          }
        ]
      }
    ]
  }
}

Spustí Prettier po každé úpravě nebo zápisu. U velkých repozitářů nahraďte plošnou . cestou odvozenou z JSON vstupu hooku, abyste formátovali jen dotčený soubor.

2. Blokování úprav chráněných cest

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/guard_paths.py"
          }
        ]
      }
    ]
  }
}

guard_paths.py přečte cestu k souboru z JSON na stdin, zkontroluje ji proti zákazovému seznamu (migrations/, .env, infra/prod/) a při shodě skončí s kódem 1 a zprávou na stderr. Je to nejbližší věc k pevné hranici oprávnění, jakou Claude Code má.

3. Spuštění testů po změnách zdrojového kódu

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npm test -- --onlyChanged --silent"
          }
        ]
      }
    ]
  }
}

Dává Claudovi okamžitý signál, když úprava rozbije test, místo čekání, až si toho všimnete až při review. Držte testovací příkaz úzký (--onlyChanged, rychlá podmnožina), jinak se z toho stane recept šest ze sekce „kdy ne" níže.

4. Desktopová notifikace, když Claude skončí

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Specifické pro macOS (na Linuxu nahraďte notify-send). Užitečné ve chvíli, kdy začnete spouštět delší autonomní tahy a přestanete celou dobu sledovat terminál.

5. Logování každého bash příkazu

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> \"$CLAUDE_PROJECT_DIR/.claude/bash-history.log\""
          }
        ]
      }
    ]
  }
}

Auditní stopa, která nezávisí na tom, že si vzpomenete zkontrolovat přepis. Na sdíleném stroji nebo v repozitáři s požadavkem na compliance je tohle skoro povinné.

6. Lint brána před commitem

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block_bad_commit.sh"
          }
        ]
      }
    ]
  }
}

block_bad_commit.sh přečte stdin, zkontroluje, jestli je příkaz git commit, a pokud ano, nejdřív spustí váš linter, přičemž při selhání skončí s nenulovým kódem. To promění „prosím zlintuj před commitem" z žádosti, na kterou Claude může zapomenout, na pravidlo, přes které se nedostane.

Hooky a skilly společně

Nejsou to konkurenční nástroje; nejlepší nastavení používají oba na to, v čem je každý dobrý. Konkrétní příklad: tým, který jsme testovali, chtěl mít každý commit napsaný v jejich firemním stylu – rozkazovací způsob, ohraničený prefix, tělo vysvětlující proč – a zároveň chtěl blokovat commity, pokud se diff dotýkal databázové migrace bez odpovídajícího rollback souboru.

Stylová část je úsudek. Co se počítá za dobré „proč", se liší podle změny, a žádný shellový skript spolehlivě nenapíše dobrou prózu. To je práce pro skill: něco jako Git Workflow Coach načtený vždy, když Claude chystá commit, který učí strukturu a dává příklady dobrých a líných commit zpráv. Claude si ho přečte, aplikuje úsudek a napíše zprávu, která odpovídá vzoru, aniž by šlo o vyplnění šablony. Pokud tým navíc provozuje přísný red-green-refactor, Test-Driven Development je stejný druh doplňku typu úsudek-ne-zákon: formuje, jak Claude k práci přistupuje, a tuhle část hook zvládnout nedokáže.

Pravidlo pro migrace není úsudek, je to zákon: rollback soubor buď existuje, nebo ne, a tým nechtěl, aby možností bylo „Claude rozhodl, že tenhle ho nepotřebuje". To je PreToolUse hook z receptu šest, upravený tak, aby kontroloval existenci párového souboru místo spouštění linteru, a rovnou blokoval volání git commit, pokud soubor chybí.

Spusťte je společně a dostanete dobrou commit zprávu, která má zároveň garantovaný průchod kontrolou migrace, protože skill obstarává část, která potřebuje mozek, a hook obstarává část, která potřebuje zeď. Ani jeden nenahrazuje druhý. Skill nemůže garantovat compliance a hook, který by u každého commitu psal „fix: various changes", by byl k ničemu. Naše stránka nejlepší programátorské skilly řadí úsudkovou stranu tohoto páru podle otestovaného skóre, pokud si vybíráte první skill ke spuštění vedle svých hooků.

Ladění hooků

Hooky selhávají spíš tiše než hlasitě. Co se obvykle rozbije:

Uvozovky. Příkazy hooku jsou shellové řetězce uvnitř JSON řetězců, takže neošetřená " rozbije parsování JSON dřív, než se váš příkaz vůbec spustí. Kdykoli váháte, dejte skutečnou logiku do skriptového souboru a nechte příkaz hooku, ať ho jen zavolá (bash .claude/hooks/my-hook.sh), místo vkládání komplexního jednořádkového příkazu.

Návratové kódy, které neznamenají to, co si myslíte. Skript hooku, který narazí na nesouvisející chybu (chybějící závislost, odepřené oprávnění), skončí s nenulovým kódem stejně jako hook, který chce záměrně blokovat. Pokud PreToolUse hook začne blokovat každé volání nástroje a nenapsali jste ho tak přísně, zkontrolujte, jestli skript skutečně selhává, místo aby posuzoval.

Předpoklady o PATH. Hooky běží v shellovém prostředí, které se nemusí shodovat s vaším interaktivním terminálem. Příkaz, který funguje v pořádku, když ho napíšete sami, může uvnitř hooku selhat, protože nvm, virtuální prostředí nebo nástroj nainstalovaný přes shellový plugin v tomhle kontextu není na PATH. Používejte absolutní cesty k binárkám, nebo na začátku skriptu načtěte správné prostředí.

Tiché předpoklady o stdin. Pokud váš skript čeká JSON na stdin a nedostane ho, protože jste ho testovali přímým spuštěním místo napipování ukázkového payloadu, bude se pod harnessem chovat jinak, než se choval ve vašem terminálu.

Timeouty. Hook bez timeoutu, který zamrzne, zamrzne celý tah. Nastavte explicitní timeout na cokoli, co se dotýká sítě nebo pomalého subprocesu.

Kdy hooky nepoužívat

Hooky se levně píšou a snadno se přehání s jejich používáním. Chybový stav není hook, který dělá špatnou věc, ale hook, který dělá správnou věc příliš často. PostToolUse hook, který po úplně každé úpravě spustí celou vaši testovací sadu, promění pětisekundovou změnu na dvouminutové čekání, opakované u každé úpravy v session, která jich udělá dvacet.

Palcové pravidlo: pokud příkaz hooku trvá víc než sekundu nebo dvě, zúžte matcher, zúžte, co kontroluje, nebo ho přesuňte na méně častou událost. Test-při-každé-úpravě se s rostoucí nákladností kontroly mění na test-při-zápisu-souboru a pak na test-před-commitem. Přizpůsobte náklad hooku tomu, jak často se jeho událost spouští, a zvažte, jestli skill, který jen načítá kontext a nespouští proces, není lepší volba pro cokoliv, co není striktně vynucování.

Taky se vyplatí nesahat po hooku, abyste opravili problém se spouštěním skillu. Pokud se skill nespouští, když by měl, opravou je lepší popis, ne hook, protože hooky spouštějí shellové příkazy a neumí načíst obsah skillu. Pro tenhle chybový stav viz proč se skilly nespouští.

FAQ

Zpomalují hooky každou session Claude Code?

Jen ty události, na které je připojíte, a jen o tolik, jak dlouho trvá váš příkaz. Hook na PostToolUse pro Edit se spustí jednou na úpravu; rychlý formátovač je nepostřehnutelný, celá testovací sada se pocítí na každé úpravě, což je případ popsaný výše v sekci kdy hooky nepoužívat.

Dokáže hook zastavit Clauda úplně od nějaké akce?

Ano, přesně na to jsou PreToolUse hooky. Skončete s nenulovým kódem a volání nástroje se zablokuje ještě před spuštěním, přičemž stderr se obvykle vrátí zpátky Claudovi jako důvod. To je mechanismus za receptem dva (chráněné cesty) a receptem šest (lint brána).

Kam mám dát konfiguraci hooků – nastavení projektu, nebo uživatele?

Na úroveň projektu (.claude/settings.json, commitované), pokud se má vztahovat na všechny na dané codebase: formátování, chráněné cesty, kontroly migrací. Na úroveň uživatele (~/.claude/settings.json) pro osobní preferenci, jako je desktopová notifikace v receptu čtyři.

Jaký je rozdíl mezi hookem a skillem, který říká „vždy formátuj kód"?

Hook se skutečně vždy spustí. Skill, který Claudovi říká, aby vždy formátoval kód, je pořád jen instrukce, kterou si Claude přečte a rozhodne se ji dodržet; je to silné pobídnutí, ne garance, a v daném tahu soupeří o pozornost s ostatními věcmi v kontextu. Pokud je „vždy" požadavek, ne preference, použijte hook.

Můj hook se vůbec nespouští. Co zkontrolovat jako první?

Ověřte, že je soubor s nastavením platný JSON (přebytečná čárka nebo neošetřená uvozovka dokáže tiše vyřadit celý blok hooks) a že jsou název události a matcher napsané přesně, jak se očekává; oba rozlišují velká a malá písmena. Pak zkontrolujte, jestli jste neupravili nastavení projektu, zatímco session čte nastavení uživatele, nebo naopak.