Stručné zhrnutie: Claude Code hooky sú automatizačné skripty, ktoré sa spustia v špecifických bodoch životného cyklu počas AI kódovacích relácií, čo umožňuje vývojárom spúšťať vlastné príkazy, validovať akcie, formátovať kód, posielať oznámenia a vynucovať pravidlá projektu. Tieto hooky sa integrujú s pracovným postupom Claude prostredníctvom udalostí ako SessionStart, PreToolUse a PostToolUse, pričom podporujú vzory spustenia založené na príkazoch, HTTP a výzvach s konfigurovateľnými časovými limitmi a správaním výstupného kódu.
Systém hookov Claude Code premieňa AI kódovacieho asistenta z užitočného nástroja na plne automatizované vývojové prostredie. Väčšina vývojárov si neuvedomuje mieru kontroly dostupnej prostredníctvom hookov.
Tu je však tá vec – hooky nie sú len o spúšťaní skriptov po úprave súborov. Poskytujú body prerušenia počas celého rozhodovacieho procesu Claude. Predtým, ako vykoná príkaz. Po zlyhaní volania nástroja. Keď potrebuje povolenie. Dokonca aj pred spracovaním používateľských výziev.
Táto príručka pokrýva všetko, čo poskytuje oficiálna dokumentácia, plus praktické vzory, ktoré diskusie komunity odhalili ako skutočne fungujúce v produkčných prostrediach.
Čo Claude Code hooky skutočne robia
Podľa oficiálnej dokumentácie Claude Code sú hooky používateľom definované shell príkazy, HTTP koncové body alebo injekcie výziev, ktoré sa spustia v špecifických bodoch životného cyklu Claude Code. Prijímajú štruktúrovaný JSON vstup cez stdin a ovládajú pracovný postup prostredníctvom výstupných kódov alebo HTTP odpovedí.
Automatizácia siaha hlbšie, než naznačuje väčšina príručiek. Hooky môžu úplne zablokovať vykonanie nástroja, vstreknúť dodatočný kontext do uvažovania Claude, spustiť externé služby a vynucovať validačné pravidlá, ktoré Claude musí dodržiavať.
Existujú tri základné typy hookov:
- Hooky príkazov: Shell skripty, ktoré komunikujú prostredníctvom stdout, stderr a výstupných kódov
- HTTP hooky: Vzdialené koncové body, ktoré prijímajú POST požiadavky a vracajú JSON odpovede
- Hooky výziev: Dynamické inštrukcie vstreknuté do kontextu Claude v špecifických udalostiach
Každý typ slúži na iné automatizačné vzory. Hooky príkazov zvládajú lokálnu validáciu a formátovanie. HTTP hooky sa integrujú s externými službami a databázami. Hooky výziev menia správanie Claude bez externých procesov.
Životný cyklus hookov a systém udalostí
Oficiálna dokumentácia definuje viacero udalostí hookov (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification a ďalšie), ktoré sa spustia počas toku vykonávania Claude Code. Pochopenie toho, kedy sa každá spustí, určuje, aká automatizácia je možná.
| Udalosť | Kedy sa spustí | Môže zablokovať |
|---|---|---|
| SessionStart | Keď relácia začne alebo pokračuje | Nie |
| UserPromptSubmit | Keď odošlete výzvu, pred spracovaním Claude | Áno |
| PreToolUse | Pred vykonaním volania nástroja | Áno |
| PermissionRequest | Keď sa zobrazí dialógové okno s povolením | Áno |
| PostToolUse | Po úspešnom volaní nástroja | Nie |
| PostToolUseFailure | Po zlyhaní volania nástroja | Nie |
| Notification | Keď Claude Code pošle oznámenie | Nie |
| SubmitMessage | Keď Claude odošle správu používateľovi | Nie |
| ContextCompaction | Keď sa okno kontextu blíži k limitom | Nie |
Možnosť blokovania je najdôležitejšia. Hooky PreToolUse môžu zabrániť nebezpečným operáciám pred ich vykonaním. Výstupný kód 1 blokuje akciu. Výstupný kód 0 ju umožňuje. Výstupný kód 2 vyzve Claude na prehodnotenie.
Ale počkajte. Hooky PostToolUse nemôžu vrátiť akcie späť, pretože nástroj sa už vykonal. Toto obmedzenie formuje štruktúru validačnej logiky. Kritické kontroly patria do PreToolUse. Upratovanie a formátovanie patria do PostToolUse.
Prehliadajte AI Tool Perks pri nastavovaní Claude Code
Ak pracujete s hookmi Claude Code, možno si vyberáte aj iné AI nástroje okolo vášho pracovného postupu. Get AI Perks zhromažďuje štartovacie kredity a zľavy na softvér pre AI a cloudové nástroje na jednom mieste. Platforma obsahuje viac ako 200 ponúk s podmienkami výhod a sprievodcom uplatnením pre každú z nich.
Hľadáte Claude alebo iné AI Tool Perks?
Navštívte Get AI Perks, aby ste:
- si prezreli ponuky Claude a iných AI nástrojov
- porovnali podmienky výhod pred žiadosťou
- našli zľavy pre startupy naprieč vašou sadou nástrojov
👉 Navštívte Get AI Perks a preskúmajte aktuálne ponuky AI softvéru.
Konfigurácia a štruktúra súborov
Hooky sú definované v súbore .claude/settings.json v rámci projektu. Schéma konfigurácie podporuje globálne hooky a nástrojovo špecifické zhodovače, ktoré filtrujú, kedy sa hooky spustia.
Základná štruktúra hooku príkazu:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Premenná ${file} sa rozbalí na skutočnú cestu k súboru zo vstupu nástroja. Podľa oficiálnej dokumentácie hooky podporujú tieto rozšírenia premenných v poliach príkazov a argumentov.
Hierarchia umiestnenia hookov
Claude Code kontroluje viacero umiestnení pre definície hookov s jasným poradím priorít:
- Na úrovni projektu: .claude/settings.json v aktuálnom pracovnom priestore
- Na používateľskej úrovni: ~/.claude/settings.json pre všetky relácie
- Poskytnuté pluginom: Hooky pribalené k nainštalovaným pluginom
Hooky projektu prepisujú používateľské hooky pre rovnakú udalosť. To umožňuje špecifické pravidlá formátovania pre projekt a zároveň zachováva globálne obslužné programy oznamovania.
Vzory zhodovača pre selektívne spustenie
Systém zhodovača filtruje hooky na špecifické nástroje alebo podmienky. Bez zhodovačov sa hooky spúšťajú pri každom výskyte ich udalosti.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Pole pathPattern prijíma glob vzory. Pole toolName sa zhoduje so vstavanými nástrojmi Claude ako edit_file, execute_command, read_file a create_directory.
Diskusie komunity odhalili, že kombinácie zhodovačov fungujú s AND logikou. Všetky špecifikované zhodovače sa musia zhodovať, aby sa hook spustil.
Hooky príkazov: Integrácia Shell skriptov
Hooky príkazov spúšťajú shell príkazy alebo skripty so štruktúrovaným JSON vstupom. Predstavujú najbežnejší typ hooku pre lokálnu automatizáciu.
Oficiálna dokumentácia špecifikuje, že hooky príkazov prijímajú JSON cez stdin s touto štruktúrou:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripty parsujú tento vstup na rozhodovanie. Python validačný hook by mohol vyzerať takto:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Výstupný kód 0 umožňuje operáciu. Výstupný kód 1 ju blokuje a zobrazí stderr správu Claude. Výstupný kód 2 spúšťa špeciálne správanie v závislosti od udalosti.
Správanie výstupného kódu 2
Podľa oficiálnej dokumentácie referenčných hookov má výstupný kód 2 význam špecifický pre udalosť (PreToolUse: blokuje a vyzýva na prehodnotenie; UserPromptSubmit: poskytuje kontext bez blokovania; PermissionRequest: blokuje povolenie):
- PreToolUse: Blokuje nástroj a vyzýva Claude na prehodnotenie so správou stderr ako kontextom
- UserPromptSubmit: Poskytuje výstup stderr ako dodatočný kontext bez blokovania
- PermissionRequest: Blokuje udelenie povolenia
Toto vytvára strednú cestu medzi tvrdým blokovaním a povolením. Claude dostáva spätnú väzbu o tom, prečo môže byť akcia problematická, a môže upraviť svoj prístup.
Asynchrónne hooky príkazov
Príznak async: true spúšťa hooky na pozadí bez blokovania pracovného postupu Claude. To je dôležité pre pomalé operácie, ako sú oznámenia o nasadení alebo zbieranie metrík.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Keď sa spustí asynchrónny hook, Claude Code spustí proces a pokračuje okamžite. Pole timeout nastavuje maximálny čas vykonávania v sekundách. Ak nie je zadaný, asynchrónne hooky používajú predvolený časový limit 10 minút.
Úprimne povedané: asynchrónne hooky nemôžu blokovať operácie, pretože sa spustia po tom, ako Claude pokračuje. Fungujú na zaznamenávanie, oznamovanie a upratovanie – nie na validáciu.
HTTP hooky: Integrácia externých služieb
HTTP hooky posielajú JSON payloady na vzdialené koncové body a parsujú odpovede pre kontrolu rozhodnutí. Umožňujú integráciu s validačnými službami, databázami a nástrojmi tretích strán.
Základná konfigurácia HTTP hooku:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Štruktúra payloadu zodpovedá vstupu hooku príkazu, ale prichádza ako telo HTTP POST. Odpoveď určuje ďalšiu akciu Claude.
Spracovanie HTTP odpovedí
Podľa oficiálnej dokumentácie HTTP hooky interpretujú odpovede na základe stavového kódu a obsahu tela:
| Stavový kód | Efekt | Zdroj správy |
|---|---|---|
| 200 | Povoliť operáciu | Telo odpovede (voliteľné) |
| 400 | Blokovať operáciu | Telo odpovede zobrazené Claude |
| 500 | Chyba hooku, povoliť operáciu | Zaznamenané, ale nezobrazené Claude |
| Iné | Povoliť operáciu | Zlyhanie hooku neblokuje pracovný postup |
Telo odpovede môže obsahovať pole správy, ktoré Claude vidí ako kontext. To umožňuje validačným službám vysvetliť, prečo bola operácia zablokovaná.
Interpolácia premenných prostredia
HTTP hooky podporujú syntax ${VAR} v poliach url, hlavičky a iných reťazcových poliach. Premenné sa rozbalia z prostredia, kde Claude Code beží.
Podľa oficiálnej dokumentácie MCP je rozšírenie premenných prostredia vrátane predvoleného záložného syntaxu: ${VAR:-default} sa rozbalí na VAR, ak je nastavené, inak používa predvolenú hodnotu.
Bezpečnostné obmedzenie: Podľa problému GitHub #28044 môžu HTTP hooky pristupovať iba k premenným prostredia explicitne uvedeným v poli konfigurácie allowedEnvVars. To zabraňuje náhodnému odhaleniu poverení.
Prompt hooky: Vstrekovanie kontextu
Prompt hooky vstrekujú dynamické inštrukcie do kontextu Claude pri špecifických udalostiach. Menia správanie bez externých procesov alebo volaní API.
| { “event”: “SessionStart”, “prompt”: “Pracujete na TypeScript projekte. Vždy používajte prísne kontroly null a preferujte async/await pred sľubmi.” } |
Vložený text sa stane súčasťou systémových inštrukcií Claude pre danú reláciu. Prompt hooky môžu tiež používať šablónové premenné, ktoré sa rozbalia na základe údajov udalosti.
Dynamické generovanie promptov
Podľa oficiálnej dokumentácie prompt hooky podporujú polia príkazov, ktoré generujú dynamické prompty:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Príkaz prijíma štandardný JSON vstup cez stdin a výstup textu výzvy na stdout. To umožňuje generovanie kontextovo uvedomelých inštrukcií založených na stave projektu.
Agent hooky
Agent hooky špecifikujú podagent, ktorý spracúva udalosť namiesto priameho vstrekovania výzvy. Podagent prijíma kontext o udalosti a môže vykonávať viacstupňové uvažovanie.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Volanie nástroja zlyhalo. Analyzujte chybu a navrhnite opravy.” } |
Názov podagenta musí byť definovaný v konfigurácii projektu. Agent hooky umožňujú komplexnú rozhodovaciu logiku, ktorú jednoduché vstrekovanie výzvy neposkytuje.
Praktické vzory hookov
Diskusie komunity a oficiálne príklady odhaľujú špecifické automatizačné vzory, ktoré spoľahlivo fungujú v produkcii.
Automatické formátovanie kódu po úpravách
Najbežnejší vzor automaticky formátuje kód po tom, ako Claude upraví súbory:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Premenná ${toolInput.path} sa rozbalí na cestu upraveného súboru. PostToolUse zabezpečuje, že formátovanie prebehne po úspešných úpravách, ale neblokuje pracovný postup Claude.
Blokovanie úprav chránených súborov
Hooky PreToolUse vynucujú pravidlá ochrany súborov:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skript overí cieľovú cestu voči chráneným vzorom a ukončí sa kódom 1, aby zablokoval zakázané úpravy.
Dostať upozornenie, keď Claude potrebuje vstup
Podľa oficiálnej príručky k pracovnému postupu môžu Notification hooky spustiť upozornenia na ploche alebo posielať správy externým službám:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Toto sa spustí vždy, keď Claude Code pošle oznámenie, vrátane čakania na vstup používateľa alebo po dokončení úlohy.
Znovu vstreknúť kontext po komprimácii
ContextCompaction hooky obnovia dôležitý kontext, keď sa konverzačné okno zaplní:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Výstup príkazu sa znovu vstrekne do kontextu Claude po tom, ako komprimácia odstráni staršie správy. Tým sa zabráni strate kritických špecifických inštrukcií projektu.
Audit zmien konfigurácie
Sledujte, kedy Claude upravuje konfiguračné súbory:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asynchrónne vykonávanie zabraňuje blokovaniu Claude, kým sa dokončia git operácie. To vytvára auditnú stopu zmien konfigurácie bez manuálneho stagingu.
JSON výstup a kontrola rozhodnutí
Hooky príkazov môžu generovať štruktúrovaný JSON, aby poskytli podrobnú spätnú väzbu nad rámec jednoduchých výstupných kódov. Podľa oficiálnej referencie umožňuje JSON výstup viacpoľové odpovede, ktoré Claude interpretuje na rozhodovanie.
| { “allowed”: false, “message”: “Tento súbor je chránený politikou tímu”, “suggestion”: “Vytvorte nový súbor v src/features/ namiesto toho” } |
Pole allowed kontroluje, či operácia pokračuje. Správa sa zobrazí Claude ako kontext. Pole suggestion poskytuje alternatívne prístupy.
Aby hooky generovali JSON, musia:
- Zapísať platný JSON na stdout
- Ukončiť s kódom 0 (pre povolené) alebo 1 (pre blokované)
- Obsahovať minimálne pole allowed, ktoré je booleovské
Claude Code parsuje JSON a používa ho na vylepšenie spätnej väzby. Výstupné kódy stále určujú primárne rozhodnutie, ale JSON poskytuje bohatší kontext.
Referenčné polia vstupu hookov
Všetky hooky prijímajú JSON objekt cez stdin s bežnými poľami plus údaje špecifické pre udalosť. Pochopenie kompletnej schémy umožňuje sofistikovanejšiu logiku hookov.
Bežné vstupne polia
Každý hook prijíma tieto základné polia:
- event: Názov udalosti hooku (napr. “PreToolUse”)
- sessionId: Jedinečný identifikátor aktuálnej relácie Claude
- turnId: Identifikátor aktuálneho otočenia konverzácie
- timestamp: ISO 8601 časová značka, kedy sa udalosť spustila
Polia udalostí nástroja
Udalosti PreToolUse, PostToolUse a PostToolUseFailure zahŕňajú:
- toolName: Názov volaného nástroja (edit_file, execute_command atď.)
- toolInput: Objekt obsahujúci parametre vstupu nástroja
- toolResponse: Výstupný dátový súbor nástroja (len PostToolUse)
- error: Podrobnosti o chybe vrátane správy a kódu (len PostToolUseFailure)
Štruktúra toolInput sa líši podľa nástroja. Pre edit_file obsahuje cestu a obsah. Pre execute_command obsahuje príkaz a argumenty.
Polia udalostí povolenia
Udalosti PermissionRequest zahŕňajú:
- permissionType: Typ požadovaného povolenia (file_write, command_execute atď.)
- requestedAction: Konkrétna akcia vyžadujúca povolenie
- resourcePath: Cesta k súboru alebo identifikátor zdroja, ktorého sa to týka
MCP Tool hooky
Podľa oficiálnej referencie hookov sa hooky môžu zhodovať s nástrojmi Model Context Protocol (MCP) pomocou poľa zhodovača mcpTool. To umožňuje vykonávanie hookov, keď Claude používa externé nástroje poskytované MCP servermi.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Hodnota mcpTool sa zhoduje s názvom nástroja vo formáte server-name/tool-name. To umožňuje validačnú logiku pre databázové dotazy, volania API alebo iné externé operácie.
Požiadavky na funkcie na GitHub naznačujú rastúci záujem o hlbšiu integráciu MCP, vrátane hookov, ktoré môžu kontrolovať oznámenia MCP servera a reagovať na externé udalosti.
Bezpečnostné hľadiská
Hooky sa vykonávajú s rovnakými oprávneniami ako samotný Claude Code. To vytvára bezpečnostné dôsledky pre prostredia s viacerými používateľmi a zdieľané konfigurácie.
Sandobox vykonávania príkazov
Podľa problému GitHub #28044, HTTP hooky prechádzajú cez sandbox proxy, ktorá obmedzuje sieťový prístup a filtruje premenné prostredia. Hooky príkazov nemajú takéto obmedzenia – bežia s plným shell prístupom.
Dokumentácia odporúča tieto postupy:
- Nikdy neukladajte poverenia do príkazov hookov
- Používajte premenné prostredia pre citlivé údaje
- Validujte všetok vstup z rozšírení ${…}
- Implementujte časové limity pre externé služby
- Používajte asynchrónne hooky pre nekritické operácie, aby ste predišli zablokovaniu pri zlyhaniach
Izolácia vykonávania hookov
Hooky na používateľskej úrovni v ~/.claude/settings.json sa vzťahujú na všetky projekty. To vytvára riziká pri práci naprieč rôznymi hranicami dôvery. Hooky na úrovni projektu prepisujú používateľské hooky, ale nemôžu ich úplne zakázať.
Menu /hooks v Claude Code zobrazuje všetky aktívne hooky pre aktuálnu reláciu. Prehliadanie tohto zoznamu pred prácou na citlivých projektoch pomáha identifikovať potenciálne bezpečnostné obavy.
Ladění a riešenie problémov
Zlyhania hookov sa nie vždy jasne prejavia v konverzácii Claude. Oficiálna dokumentácia poskytuje niekoľko prístupov k ladeniu.
Logy vykonávania hookov
Claude Code loguje vykonávanie hookov do výstupu ladenia relácie. Podľa príručky na riešenie problémov povolenie ladenia logovania odhalí:
- Ktoré hooky sa zhodovali pre každú udalosť
- JSON vstup poslaný každému hooku
- Výstup stdout a stderr z procesov hookov
- Výstupné kódy a čas vykonávania
- HTTP stavové kódy a telá pre HTTP hooky
Povoľte ladenie logovania nastavením CLAUDE_DEBUG=1 v prostredí pred spustením Claude Code.
Nezávislé testovanie hookov
Hooky príkazov je možné testovať mimo Claude Code manuálnym vytvorením JSON vstupu:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Toto overí logiku hooku bez spustenia skutočných operácií Claude. Výstupný kód a výstup stdout/stderr by mali zodpovedať očakávanému správaniu.
Bežné zlyhania hookov
Diskusie komunity identifikujú tieto časté problémy:
- Chyby časového limitu: Predvolený 10-minútový časový limit príliš krátky pre pomalé operácie – zvýšte pomocou poľa timeout
- Zlyhania rozšírenia cesty: Premenné ako ${file} nedefinované pre udalosti, ktoré neobsahujú kontext súboru
- Chyby oprávnení: Skripty hookov nemajú oprávnenia na vykonanie – spustite chmod +x script.sh
- Chyby parsovania JSON: Nesprávny JSON výstup z hookov – validujte pomocou jq pred vrátením
- Nedostupnosť premenných prostredia: Premenné sa nešíria do procesu hooku – skontrolujte prostredie Claude Code
Vplyvy výkonu hookov
Synchrónne hooky blokujú pracovný postup Claude až do dokončenia. Predvolený 10-minútový časový limit zabraňuje nekonečnému zablokovaniu, ale aj krátke oneskorenia sa hromadia naprieč viacerými operáciami.
Odborníci hlásia, že jednoduché validačné hooky majú zanedbateľný vplyv na výkon. Hooky na formátovanie súborov spôsobujú citeľný, ale prijateľný vplyv na výkon. Volania externých API môžu spôsobiť trenie v pracovnom postupe. Operácie s vysokou výpočtovou náročnosťou profitujú z asynchrónneho vykonávania.
Dávkovanie hookov
Viaceré hooky sa môžu zhodovať s rovnakou udalosťou. Podľa referenčnej dokumentácie sa hooky vykonávajú sekvenčne v poradí definície. Ak ktorýkoľvek hook zablokuje operáciu, zostávajúce hooky sa nevykonajú.
Toto je dôležité pre výkon. Päť synchrónnych hookov po 200 ms každý pridá jednu sekundu na udalosť. Kombinovanie súvisiacich validácií do jedného hooku znižuje réžiu.
Pokročilé vzory
Okrem základnej automatizácie umožňujú hooky sofistikované prispôsobenie pracovného postupu.
Stavové reťazce hookov
Hooky môžu udržiavať stav medzi vykonaniami pomocou súborov alebo databáz. PostToolUse hook môže zaznamenať úspešné operácie, ktoré potom PreToolUse hook validuje:
| #!/bin/bash # Záznam úspešných úprav echo “${toolInput.path}” >> .claude/edit-history.txt |
Sprievodný PreToolUse hook by mohol skontrolovať túto históriu, aby zabránil redundantným operáciám alebo vynútil obmedzenia poradia.
Podmienená aktivácia hookov
Premenné prostredia ovládajú správanie hookov za behu. Nastavenie CLAUDE_SKIP_HOOKS=1 zakáže hooky pre núdzové situácie.
Samotné hooky môžu kontrolovať príznaky prostredia:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Použiť prísnu validáciu exit 1 fi exit 0 |
Toto umožňuje správanie v režime vývoja vs. produkčnom režime bez zmien konfigurácie.
Viacstupňová validácia
PreToolUse hooky môžu implementovať viacúrovňovú validáciu, kde výstupný kód 2 umožňuje Claude pokračovať s varovaniami:
- Tvrdé zlyhania (výstup 1): Blokovanie nebezpečných operácií
- Jemné varovania (výstup 2): Upozornenie Claude na prehodnotenie
- Prejsť s kontextom (výstup 0 + JSON): Poskytnutie dodatočných informácií
Toto vytvára spektrum validácie, ktoré je jemnejšie ako binárne povoliť/odmietnuť.
Integrácia s CI/CD
Podľa oficiálnej dokumentácie integrácie platformy Claude Code beží v prostrediach CI/CD pre automatizovanú kontrolu kódu a triedenie problémov. Hooky rozširujú túto automatizáciu.
Pracovné postupy GitHub Actions môžu definovať hooky, ktoré vynucujú tímové politiky počas automatizovaných relácií:
| -- meno: Spustiť Claude Code s prísnymi hookmi env: STRICT_MODE: 1 run: | claude “Skontrolujte tento PR a navrhnite vylepšenia” |
Príznak STRICT_MODE aktivuje podmienenú validačnú logiku v skriptoch hookov. To zaisťuje, že automatizované relácie dodržiavajú prísnejšie pravidlá ako interaktívny vývoj.
Generovanie auditnej stopy
PostToolUse hooky v prostrediach CI vytvárajú podrobné auditné záznamy všetkých operácií Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Logovanie na pozadí neovplyvňuje výkon, ale poskytuje kompletnú históriu operácií pre dodržiavanie predpisov a ladenie.
Menu /hooks
Claude Code poskytuje príkaz /hooks, ktorý zobrazuje všetky aktívne hooky pre aktuálnu reláciu. Podľa oficiálnej dokumentácie toto menu zobrazuje:
- Typ udalosti hooku
- Vzory zhodovača
- Príkaz alebo URL koncový bod
- Či sa hook spúšťa asynchrónne
- Zdroj konfigurácie (projekt, používateľ alebo plugin)
Výber hooku zobrazí jeho kompletnú konfiguráciu a umožní dočasné zakázanie pre aktuálnu reláciu.
Zakázanie alebo odstránenie hookov
Hooky je možné zakázať bez odstránenia konfigurácie pridaním “enabled”: false k definícii hooku. To zachová konfiguráciu a zároveň zabráni jej spusteniu.
Ak chcete trvalo odstrániť hook, odstráňte jeho záznam z príslušného súboru settings.json. Zmeny sa prejavia pri ďalšom reštarte relácie alebo pri spustení príkazu /reload.
Hooky v zručnostiach a agentoch
Podľa oficiálnej dokumentácie sa hooky definované v rámci konfigurácií zručností alebo podagentov aplikujú iba vtedy, keď sa daná zručnosť alebo agent spustí. To umožňuje špecializovanú automatizáciu pre konkrétne pracovné postupy.
Podagent na ladenie môže obsahovať hooky, ktoré logujú všetky volania nástrojov:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Tieto hooky sa spustia iba počas relácií agenta debuggera, nie počas bežnej prevádzky Claude Code.
Odkazovanie na skripty podľa cesty
Príkazy hookov podporujú relatívne aj absolútne cesty. Relatívne cesty sa riešia z koreňa projektu, kde Claude Code beží.
Najlepšie postupy z diskusií komunity:
- Ukladajte skripty hookov do adresára .claude/hooks/
- Používajte popisné názvy: validate-typescript.sh namiesto hook1.sh
- Nastavte skripty ako spustiteľné: chmod +x .claude/hooks/*.sh
- Zahrňte shebang riadok: #!/usr/bin/env bash alebo #!/usr/bin/env python3
- Pridajte spracovanie chýb pomocou set -e v bash skriptoch
Budúce možnosti hookov
Požiadavky na funkcie na GitHub odhaľujú plánované a požadované vylepšenia hookov:
- Inline skript hooky: Definujte logiku hooku priamo v settings.json bez externých súborov
- Integrácia MCP nástrojov: Spustite MCP server nástroje z hookov namiesto shell príkazov
- Kolaborácia viacerých agentov: Hooky, ktoré koordinujú medzi inštanciami Claude na rôznych strojoch
- Rozšírené typovanie: TypeScript definície typov pre schémy vstupu/výstupu hookov
Podľa problému GitHub #4274 je požiadavka na integrované typy hookov (MCP nástroj, inline skript, volanie API) zameraná na zjednodušenie konfigurácie a zlepšenie používateľskej skúsenosti vývojárov.
Často kladené otázky
Môžu hooky zabrániť Claude v spustení nebezpečných príkazov?
Áno. Hooky PreToolUse môžu zablokovať akékoľvek vykonanie nástroja ukončením s kódom 1. To zahŕňa úpravy súborov, vykonávanie príkazov a volania MCP nástrojov. Hook prijíma kompletný vstup nástroja a môže validovať podľa akýchkoľvek kritérií pred povolením operácie.
Ako mám ladiť hook, ktorý nefunguje?
Povoľte ladenie logovania s CLAUDE_DEBUG=1 pred spustením Claude Code. Skontrolujte logy relácie pre podrobnosti o vykonávaní hookov vrátane toho, ktoré hooky sa zhodovali, JSON vstup, výstup stdout/stderr a výstupné kódy. Testujte hooky nezávisle zasielaním vzorových JSON do skriptu hooku.
Fungujú hooky so všetkými platformami Claude Code?
Hooky fungujú v CLI, desktopovej aplikácii a rozšírení VS Code. Podľa oficiálnej dokumentácie sa hooky spúšťajú všade tam, kde Claude Code beží s prístupom k súborovému systému. Prehliadačové Claude a mobilné aplikácie nepodporujú hooky kvôli obmedzeniam sandoxingu.
Môžu hooky meniť odpovede alebo správanie Claude?
Prompt hooky vstrekujú inštrukcie, ktoré ovplyvňujú správanie Claude. Agent hooky delegujú spracovanie udalostí na špecializované podagenty. Hooky však nemôžu priamo meniť generovaný text alebo proces uvažovania Claude – fungujú poskytovaním kontextu a blokovaním operácií.
Aký je rozdiel medzi asynchrónnymi a synchrónnymi hookmi?
Synchrónne hooky blokujú pracovný postup Claude až do dokončenia alebo časového limitu. Asynchrónne hooky bežia na pozadí bez blokovania. Synchrónne hooky môžu zabrániť operáciám pomocou výstupných kódov. Asynchrónne hooky nemôžu blokovať, pretože Claude pokračuje predtým, ako sa hook dokončí. Používajte asynchrónne na logovanie a oznamovanie, synchrónne na validáciu.
Ako môžem zdieľať hooky naprieč tímom?
Súbor .claude/settings.json commitujte do verzovacieho systému. Hooky na úrovni projektu sa aplikujú na všetkých členov tímu, ktorí klonujú repozitár. Pre politiky celej organizácie môžu tímy udržiavať spoločný súbor nastavení na používateľskej úrovni, ktorý členovia skopírujú do ~/.claude/settings.json.
Môžu HTTP hooky volať interné API za firewallami?
Áno, ak Claude Code beží v prostredí s sieťovým prístupom k týmto API. HTTP hooky vykonávajú štandardné POST požiadavky zo stroja, na ktorom beží Claude Code. Korporátne firewally a VPN sa uplatňujú normálne. Sandbox proxy spomenutý v dokumentácii kontroluje expozíciu premenných prostredia, nie sieťové smerovanie.
Zvyšujú hooky využitie tokenov Claude Code?
Prompt hooky vstrekujú text do kontextu Claude, čo spotrebúva tokeny. Hooky príkazov a HTTP hooky priamo neovplyvňujú využitie tokenov, ale ich výstup (chybové správy, návrhy) sa stáva súčasťou kontextu konverzácie. Výstupný kód 2 s vysvetľujúcimi správami pridáva viac kontextu ako výstupný kód 1 s jednoduchým blokovaním.
Záver
Claude Code hooky premieňajú AI asistenta z výkonného nástroja na plne automatizovanú vývojovú platformu. Systém udalostí poskytuje body prerušenia počas celého pracovného postupu Claude – od inicializácie relácie až po komprimáciu kontextu.
Hooky príkazov zvládajú lokálnu validáciu a formátovanie. HTTP hooky integrujú externé služby a databázy. Prompt hooky menia správanie prostredníctvom vstrekovania kontextu. Spoločne umožňujú automatizačné vzory, ktoré vynucujú tímové politiky, udržiavajú kvalitu kódu a integrujú sa s existujúcou vývojovou infraštruktúrou.
Systém zhodovača filtruje hooky na špecifické nástroje a vzory súborov. Výstupné kódy a JSON výstup riadia tok rozhodnutí. Asynchrónne vykonávanie zabraňuje blokovaniu pri pomalých operáciách. Kompletná schéma konfigurácie podporuje všetko od jednoduchého automatického formátovania až po komplexnú viacstupňovú validáciu.
Začnite so základnými PostToolUse hookmi na formátovanie kódu. Pridajte PreToolUse validáciu, keď sa objavia politiky. Experimentujte s prompt hookmi na zmenu správania. Vytvorte HTTP integrácie pre celotímové vynucovanie.
Pozrite si oficiálnu dokumentáciu Claude Code pre kompletnú referenciu hookov a aktualizovanú schému konfigurácie, keď sa dodajú nové možnosti.
