Kiir kokkuvõte: Claude Code hookid on automaatika skriptid, mis täidetakse AI kodeerimise sessioonide konkreetsetel elutsükli punktidel, võimaldades arendajatel käivitada kohandatud käske, valideerida toiminguid, vormindada koodi, saata teateid ja jõustada projektireegleid. Need hookid integreeruvad Claude'i töövooga selliste sündmuste kaudu nagu SessionStart, PreToolUse ja PostToolUse, toetades käsu-, HTTP- ja käsuviipapõhiseid täitmismustreid koos konfigureeritavate aegumiste ja väljumiskoodi käitumisega.
Claude Code'i hooki süsteem muudab AI kodeerimise assistendi abivaldast tööriistast täielikult automatiseeritud arenduskeskkonnaks. Enamik arendajaid ei mõista hookide kaudu saadaoleva kontrolli ulatust.
Asi on aga selles – hookid ei seisne ainult skriptide käitamises pärast faili muudatusi. Need pakuvad vahelesurumispunkte kogu Claude'i otsustusprotsessi vältel. Enne käsu täitmist. Pärast tööriista kutse ebaõnnestumist. Kui see vajab luba. Isegi enne kasutajate käsuviipade töötlemist.
See juhend hõlmab kõike, mida ametlik dokumentatsioon pakub, lisaks praktilisi mustreid, mis kogukonna arutelude kohaselt tootmiskeskkondades tegelikult töötavad.
Mida Claude Code hookid tegelikult teevad
Ametliku Claude Code dokumentatsiooni kohaselt on hookid kasutaja määratud kestkäskud, HTTP-lõpp-punktid või käsuviipade süstimised, mis täidetakse Claude Code'i elutsükli konkreetsetel punktidel. Nad saavad JSON-sisendit standard sisendi kaudu ja kontrollivad töövoogu väljumiskoodide või HTTP-vastuste kaudu.
Automaatika läheb sügavamale, kui enamik juhendeid soovitab. Hookid võivad täielikult blokeerida tööriista täitmist, süstida täiendavat konteksti Claude'i põhjendusse, käivitada välised teenused ja jõustada valideerimisreegleid, mida Claude peab järgima.
Olemas on kolm peamist hooki tüüpi:
- Käsu hookid: Kest skriptid, mis suhtlevad standard väljundi, standard vea ja väljumiskoodide kaudu
- HTTP hookid: Kaugelt asuvad lõpp-punktid, mis saavad POST-päringuid ja tagastavad JSON-vastuseid
- Käsuviip hookid: Dünaamilised juhised, mis süstitakse Claude'i konteksti konkreetsete sündmuste korral
Iga tüüp teenindab erinevaid automaatika mustreid. Käsu hookid tegelevad kohaliku valideerimise ja vormindamisega. HTTP hookid integreeruvad väliste teenuste ja andmebaasidega. Käsuviip hookid muudavad Claude'i käitumist ilma väliste protsessideta.
Hooki elutsükkel ja sündmuste süsteem
Ametlik dokumentatsioon määratleb mitmeid hooki sündmusi (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification ja teised), mis käivituvad Claude Code'i täitmise ajal. Millal igaüks neist käivitub, mõistmine määrab, milline automaatika on võimalik.
| Sündmus | Millal see käivitub | Kas saab blokeerida |
|---|---|---|
| SessionStart | Kui sessioon algab või jätkub | Ei |
| UserPromptSubmit | Kui esitate käsuviiba, enne kui Claude seda töötleb | Jah |
| PreToolUse | Enne tööriista kutse täitmist | Jah |
| PermissionRequest | Kui ilmub loa dialoog | Jah |
| PostToolUse | Pärast tööriista kutse edukat täitmist | Ei |
| PostToolUseFailure | Pärast tööriista kutse ebaõnnestumist | Ei |
| Notification | Kui Claude Code saadab teate | Ei |
| SubmitMessage | Kui Claude esitab kasutajale sõnumi | Ei |
| ContextCompaction | Kui konteksti akna piirid lähenevad | Ei |
Blokeerimise võime on kõige olulisem. PreToolUse hookid võivad ohtlikud toimingud enne nende täitmist blokeerida. Väljumiskood 1 blokeerib toimingu. Väljumiskood 0 lubab selle. Väljumiskood 2 paneb Claude'i uuesti kaaluma.
Aga oodake. PostToolUse hookid ei saa toiminguid tühistada, kuna tööriist on juba täidetud. See piirang kujundab valideerimisloogika struktuuri. Kriitilised kontrollid kuuluvad PreToolUse'i. Puhastamine ja vormindamine kuuluvad PostToolUse'i.
Sirvi AI tööriistade eeliseid Claude Code'i seadistamisel
Kui töötate Claude Code hookidega, valite tõenäoliselt ka teisi AI tööriistu oma töövoo ümber. Get AI Perks kogub ühte kohta alguse krediite ja tarkvarasoodustusi AI ja pilve tööriistadele. Platvorm sisaldab üle 200 pakkumise koos eeliste tingimuste ja nõudmise juhistega igaühele.
Otsid Claude'i või teiste AI tööriistade eeliseid?
Kontrollige Get AI Perks, et:
- sirvida Claude'i ja teiste AI tööriistade pakkumisi
- võrrelda eeliste tingimusi enne taotlemist
- leida alguse soodustusi kogu oma tööriistade virnast
👉 Külastage Get AI Perks, et uurida praeguseid AI tarkvara eeliseid.
Konfiguratsioon ja failistruktuur
Hookid on määratletud .claude/settings.json failis projekti sees. Konfiguratsiooni skeem toetab globaalseid hooke ja tööriistaspetsiifilisi sobitajaid, mis filtreerivad, millal hookid täidetakse.
Põhiline käsu hooki struktuur:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Muutuja ${file} laieneb tegelikuks faili teeks tööriista sisendist. Ametliku dokumentatsiooni kohaselt toetavad hookid käsu- ja argumentide väljades nende muutuja laiendusi.
Hooki asukoha hierarhia
Claude Code otsib hooki definitsioonide jaoks mitmeid asukohti, millel on selge eelisjärjekord:
- Projekti tase: .claude/settings.json praeguses tööruumis
- Kasutaja tase: ~ / .claude / settings.json kõigi sessioonide jaoks
- Plugin-pakutavad: Hookid installitud pluginitega kaasas
Projekti hookid asendavad kasutaja hookid sama sündmuse korral. See võimaldab projekti spetsiifilisi vormindamisreegleid, säilitades samal ajal globaalsed teavituste töötlejad.
Sobitajate mustrid valikuliseks täitmiseks
Sobitajate süsteem filtreerib hookid konkreetsete tööriistade või tingimuste järgi. Ilma sobitajateta käivituvad hookid iga sündmuse esinemise korral.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Välja ${pathPattern} aktsepteerib glob süntaksit. Välja ${toolName} sobib Claude'i sisseehitatud tööriistadega nagu edit_file, execute_command, read_file ja create_directory.
Kogukonna arutelud näitavad, et sobitajate kombinatsioonid töötavad JA loogikaga. Kõik määratud sobitajad peavad sobima, et hook täidetaks.
Käsu hookid: Kest skriptide integreerimine
Käsu hookid täidavad kest käske või skripte struktureeritud JSON-sisendiga. Need esindavad kõige levinumat hooki tüüpi kohaliku automaatika jaoks.
Ametlik dokumentatsioon täpsustab, et käsu hookid saavad JSON-i standard sisendi kaudu järgmise struktuuriga:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skriptid parsilvad seda sisendit, et teha otsuseid. Pythoni valideerimise hook võiks välja näha nii:#!/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äljumiskood 0 lubab toimingu. Väljumiskood 1 blokeerib selle ja näitab Claude'ile standard vea sõnumit. Väljumiskood 2 käivitab sündmusest sõltuvalt erilise käitumise.
Väljumiskoodi 2 käitumine
Ametliku hookide viite dokumentatsiooni kohaselt on väljumiskoodil 2 sündmusespetsiifiline tähendus (PreToolUse: blokeerib ja kutsub uuesti kaalumisele; UserPromptSubmit: pakub konteksti ilma blokeerimata; PermissionRequest: blokeerib loa):
- PreToolUse: Blokeerib tööriista ja kutsub Claude'i uuesti kaaluma standard vea sõnumiga kontekstina
- UserPromptSubmit: Pakub standard vea väljundit täiendava kontekstina ilma blokeerimata
- PermissionRequest: Blokeerib loa andmise
See loob kesktee kõva blokeerimise ja lubamise vahel. Claude saab tagasisidet selle kohta, miks tegevus võib olla problemaatiline, ja saab oma lähenemist kohandada.
Asünkroonsed käsu hookid
Async: true lipp käivitab hookid taustal ilma Claude'i töövoogu blokeerimata. See on oluline aeglaste toimingute, nagu juurutamisteate või meetrikogumise jaoks.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Kui asünkroonne hook käivitub, käivitab Claude Code protsessi ja jätkab kohe. Timeout väli määrab maksimaalse täitmise aja sekundites. Kui seda ei ole määratud, kasutavad asünkroonsed hookid vaikimisi 10-minutilist aegumist.
Päris jutt: asünkroonsed hookid ei saa toiminguid blokeerida, kuna nad töötavad pärast seda, kui Claude jätkab. Nad töötavad logimise, teavituste ja puhastamise jaoks – mitte valideerimise jaoks.
HTTP hookid: Välise teenuse integreerimine
HTTP hookid saadavad JSON-payloadid kaugematele lõpp-punktidele ja parsilvad vastuseid otsuste juhtimiseks. Need võimaldavad integreerimist valideerimisteenuste, andmebaaside ja kolmandate osapoolte tööriistadega.
Põhiline HTTP hooki konfiguratsioon:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Payloadi struktuur vastab käsu hooki sisendile, kuid saabub HTTP POST kehaga. Vastus määrab Claude'i järgmise sammu.
HTTP vastuse käsitlus
Ametliku dokumentatsiooni kohaselt tõlgendavad HTTP hookid vastuseid olekukoodi ja keha sisu põhjal:
| Olekukood | Mõju | Sõnumi allikas |
|---|---|---|
| 200 | Lubab toimingu | Vastuse keha (valikuline) |
| 400 | Blokeerib toimingu | Vastuse keha näidatakse Claude'ile |
| 500 | Hooki viga, lubab toimingu | Logitakse, kuid Claude'ile ei näidata |
| Muud | Lubab toimingu | Hooki ebaõnnestumine ei blokeeri töövoogu |
Vastuse keha võib sisaldada sõnumi välja, mida Claude näeb kontekstina. See võimaldab valideerimisteenustel selgitada, miks toiming oli blokeeritud.
Keskkonnamuutuja interpolatsioon
HTTP hookid toetavad ${VAR} süntaksit url, headers ja muudes stringiväljades. Muutujad laienevad keskkonnast, kus Claude Code töötab.
Ametliku MCP dokumentatsiooni kohaselt sisaldab keskkonnamuutuja laiendus vaikimisi tagasiside süntaksit: ${VAR:-default} laieneb VAR-iks, kui see on määratud, vastasel juhul kasutab vaikimisi väärtust.
Turvalisuse piirang: vastavalt GitHubi probleemile #28044 saavad HTTP hookid juurdepääsu ainult keskkonnamuutujatele, mis on selgesõnaliselt loetletud lubatudEnvVars konfiguratsiooniväljas. See takistab juhuslikku krediidi lekkimist.
Käsuviip hookid: Konteksti süstimine
Käsuviip hookid süstivad dünaamilisi juhiseid Claude'i konteksti konkreetsetel sündmustel. Nad muudavad käitumist ilma väliste protsesside või API kutseteta.
| { “event”: “SessionStart”, “prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.” } |
Süstitud tekst muutub Claude'i süsteemi juhiste osaks selleks sessiooniks. Käsuviip hookid võivad kasutada ka mallimuutujaid, mis laienevad sündmuse andmete põhjal.
Dünaamiline käsuviipade loomine
Ametliku dokumentatsiooni kohaselt toetavad käsuviip hookid käsu välju, mis loovad dünaamilisi käsuviipasid:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Käsk saab standard JSON sisendi standard sisendi kaudu ja väljastab käsuviiba teksti standard väljundisse. See võimaldab kontekstiteadlikku juhiste loomist projekti oleku põhjal.
Agent-põhised hookid
Agenti hookid määravad alagentuuri, mis töötleb sündmust otse käsuviiba süstimise asemel. Alagentuur saab sündmuse kohta konteksti ja saab sooritada mitmeastmelist põhjendust.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.” } |
Nimetatud alagentuur peab olema projekti konfiguratsioonis määratletud. Agenti hookid võimaldavad keerukat otsustusloogikat, mida lihtne käsuviip süstimine ei paku.
Praktilised hooki mustrid
Kogukonna arutelud ja ametlikud näited toovad välja spetsiifilisi automaatika mustreid, mis töötavad tootmiskeskkonnas usaldusväärselt.
Koodi automaatne vormindamine pärast muudatusi
Kõige tavalisem muster vormindab koodi automaatselt pärast seda, kui Claude muudab faile:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Muutuja ${toolInput.path} laieneb muudetud faili teeks. PostToolUse tagab vormindamise pärast edukat muudatust, kuid ei blokeeri Claude'i töövoogu.
Kaitstud failide muudatuste blokeerimine
PreToolUse hookid jõustavad failikaitse reegleid:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skript valideerib sihttee kaitstud mustrite suhtes ja väljub koodiga 1, et blokeerida keelatud muudatusi.
Saate teate, kui Claude vajab sisendit
Ametliku töövoo juhendi kohaselt võivad teate hookid käivitada töölaua hoiatusi või saata sõnumeid välistele teenustele:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
See käivitub iga kord, kui Claude Code saadab teate, sealhulgas oodates kasutaja sisendit või pärast ülesande täitmist.
Taas-süstke kontekst pärast kokkusurumist
ContextCompaction hookid taastavad olulise konteksti, kui vestlusaken täitub:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Käsu väljund süstitakse tagasi Claude'i konteksti pärast seda, kui kokkusurumine eemaldab vanemad sõnumid. See hoiab ära kriitiliste projekti spetsiifiliste juhiste kaotamise.
Konfiguratsiooni muudatuste auditeerimine
Jälgige, millal Claude muudab konfiguratsioonifaile:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asünkroonne täitmine hoiab ära Claude'i blokeerimise, samal ajal kui git toimingud lõpevad. See loob auditraja konfiguratsiooni muudatustest ilma käsitsi lavastamiseta.
JSON-väljund ja otsuste juhtimine
Käsu hookid võivad väljastada struktureeritud JSON-i, et pakkuda üksikasjalikku tagasisidet, mis ületab lihtsad väljumiskoodid. Ametliku viite kohaselt võimaldab JSON-väljund mitmeväljalisi vastuseid, mida Claude tõlgendab otsuste tegemiseks.
| { “allowed”: false, “message”: “This file is protected by team policy”, “suggestion”: “Create a new file in src/features/ instead” } |
Välja ${allowed} kontrollib, kas toiming jätkub. Sõnum ilmub Claude'ile kontekstina. Välja ${suggestion} pakub alternatiivseid lähenemisi.
Et hookid väljastaksid JSON-i, peavad nad:
- Kirjutama kehtiva JSON-i standard väljundisse
- Välja tulema koodiga 0 (lubatud) või 1 (blokeeritud)
- Sisaldama vähemalt boolean välja ${allowed}
Claude Code parsilneb JSON-i ja kasutab seda tagasisideahela täiustamiseks. Väljumiskoodid määravad endiselt peamise otsuse, kuid JSON pakub rikkamat konteksti.
Hooki sisendiväljade viide
Kõik hookid saavad standard sisendi kaudu JSON-objekti, millel on tavalised väljad ja sündmusespetsiifilised andmed. Täieliku skeemi mõistmine võimaldab keerukamat hooki loogikat.
Tavalised sisendiväljad
Iga hook saab need baasväljad:
- event: Hooki sündmuse nimi (nt „PreToolUse“)
- sessionId: Praeguse Claude sessiooni unikaalne identifikaator
- turnId: Praeguse vestlusvoorude identifikaator
- timestamp: ISO 8601 ajatempel, kui sündmus käivitus
Tööriista sündmuse väljad
PreToolUse, PostToolUse ja PostToolUseFailure sündmused sisaldavad:
- toolName: Käivitatava tööriista nimi (edit_file, execute_command jne)
- toolInput: Objekt, mis sisaldab tööriista sisendiparameetreid
- toolResponse: Tööriista väljundandmed (ainult PostToolUse)
- error: Vea üksikasjad, sealhulgas sõnum ja kood (ainult PostToolUseFailure)
Tööriista sisendi struktuur varieerub tööriistast sõltuvalt. edit_file puhul sisaldab see teed ja sisu. execute_command puhul sisaldab see käsku ja argumente.
Loa sündmuse väljad
PermissionRequest sündmused sisaldavad:
- permissionType: Taotletud loa tüüp (file_write, command_execute jne)
- requestedAction: Konkreetne tegevus, mis vajab luba
- resourcePath: Mõjutatud failitee või ressursi identifikaator
MCP Tööriista hookid
Ametliku hookide viite kohaselt võivad hookid sobitada Model Context Protocol (MCP) tööriistadega, kasutades mcpTool sobitaja välja. See võimaldab hooki täitmist, kui Claude kasutab MCP serverite poolt pakutavaid väliseid tööriistu.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Väärtus ${mcpTool} sobib tööriista nimega vormingus server-name/tool-name. See võimaldab valideerimisloogikat andmebaasipäringute, API kutsete või muude väliste toimingute jaoks.
GitHubi funktsioonitaotlused näitavad kasvavat huvi sügavama MCP integratsiooni vastu, sealhulgas hookide vastu, mis saavad kontrollida MCP serveri teateid ja reageerida välistele sündmustele.
Turvalisuse kaalutlused
Hookid täidetakse samade lubadega nagu Claude Code ise. See tekitab turvalisusimplikatsioone mitme kasutaja keskkondade ja jagatud konfiguratsioonide jaoks.
Käsu täitmise liivakast
Vastavalt GitHubi probleemile #28044 suunatakse HTTP hookid liivakast proksi kaudu, mis piirab võrgu juurdepääsu ja filtreerib keskkonnamuutujad. Käsu hookidel pole selliseid piiranguid – nad töötavad täieliku kest juurdepääsuga.
Dokumentatsioon soovitab järgmisi tavasid:
- Ärge kunagi salvestage krediite hooki käskudesse
- Kasutage tundlike andmete jaoks keskkonnamuutujad
- Valideerige kogu sisend ${...} laiendustest
- Rakendage välise teenuste aegumise piiranguid
- Kasutage mitte-kriitiliste toimingute jaoks asünkroonseid hooke, et vältida ebaõnnestumiste korral blokeerimist
Hooki täitmise isolatsioon
~/.claude/settings.json kasutaja tasemel hookid kehtivad kõigi projektide kohta. See tekitab riske erinevate usalduspiiridega töötades. Projekti tasemel hookid asendavad kasutaja hookid, kuid ei saa neid täielikult keelata.
Claude Code'i menüüs /hooks kuvatakse kõik praeguse sessiooni jaoks aktiivsed hookid. Selle loendi ülevaatamine enne tundlike projektidega töötamist aitab tuvastada võimalikke turvalisusprobleeme.
Silumine ja tõrkeotsing
Hooki ebaõnnestumised ei pruugi Claude'i vestluses alati selgelt välja paista. Ametlik dokumentatsioon pakub mitmeid silumise lähenemisi.
Hooki täitmise logid
Claude Code logib hooki täitmist sessiooni silumisväljundisse. Tõrkeotsingu juhendi kohaselt paljastab silumis logimise lubamine:
- Millised hookid sobisid iga sündmuse jaoks
- JSON sisend, mis saadeti igale hookile
- Hooki protsesside standard väljund ja standard vea väljund
- Väljumiskoodid ja täitmise aeg
- HTTP vastukoodid ja kehad HTTP hookide jaoks
Luba silumis logimine, määrates CLAUDE_DEBUG=1 keskkonnas enne Claude Code'i käivitamist.
Hookide sõltumatu testimine
Käsu hookid saab testida väljaspool Claude Code'i, konstrueerides käsitsi JSON sisendi:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
See valideerib hooki loogikat ilma tegelikke Claude toiminguid käivitamata. Väljumiskood ja standard väljund/standard vea väljund peaksid vastama oodatavale käitumisele.
Levinumad hooki ebaõnnestumised
Kogukonna arutelud tuvastavad need sagedased probleemid:
- Aegumise vead: Vaikimisi 10-minutiline aegumine liiga lühike aeglaste toimingute jaoks – suurendage koos timeout väljaga
- Tee laienduse ebaõnnestumised: Muutujad nagu ${file} on defineerimata sündmuste korral, mis ei sisalda faili konteksti
- Loa vead: Hooki skriptidel puudub täitmise luba – käivitage chmod +x script.sh
- JSON parsimise vead: Hookidest väljastatud vigase JSON-i – valideerige jq abil enne tagastamist
- Keskkonnamuutujate kättesaadavus: Muutujad ei ole edastatud hooki protsessi – kontrollige Claude Code'i keskkonda
Hooki jõudluse mõju
Sünkroonsed hookid blokeerivad Claude'i töövoogu kuni lõpetamiseni. Vaikimisi 10-minutiline aegumine hoiab ära lõputu rippumise, kuid isegi lühikesed viivitused kuhjuvad mitmete toimingute jooksul.
Praktiseerijad teatavad, et lihtsatel valideerimis hookidel on minimaalne jõudluse mõju. Failivorminduse hookid põhjustavad märgatavat, kuid vastuvõetavat jõudluse mõju. Välised API kutseid võivad tekitada töövoo hõõrdumist. Rasked arvutusoperatsioonid saavad kasu asünkroonsest täitmisest.
Hooki partiid
Mitmed hookid võivad sama sündmusega sobida. Viite dokumentatsiooni kohaselt täidetakse hookid järjestikku definitsiooni järgi. Kui mõni hook blokeerib toimingu, ei täideta ülejäänud hookid.
See on jõudluse seisukohast oluline. Viis sünkroonset hooki 200 ms kohta lisavad ühe sekundi sündmuse kohta. Seotud valideerimiste ühendamine üheks hookiks vähendab ülekoormust.
Täpsemad mustrid
Põhilisest automaatikaest kaugemal võimaldavad hookid keerukat töövoo kohandamist.
Olekuga hooki ketid
Hookid saavad säilitada oleku täitmiste vahel, kasutades faile või andmebaase. PostToolUse hook võib salvestada edukad toimingud, mida PreToolUse hook hiljem valideerib:
| #!/bin/bash # Salvesta edukad muudatused echo “${toolInput.path}” >> .claude/edit-history.txt |
Saatev PreToolUse hook võiks kontrollida seda ajalugu, et vältida korduvate toiminguid või jõustada järjestuse piiranguid.
Tingimuslik hooki aktiveerimine
Keskkonnamuutujad kontrollivad hooki käitumist käitusajal. CLAUDE_SKIP_HOOKS=1 seadistamine keelab hookid hädaolukordade jaoks.
Hookid ise saavad kontrollida keskkonna lippe:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Rakenda ranget valideerimist exit 1 fi exit 0 |
See võimaldab arendusrežiimi versus tootmisrežiimi käitumist ilma konfiguratsiooni muudatusteta.
Mitmeastmeline valideerimine
PreToolUse hookid saavad rakendada mitmeastmelist valideerimist, kus väljumiskood 2 lubab Claude'il jätkata hoiatustega:
- Hard failures (exit 1): Blokeerib ohtlikud toimingud
- Soft warnings (exit 2): Hoiatab Claude'i uuesti kaaluma
- Pass with context (exit 0 + JSON): Pakub täiendavat teavet
See loob valideerimise spektri, mis on nüansirikkam kui binaarne lubamine/keelamine.
Integratsioon CI/CD-ga
Ametliku platvormi integratsiooni dokumentatsiooni kohaselt töötab Claude Code CI/CD keskkondades automaatseks koodi ülevaatuseks ja probleemide triaažiks. Hookid laiendavad seda automaatikat.
GitHub Actions töövood saavad määratleda hookid, mis jõustavad meeskonnapoliitikaid automaatsete sessioonide ajal:
| -- name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
STRICT_MODE lipp aktiveerib tingimusliku valideerimise loogika hooki skriptides. See tagab, et automaatsed sessioonid järgivad rangemaid reegleid kui interaktiivne arendus.
Auditraja loomine
PostToolUse hookid CI keskkondades loovad üksikasjalikud auditeerimise logid kõigist Claude toimingutest:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Taustal logimine ei mõjuta jõudlust, kuid pakub täielikku toimingute ajalugu vastavuse ja silumise jaoks.
Menüü /hooks
Claude Code pakub käsku /hooks, mis kuvab kõik praeguse sessiooni jaoks aktiivsed hookid. Ametliku dokumentatsiooni kohaselt näitab see menüü:
- Hooki sündmuse tüüp
- Sobitajate mustrid
- Käsk või URL-i lõpp-punkt
- Kas hook töötab asünkroonselt
- Konfiguratsiooni allikas (projekt, kasutaja või plugin)
Hooki valimine näitab selle täielikku konfiguratsiooni ja võimaldab ajutiselt keelata praeguse sessiooni jaoks.
Hookide keelamine või eemaldamine
Hookid saab keelata ilma konfiguratsiooni eemaldamata, lisades hooki definitsiooni välja "enabled": false. See säilitab konfiguratsiooni, takistades samal ajal täitmist.
Hooki püsivaks eemaldamiseks kustutage selle kirje vastavast settings.json failist. Muudatused jõustuvad järgmisel sessiooni taaskäivitamisel või /reload käivitamisel.
Hookid oskustes ja agentides
Ametliku dokumentatsiooni kohaselt kehtivad oskuse või alagentuuri konfiguratsioonide sees määratletud hookid ainult siis, kui see oskus või agent täitub. See võimaldab spetsialiseeritud automaatikat konkreetsete töövoogude jaoks.
Silumise alagentuur võib sisaldada hookid, mis logivad kõik tööriista kutsed:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Need hookid käivituvad ainult siluri agentuuri sessioonide ajal, mitte tavalise Claude Code töö ajal.
Viide skriptidele tee järgi
Hooki käsud toetavad nii suhtelisi kui ka absoluutseid teid. Suhtelised teed lahendatakse projekti juurest, kus Claude Code töötab.
Parimad tavad kogukonna aruteludest:
- Salvestage hooki skriptid .claude/hooks/ kataloogi
- Kasutage kirjeldavaid nimesid: validate-typescript.sh mitte hook1.sh
- Muutke skriptid täidetavaks: chmod +x .claude/hooks/*.sh
- Lisage shebang rida: #!/usr/bin/env bash või #!/usr/bin/env python3
- Lisage bash skriptidesse veahaldus koos set -e
Tulevased hooki võimalused
GitHubi funktsioonitaotlused toovad välja kavandatud ja soovitud hooki täiustused:
- Juhisskripti hookid: Määrake hooki loogika otse settings.json-is ilma väliste failideta
- MCP tööriista integratsioon: Kutsuge MCP serveri tööriistu hookidest kestkäskude asemel
- Mitme agendi koostöö: Hookid, mis koordineerivad Claude eksemplaride vahel erinevatel masinatel
- Täiustatud tüübid: TypeScripti tüübi definitsioonid hooki sisend/väljund skeemide jaoks
Vastavalt GitHubi probleemile #4274, integreeritud hooki tüüpide (MCP tööriist, juhisskript, API kutse) taotlus on suunatud konfiguratsiooni lihtsustamisele ja arendaja kogemuse parandamisele.
Korduma kippuvad küsimused
Kas hookid saavad takistada Claude'il ohtlike käskude täitmist?
Jah. PreToolUse hookid saavad blokeerida mis tahes tööriista täitmist, väljudes koodiga 1. See hõlmab failide muutmist, käskude täitmist ja MCP tööriista kutseid. Hook saab täieliku tööriista sisendi ja võib enne toimingu lubamist valideerida mis tahes kriteeriumide alusel.
Kuidas siluda hooki, mis ei tööta?
Luba silumis logimine CLAUDE_DEBUG=1 abil enne Claude Code'i käivitamist. Kontrollige sessiooni logisid hooki täitmise üksikasjade jaoks, sealhulgas millised hookid sobisid, saadetud JSON sisend, standard väljund/standard vea väljund ja väljumiskoodid. Testige hookid sõltumata, saates proovi JSON-i hooki skriptile.
Kas hookid töötavad kõigi Claude Code platvormidega?
Hookid töötavad CLI-s, töölaua rakenduses ja VS Code laienduses. Ametliku dokumentatsiooni kohaselt täidetakse hookid kõikjal, kus Claude Code töötab failisüsteemi juurdepääsuga. Brauseripõhised Claude'i ja mobiilirakendused ei toeta hooki liivakasti piirangute tõttu.
Kas hookid saavad Claude'i vastuseid või käitumist muuta?
Käsuviip hookid süstivad juhiseid, mis mõjutavad Claude'i käitumist. Agendi hookid delegeerivad sündmuste käsitlemist spetsialiseeritud alagentuuridele. Kuid hookid ei saa otseselt muuta Claude'i genereeritud teksti või põhjenduse protsessi – nad töötavad, pakkudes konteksti ja blokeerides toiminguid.
Mis vahe on asünkroonsel ja sünkroonsel hookil?
Sünkroonsed hookid blokeerivad Claude'i töövoogu kuni lõpetamiseni või aegumiseni. Asünkroonsed hookid töötavad taustal ilma blokeerimata. Sünkroonsed hookid saavad väljumiskoodide kaudu toiminguid takistada. Asünkroonsed hookid ei saa blokeerida, kuna Claude jätkab enne hooki lõpetamist. Kasutage logimise ja teavituste jaoks asünkroonseid, valideerimise jaoks sünkroonseid.
Kuidas jagada hookid meeskonnaga?
Commit .claude/settings.json faili versioonikontrolli. Projekti tasemel hookid kehtivad kõigile meeskonnaliikmetele, kes kloonivad repositooriumi. Organisatsiooniülese poliitika jaoks saavad meeskonnad säilitada jagatud kasutaja tasemel seadete faili, mille liikmed kopeerivad ~/.claude/settings.json.
Kas HTTP hookid saavad helistada tulemüüri taga olevatele sisevõrgu API-dele?
Jah, kui Claude Code töötab keskkonnas, millel on nende API-de võrgu juurdepääs. HTTP hookid teevad standard POST päringuid Claude Code'i käitavast masinast. Korporatiivsed tulemüürid ja VPN-id kehtivad tavaliselt. Dokumentatsioonis mainitud liivakast proksi kontrollib keskkonnamuutuja eksponeerimist, mitte võrgu marsruutimist.
Kas hookid suurendavad Claude Code'i tokenite kasutamist?
Käsuviip hookid süstivad teksti Claude'i konteksti, mis tarbib tokeneid. Käsu- ja HTTP hookid ei mõjuta otseselt tokenite kasutamist, kuid nende väljund (veasõnumid, ettepanekud) muutub osa vestluskontekstist. Väljumiskood 2 selgitavate sõnumitega lisab rohkem konteksti kui väljumiskood 1 lihtsa blokeerimisega.
Kokkuvõte
Claude Code hookid muudavad AI assistendi võimsast tööriistast täielikult automatiseeritud arendusplatvormiks. Sündmuste süsteem pakub vahelesurumispunkte kogu Claude'i töövoo vältel – sessiooni initsialiseerimisest kuni konteksti kokkusurumiseni.
Käsu hookid tegelevad kohaliku valideerimise ja vormindamisega. HTTP hookid integreerivad välised teenused ja andmebaasid. Käsuviip hookid muudavad käitumist konteksti süstimise kaudu. Koos võimaldavad need automaatika mustrid, mis jõustavad meeskonnapoliitikaid, säilitavad koodi kvaliteedi ja integreeruvad olemasoleva arendusinfrastruktuuriga.
Sobitajate süsteem filtreerib hookid konkreetsete tööriistade ja failimustrite järgi. Väljumiskoodid ja JSON-väljund kontrollivad otsustusvoogu. Asünkroonne täitmine hoiab ära aeglaste toimingute blokeerimise. Täielik konfiguratsiooni skeem toetab kõike alates lihtsast automaatvormindamisest kuni keeruka mitmeastmelise valideerimiseni.
Alustage lihtsate PostToolUse hookidega koodi vormindamiseks. Lisage PreToolUse valideerimine vastavalt kujunevatele poliitikatele. Katsetage käsuviip hookidega käitumise muutmiseks. Looge HTTP integratsioone meeskonnaüleseks jõustamiseks.
Kontrollige ametlikku Claude Code dokumentatsiooni täieliku hookide viite ja värskendatud konfiguratsiooni skeemi jaoks, kui uued võimalused jõustuvad.
