Vinnige Opsomming: Claude Code hooks is outomatisering-skrifte wat op spesifieke lewensiklus-punte tydens KI-kodering-sessies uitgevoer word, wat ontwikkelaars toelaat om pasgemaakte opdragte uit te voer, aksies te valideer, kode te formateer, kennisgewings te stuur en projekreëls af te dwing. Hierdie hooks integreer met Claude’s werkstroom deur gebeurtenisse soos SessionStart, PreToolUse, en PostToolUse, wat opdrag-gebaseerde, HTTP-gebaseerde, en prompt-gebaseerde uitvoeringspatrone ondersteun met konfigureerbare tyds límite en uitgangskode-gedrag.
Claude Code’s hook-stelsel omskep die KI-kodering-assistent van 'n nuttige hulpmiddel na 'n volledig geoutomatiseerde ontwikkelingsomgewing. Die meeste ontwikkelaars besef nie die omvang van beheer wat beskikbaar is deur hooks nie.
Hier is die ding egter – hooks gaan nie net oor die uitvoer van skrifte na lêer wysigings nie. Hulle bied onderskep-punte deur Claude’s hele besluitnemingsproses. Voordat dit 'n opdrag uitvoer. Nadat 'n hulpmiddel-oproep misluk het. Wanneer dit toestemming benodig. Selfs voor die verwerking van gebruikersprompts.
Hierdie gids dek alles wat die amptelike dokumentasie bied, plus praktiese patrone wat gemeenskapsbesprekings onthul eintlik werk in produksie-omgewings.
Wat Claude Code Hooks Eintlik Doen
Volgens die amptelike Claude Code dokumentasie, is hooks gebruiker-gedefinieerde shell-opdragte, HTTP-eindpunte, of prompt-inspuitings wat op spesifieke punte in Claude Code’s lewensiklus uitgevoer word. Hulle ontvang gestruktureerde JSON-invoer via stdin en beheer werkstrome deur uitgangskodes of HTTP-antwoorde.
Die outomatisering gaan dieper as wat die meeste gidse voorstel. Hooks kan hulpmiddel-uitvoering volledig blokkeer, bykomende konteks in Claude’s redenering inspuit, eksterne dienste aktiveer, en validasiereëls afdwing wat Claude moet respekteer.
Drie kern hook-tipes bestaan:
- Opdrag-hooks: Shell-skrifte wat deur stdout, stderr, en uitgangskodes kommunikeer
- HTTP-hooks: Afgeleë eindpunte wat POST-versoeke ontvang en JSON-antwoorde terugstuur
- Prompt-hooks: Dinamiese instruksies wat op spesifieke gebeurtenisse in Claude’s konteks ingespuit word
Elke tipe dien verskillende outomatiseringpatrone. Opdrag-hooks hanteer plaaslike validasie en formatering. HTTP-hooks integreer met eksterne dienste en databasisse. Prompt-hooks wysig Claude’s gedrag sonder eksterne prosesse.
Hook Lewensiklus en Gebeurtenis Stelsel
Die amptelike dokumentasie definieer veelvuldige hook-gebeurtenisse (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, en ander) wat tydens Claude Code’s uitvoeringsvloei afgevuur word. Om te verstaan wanneer elke gebeurtenis afgevuur word, bepaal watter outomatisering moontlik word.
| Gebeurtenis | Wanneer dit afgevuur word | Kan blokkeer |
|---|---|---|
| SessionStart | Wanneer 'n sessie begin of hervat word | Nee |
| UserPromptSubmit | Wanneer jy 'n prompt indien, voordat Claude dit verwerk | Ja |
| PreToolUse | Voordat 'n hulpmiddel-oproep uitgevoer word | Ja |
| PermissionRequest | Wanneer 'n toestemmingsdialoog verskyn | Ja |
| PostToolUse | Nadat 'n hulpmiddel-oproep suksesvol was | Nee |
| PostToolUseFailure | Nadat 'n hulpmiddel-oproep misluk het | Nee |
| Notification | Wanneer Claude Code 'n kennisgewing stuur | Nee |
| SubmitMessage | Wanneer Claude 'n boodskap aan die gebruiker indien | Nee |
| ContextCompaction | Wanneer die konteksvenster grense nader | Nee |
Die blokkeer-vermoë is die belangrikste. PreToolUse hooks kan gevaarlike operasies voorkom voordat dit uitgevoer word. Uitgangskode 1 blokkeer die aksie. Uitgangskode 0 laat dit toe. Uitgangskode 2 laat Claude oorweeg.
Maar wag. PostToolUse hooks kan nie aksies ongedaan maak nie, aangesien die hulpmiddel reeds uitgevoer is. Hierdie beperking vorm hoe validasie logika gestruktureer word. Kritieke kontroles behoort in PreToolUse te wees. Opruiming en formatering behoort in PostToolUse te wees.
Blaai KI-Hulpmiddel Perks Tydens Opstel van Claude Code
As jy met Claude Code hooks werk, kies jy dalk ook ander KI-hulpmiddels rondom jou werkstroom. Kry KI Perks versamel opstartkrediete en sagteware-afslag vir KI- en wolk-hulpmiddels op een plek. Die platform sluit 200+ aanbiedinge in, met perk-voorwaardes en eis-leiding vir elkeen.
Op Soek Na Claude Of Ander KI-Hulpmiddel Perks?
Kyk na Kry KI Perks om:
- blaai deur Claude en ander KI-hulpmiddel aanbiedinge
- vergelyk perk-voorwaardes voordat jy aansoek doen
- vind opstart-afslag oor jou hulpmiddel-stapel
👉 Besoek Kry KI Perks om huidige KI-sagteware-perks te verken.
Konfigurasie en Lêer Struktuur
Hooks word gedefinieer in die .claude/settings.json lêer binne 'n projek. Die konfigurasie-skema ondersteun globale hooks en hulpmiddel-spesifieke bypassers wat filtreer wanneer hooks uitgevoer word.
Basiese opdrag hook-struktuur:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Die ${file} veranderlike brei uit na die werklike lêerpad van die hulpmiddel-invoer. Volgens die amptelike dokumentasie, ondersteun hooks hierdie veranderlike uitbreidings in opdrag- en args-velde.
Hook Plek Hiërargie
Claude Code kontroleer veelvuldige plekke vir hook-definisies, met 'n duidelike prioriteitsorde:
- Projek-vlak: .claude/settings.json in die huidige werkruimte
- Gebruiker-vlak: ~/.claude/settings.json vir alle sessies
- Plugin-verskaf: Hooks gebundel met geïnstalleerde plugins
Projek hooks vervang gebruiker hooks vir dieselfde gebeurtenis. Dit laat projek-spesifieke formateringsreëls toe terwyl globale kennisgewing-hanterders behou word.
Bypass Patrone vir Selektiewe Uitvoering
Die bypass-stelsel filtreer hooks na spesifieke hulpmiddels of toestande. Sonder bypassers, vuur hooks vir elke voorkoms van hul gebeurtenis.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Die pathPattern-veld aanvaar glob-sintaksis. Die toolName-veld pas by Claude’s ingeboude hulpmiddels soos edit_file, execute_command, read_file, en create_directory.
Gemeenskapsbesprekings onthul dat bypass-kombinasies met AND-logika werk. Alle gespesifiseerde bypassers moet pas vir die hook om uitgevoer te word.
Opdrag Hooks: Shell-skrip Integrasie
Opdrag hooks voer shell-opdragte of skrifte uit met gestruktureerde JSON-invoer. Hulle verteenwoordig die mees algemene hook-tipe vir plaaslike outomatisering.
Die amptelike dokumentasie spesifiseer dat opdrag hooks JSON via stdin ontvang met hierdie struktuur:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skrifte pars hierdie invoer om besluite te neem. 'n Python-validasie hook sal dalk so lyk:#!/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) |
Uitgangskode 0 laat die operasie toe. Uitgangskode 1 blokkeer dit en wys die stderr boodskap aan Claude. Uitgangskode 2 aktiveer spesiale gedrag afhangende van die gebeurtenis.
Uitgangskode 2 Gedrag
Volgens die amptelike hooks-verwysingsdokumentasie, het uitgangskode 2 gebeurtenis-spesifieke betekenis (PreToolUse: blokkeer en vra vir heroorweging; UserPromptSubmit: verskaf konteks sonder om te blokkeer; PermissionRequest: blokkeer toestemming):
- PreToolUse: Blokkeer die hulpmiddel en vra Claude om te heroorweeg met die stderr boodskap as konteks
- UserPromptSubmit: Verskaf die stderr-uitvoer as bykomende konteks sonder om te blokkeer
- PermissionRequest: Blokkeer die toestemmingsverlening
Dit skep 'n middeweg tussen harde blokkering en toelaat. Claude ontvang terugvoer oor waarom die aksie problematies mag wees en kan sy benadering aanpas.
Asinchrone Opdrag Hooks
Die async: true vlag voer hooks in die agtergrond uit sonder om Claude’s werkstroom te blokkeer. Dit maak saak vir stadige operasies soos ontplooiingskennisgewings of metriese versameling.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Wanneer 'n async hook afgevuur word, begin Claude Code die proses en gaan onmiddellik voort. Die timeout-veld stel die maksimum uitvoeringstyd in sekondes. Indien nie gespesifiseer nie, gebruik async hooks 'n 10-minute standaard tyds limiet.
Regte praat: async hooks kan nie operasies blokkeer nie, aangesien hulle uitvoer nadat Claude voortgaan. Hulle werk vir logging, kennisgewings, en opruiming—nie validasie nie.
HTTP Hooks: Eksterne Diens Integrasie
HTTP hooks pos JSON-payloads na afgeleë eindpunte en pars antwoorde vir besluitbeheer. Hulle maak integrasie met validasie-dienste, databasisse, en derdeparty-hulpmiddels moontlik.
Basiese HTTP hook konfigurasie:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Die payload-struktuur pas by die opdrag hook-invoer, maar kom aan as 'n HTTP POST-liggaam. Die antwoord bepaal Claude’s volgende aksie.
HTTP Antwoord Hantering
Volgens die amptelike dokumentasie, interpreteer HTTP hooks antwoorde gebaseer op statuskode en liggaam-inhoud:
| Status Kode | Effek | Boodskap Bron |
|---|---|---|
| 200 | Laat operasie toe | Antwoordliggaam (opsioneel) |
| 400 | Blokkeer operasie | Antwoordliggaam gewys aan Claude |
| 500 | Hook-fout, laat operasie toe | Gelog maar nie aan Claude gewys nie |
| Ander | Laat operasie toe | Hook-mislukking blokkeer nie die werkstroom nie |
Die antwoordliggaam kan 'n boodskap-veld insluit wat Claude as konteks sien. Dit stel validasie-dienste in staat om te verduidelik waarom 'n operasie geblokkeer is.
Omgewingsveranderlike Interpolasie
HTTP hooks ondersteun ${VAR} sintaksis in url, headers, en ander string-velde. Veranderlikes brei uit vanaf die omgewing waar Claude Code uitgevoer word.
Volgens die amptelike MCP-dokumentasie, sluit omgewingsveranderlike uitbreiding 'n standaard terugval-sintaksis in: ${VAR:-default} brei uit na VAR indien dit gestel is, andersins gebruik dit die standaardwaarde.
Veiligheidsbeperking: Volgens GitHub-uitgawe #28044, kan HTTP hooks slegs toegang verkry tot omgewingsveranderlikes wat eksplisiet gelys is in die allowedEnvVars konfigurasie-veld. Dit voorkom onbedoelde toegangsherkenning blootstelling.
Prompt Hooks: Konteks Inspuiting
Prompt hooks spuit dinamiese instruksies in Claude’s konteks op spesifieke gebeurtenisse. Hulle wysig gedrag sonder eksterne prosesse of API-oproepe.
| { “event”: “SessionStart”, “prompt”: “Jy werk aan 'n TypeScript-projek. Gebruik altyd streng null-kontroles en verkies async/await bo promises.” } |
Die ingespuite teks word deel van Claude’s stelselinstruksies vir daardie sessie. Prompt hooks kan ook sjabloonveranderlikes gebruik wat uitbrei op grond van gebeurtenisdata.
Dinamiese Prompt Generering
Volgens die amptelike dokumentasie, ondersteun prompt hooks opdrag-velde wat dinamiese prompts genereer:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Die opdrag ontvang die standaard JSON-invoer via stdin en voer die prompt-teks uit na stdout. Dit maak konteks-bewuste instruksie-generering moontlik gebaseer op projekstatus.
Agent-gebaseerde Hooks
Agent hooks spesifiseer 'n sub-agent wat die gebeurtenis hanteer in plaas van direkte prompt-inspuiting. Die sub-agent ontvang konteks oor die gebeurtenis en kan meer-stap redenering uitvoer.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “'n Hulpmiddel-oproep het misluk. Analiseer die fout en stel oplossings voor.” } |
Die genomde sub-agent moet in die projekkonfigurasie gedefinieer word. Agent hooks maak komplekse besluitlogika moontlik wat eenvoudige prompt-inspuiting nie kan bied nie.
Praktiese Hook Patrone
Gemeenskapsbesprekings en amptelike voorbeelde onthul spesifieke outomatiseringpatrone wat betroubaar in produksie werk.
Auto-Formateer Kode Na Wysigings
Die mees algemene patroon formateer kode outomaties nadat Claude lêers wysig:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Die ${toolInput.path} veranderlike brei uit na die gewysigde lêerpad. PostToolUse verseker dat formatering gebeur na suksesvolle wysigings, maar blokkeer nie Claude’s werkstroom nie.
Blokkeer Beskermde Lêer Wysigings
PreToolUse hooks dwing lêerbeskermingsreëls af:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Die skrip valideer die teikenpad teen beskermde patrone en eindig met kode 1 om verbode wysigings te blokkeer.
Kry Kennisgewing Wanneer Claude Invoer Benodig
Volgens die amptelike werkstroomgids, kan Notification hooks rekenaarwaarskuwings aktiveer of boodskappe na eksterne dienste stuur:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Dit vuur elke keer af wanneer Claude Code 'n kennisgewing stuur, insluitend wanneer gewag word vir gebruikersinvoer of na taak voltooiing.
Her-inspuit Konteks Na Kompaksie
ContextCompaction hooks herstel belangrike konteks wanneer die gespreksvenster vol raak:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Die opdrag-uitvoer word terug ingespuit in Claude’s konteks nadat kompaksi ouer boodskappe verwyder het. Dit voorkom verlies van kritieke projek-spesifieke instruksies.
Oudit Konfigurasie Wysigings
Houd rekord van wanneer Claude konfigurasie lêers wysig:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Async uitvoering voorkom dat Claude geblokkeer word terwyl git-operasies voltooi word. Dit skep 'n ouditspoor van konfigurasie-wysigings sonder handmatige staging.
JSON Uitvoer en Besluit Beheer
Opdrag hooks kan gestruktureerde JSON uitvoer om gedetailleerde terugvoer bo eenvoudige uitgangskodes te verskaf. Volgens die amptelike verwysing, maak JSON-uitvoer multi-veld antwoorde moontlik wat Claude vir besluitneming interpreteer.
| { “allowed”: false, “message”: “Hierdie lêer is beskerm deur spanbeleid”, “suggestion”: “Skep 'n nuwe lêer in plaas daarvan in src/features/” } |
Die allowed-veld beheer of die operasie voortgaan. Die boodskap verskyn aan Claude as konteks. Die suggestion-veld bied alternatiewe benaderings.
Vir hooks om JSON uit te voer, moet hulle:
- Geldige JSON na stdout skryf
- Met kode 0 (vir toegelaat) of 1 (vir geblokkeer) eindig
- Ten minste die allowed booleaanse veld insluit
Claude Code pars die JSON en gebruik dit om die terugvoerlus te verbeter. Uitgangskodes bepaal steeds die primêre besluit, maar JSON bied ryker konteks.
Hook Invoer Velde Verwysing
Alle hooks ontvang 'n JSON-objek via stdin met algemene velde plus gebeurtenis-spesifieke data. Om die volledige skema te verstaan, maak meer gesofistikeerde hook-logika moontlik.
Algemene Invoer Velde
Elke hook ontvang hierdie basis velde:
- event: Die hook-gebeurtenis naam (bv. “PreToolUse”)
- sessionId: Unieke identifiseerder vir die huidige Claude sessie
- turnId: Identifiseerder vir die huidige gespreksdraai
- timestamp: ISO 8601 tydstempel toe die gebeurtenis afgevuur het
Hulpmiddel Gebeurtenis Velde
PreToolUse, PostToolUse, en PostToolUseFailure gebeurtenisse sluit in:
- toolName: Naam van die hulpmiddel wat ingeroep word (edit_file, execute_command, ens.)
- toolInput: Voorwerp wat die hulpmiddel se invoer parameters bevat
- toolResponse: Hulpmiddel uitvoer data (slegs PostToolUse)
- error: Foutbesonderhede insluitend boodskap en kode (slegs PostToolUseFailure)
Die toolInput-struktuur wissel volgens hulpmiddel. Vir edit_file bevat dit pad en inhoud. Vir execute_command bevat dit opdrag en args.
Toestemming Gebeurtenis Velde
PermissionRequest gebeurtenisse sluit in:
- permissionType: Tipe toestemming wat versoek is (file_write, command_execute, ens.)
- requestedAction: Spesifieke aksie wat toestemming vereis
- resourcePath: Lêerpad of hulpbron identifiseerder wat betrokke is
MCP Hulpmiddel Hooks
Volgens die amptelike hooks verwysing, kan hooks pas by Model Context Protocol (MCP) hulpmiddels met die mcpTool bypasser-veld. Dit maak hook-uitvoering moontlik wanneer Claude eksterne hulpmiddels gebruik wat deur MCP-bedieners verskaf word.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Die mcpTool-waarde pas by die hulpmiddelnaam in die formaat bediener-naam/hulpmiddel-naam. Dit laat validasie logika toe vir databasis navrae, API-oproepe, of ander eksterne operasies.
GitHub-funksieversoeke dui groeiende belangstelling in dieper MCP-integrasie aan, insluitend hooks wat MCP-bediener kennisgewings kan inspekteer en op eksterne gebeurtenisse kan reageer.
Veiligheids Oorwegings
Hooks word uitgevoer met dieselfde toestemmings as Claude Code self. Dit skep veiligheidsimplikasies vir multi-gebruiker omgewings en gedeelde konfigurasies.
Opdrag Uitvoering Sandbox
Volgens GitHub-uitgawe #28044, word HTTP hooks deur 'n sandbox-prokser gelei wat netwerktoegang beperk en omgewingsveranderlikes filter. Opdrag hooks het geen sulke beperkings nie—hulle voer uit met volle shell-toegang.
Die dokumentasie beveel hierdie praktyke aan:
- Stoor nooit toegangsherkennings in hook-opdragte nie
- Gebruik omgewingsveranderlikes vir sensitiewe data
- Valideer alle invoer van ${…} uitbreidings
- Implementeer tyds limiet vir eksterne dienste
- Gebruik async hooks vir nie-kritiese operasies om te verhoed dat op mislukkings gewag word
Hook Uitvoering Isolering
Gebruiker-vlak hooks in ~/.claude/settings.json is van toepassing op alle projekte. Dit skep risiko's wanneer oor verskillende vertrouensgrense gewerk word. Projek-vlak hooks vervang gebruiker hooks, maar kan dit nie heeltemal afskakel nie.
Die /hooks-menu in Claude Code wys alle aktiewe hooks vir die huidige sessie. Om hierdie lys te hersien voordat jy aan sensitiewe projekte werk, help om potensiële veiligheidskwessies te identifiseer.
Debugging en Probleemoplossing
Hook-mislukkings verskyn nie altyd duidelik in Claude’s gesprek nie. Die amptelike dokumentasie bied verskeie debugging benaderings.
Hook Uitvoering Logs
Claude Code log hook-uitvoering na die sessie-debug-uitvoer. Volgens die probleemoplossingsgids, onthul die aktivering van debug-logging:
- Watter hooks vir elke gebeurtenis gepas het
- Die JSON-invoer wat na elke hook gestuur is
- Stdout en stderr uitvoer van hook-prosesse
- Uitgangskodes en uitvoeringstyd
- HTTP-antwoordkodes en liggame vir HTTP hooks
Aktiveer debug-logging deur CLAUDE_DEBUG=1 in die omgewing te stel voordat Claude Code begin word.
Onafhanklik Hooks Toets
Opdrag hooks kan buite Claude Code getoets word deur handmatig JSON-invoer te konstrueer:
| echo ‘{“event”:“PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Dit valideer hook-logika sonder om werklike Claude-operasies te aktiveer. Die uitgangskode en stdout/stderr uitvoer moet ooreenstem met verwagte gedrag.
Algemene Hook Mislukkings
Gemeenskapsbesprekings identifiseer hierdie gereelde probleme:
- Tydsbegrensing foute: Standaard 10-minuut tydsbegrensing te kort vir stadige operasies—verhoog met timeout-veld
- Pad uitbreiding mislukkings: Veranderlikes soos ${file} ongedefinieerd vir gebeurtenisse wat nie lêer konteks insluit nie
- Toestemmingsfoute: Hook-skrifte ontbreek uitvoer toestemmings—voer chmod +x script.sh uit
- JSON pars foute: Wanvormige JSON-uitvoer van hooks—valideer met jq voor terugkeer
- Omgewingsveranderlike ontoeganklikheid: Veranderlikes nie na hook-proses oorgedra nie—kontroleer Claude Code’s omgewing
Hook Prestasie Implikasies
Sinkrone hooks blokkeer Claude’s werkstroom tot voltooiing. Die standaard 10-minuut tydsbegrensing voorkom onbeperkte vriespunte, maar selfs kort vertragings akkumuleer oor veelvuldige operasies.
Praktisyns rapporteer dat eenvoudige validasie hooks geringe prestasie-impak het. Lêer formatering hooks veroorsaak merkbare maar aanvaarbare prestasie-impak. Eksterne API oproepe kan werkstroom wrywing skep. Swaar berekeningsoperasies baat by async uitvoer.
Hook Groepering
Veelvuldige hooks kan by dieselfde gebeurtenis pas. Volgens die verwysingsdokumentasie, word hooks opeenvolgend uitgevoer in definisie-orde. Indien enige hook die operasie blokkeer, word oorblywende hooks nie uitgevoer nie.
Dit is belangrik vir prestasie. Vyf sinkrone hooks teen 200ms elk voeg een sekonde per gebeurtenis by. Die kombinasie van verwante validasies in 'n enkele hook verminder oorhoofse koste.
Gevorderde Patrone
Buiten basiese outomatisering, maak hooks gesofistikeerde werkstroom-aanpassing moontlik.
Toestandgebonde Hook Kettings
Hooks kan toestand handhaaf tussen uitvoerings deur lêers of databasisse te gebruik. 'n PostToolUse hook kan suksesvolle operasies aanteken wat 'n PreToolUse hook later valideer:
| #!/bin/bash # Teken suksesvolle wysigings aan echo “${toolInput.path}” >> .claude/edit-history.txt |
'n Komplementêre PreToolUse hook kan hierdie geskiedenis kontroleer om herhalende operasies te voorkom of ordeningsbeperkings af te dwing.
Voorwaardelike Hook Aktivering
Omgewingsveranderlikes beheer hook-gedrag by uitvoer tyd. Die instel van CLAUDE_SKIP_HOOKS=1 skakel hooks uit vir noodsituasies.
Hooks self kan omgewingsvlae kontroleer:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Pas streng validasie toe exit 1 fi exit 0 |
Dit maak ontwikkeling modus teenoor produksie modus gedrag moontlik sonder konfigurasie wysigings.
Veelvlakkige Validasi
PreToolUse hooks kan veelvlakkige validasi implementeer waar uitgangskode 2 Claude toelaat om met waarskuwings voort te gaan:
- Harde mislukkings (uitgang 1): Blokkeer gevaarlike operasies
- Sagte waarskuwings (uitgang 2): Waarsku Claude om te heroorweeg
- Slaag met konteks (uitgang 0 + JSON): Verskaf bykomende inligting
Dit skep 'n validasie spektrum wat meer genuanseerd is as binêre toelaat/ontken.
Integrasie met CI/CD
Volgens die amptelike platform-integrasie dokumentasie, voer Claude Code uit in CI/CD omgewings vir geoutomatiseerde kodereviews en foutbepaling. Hooks brei hierdie outomatisering uit.
GitHub Actions workflows kan hooks definieer wat spanbeleide afdwing tydens geoutomatiseerde sessies:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Die STRICT_MODE vlag aktiveer voorwaardelike validasie logika in hook-skrifte. Dit verseker dat geoutomatiseerde sessies meer rigiede reëls volg as interaktiewe ontwikkeling.
Ouditspoor Generering
PostToolUse hooks in CI-omgewings skep gedetailleerde ouditlogs van alle Claude-operasies:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Agtergrond logging beïnvloed nie prestasie nie, maar bied 'n volledige operasionele geskiedenis vir nakoming en debugging.
Die /hooks Menu
Claude Code bied 'n /hooks opdrag wat alle aktiewe hooks vir die huidige sessie vertoon. Volgens die amptelike dokumentasie, wys hierdie menu:
- Hook gebeurtenis tipe
- Bypass patrone
- Opdrag of URL eindpunt
- Of die hook async loop
- Konfigurasie bron (projek, gebruiker, of plugin)
Om 'n hook te kies, wys sy volledige konfigurasie en laat tydelike afskakeling vir die huidige sessie toe.
Skakel Af Of Verwyder Hooks
Hooks kan afgeskakel word sonder om konfigurasie te verwyder deur "enabled": false by die hook-definisie te voeg. Dit bewaar die konfigurasie terwyl uitvoering voorkom word.
Om 'n hook permanent te verwyder, vee sy inskrywing uit die toepaslike settings.json lêer. Veranderinge word effektief op die volgende sessie herbegin of wanneer /reload uitgevoer word.
Hooks in Vaardighede en Agente
Volgens die amptelike dokumentasie, is hooks gedefinieer binne vaardigheid of subagent konfigurasies van toepassing slegs wanneer daardie vaardigheid of agent uitgevoer word. Dit maak gespesialiseerde outomatisering vir spesifieke werkstrome moontlik.
'n Debugging subagent kan hooks insluit wat alle hulpmiddel-oproepe log:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Hierdie hooks vuur slegs tydens debugger agent sessies, nie tydens normale Claude Code operasies nie.
Verwysings Skripte per Pad
Hook-opdragte ondersteun beide relatiewe en absolute paaie. Relatiewe paaie word opgelos vanaf die projekwortel waar Claude Code uitgevoer word.
Beste praktyke uit gemeenskapsbesprekings:
- Stoor hook-skrifte in die .claude/hooks/ gids
- Gebruik beskrywende name: validate-typescript.sh nie hook1.sh nie
- Maak skrifte uitvoerbaar: chmod +x .claude/hooks/*.sh
- Sluit shebang lyn in: #!/usr/bin/env bash of #!/usr/bin/env python3
- Voeg fout-hantering by met set -e in bash skrifte
Toekomstige Hook Vermoëns
GitHub-funksieversoeke onthul beplande en versoekte hook-verbeterings:
- Inline skrip hooks: Definieer hook-logika direk in settings.json sonder eksterne lêers
- MCP hulpmiddel integrasie: Roep MCP-bediener hulpmiddels van hooks af in plaas van shell-opdragte
- Multi-agent samewerking: Hooks wat koördineer tussen Claude instansies op verskillende masjiene
- Verbeterde tipes: TypeScript tipe definisies vir hook-invoer/uitvoer skemas
Volgens GitHub-uitgawe #4274, mik die versoek vir geïntegreerde hook-tipes (MCP-hulpmiddel, inline skrip, API-oproep) daarna om konfigurasie te vereenvoudig en ontwikkelaarservaring te verbeter.
Gereelde Vrae
Kan hooks verhoed dat Claude gevaarlike opdragte uitvoer?
Ja. PreToolUse hooks kan enige hulpmiddel-uitvoering blokkeer deur met kode 1 te eindig. Dit sluit lêer wysigings, opdrag uitvoer, en MCP hulpmiddel oproepe in. Die hook ontvang die volledige hulpmiddel-invoer en kan teen enige kriteria valideer voordat die operasie toegelaat word.
Hoe debug ek 'n hook wat nie werk nie?
Aktiveer debug-logging met CLAUDE_DEBUG=1 voordat Claude Code begin word. Kyk na die sessielogs vir hook-uitvoerbesonderhede insluitend watter hooks gepas het, die JSON-invoer gestuur, stdout/stderr uitvoer, en uitgangskodes. Toets hooks onafhanklik deur monster JSON na die hook-skrip te pipel.
Werk hooks met alle Claude Code platforms?
Hooks werk in die CLI, desktop app, en VS Code uitbreiding. Volgens die amptelike dokumentasie, voer hooks uit oral waar Claude Code loop met toegang tot die lêerstelsel. Blaaier-gebaseerde Claude en mobiele programme ondersteun nie hooks nie as gevolg van sandboxing beperkings.
Kan hooks Claude’s antwoorde of gedrag wysig?
Prompt hooks spuit instruksies wat Claude’s gedrag beïnvloed. Agent hooks delegeer gebeurtenis-hantering na gespesialiseerde subagente. Hooks kan egter nie direk Claude’s gegenereerde teks of redeneringsproses wysig nie—hulle werk deur konteks te verskaf en operasies te blokkeer.
Wat is die verskil tussen async en sync hooks?
Sinkrone hooks blokkeer Claude’s werkstroom tot voltooiing of tyds limiet. Asinchrone hooks loop in die agtergrond sonder om te blokkeer. Sync hooks kan operasies voorkom deur uitgangskodes. Async hooks kan nie blokkeer nie, aangesien Claude voortgaan voordat die hook voltooi is. Gebruik async vir logging en kennisgewings, sync vir validasi.
Hoe deel ek hooks oor 'n span?
Lêer die .claude/settings.json lêer in weergawebeheer in. Projek-vlak hooks is van toepassing op alle spanlede wat die repo kloon. Vir organisasie-wye beleide, kan spanne 'n gedeelde gebruiker-vlak instellingslêer onderhou wat lede na ~/.claude/settings.json kopieer.
Kan HTTP hooks interne API's agter brandmure oproep?
Ja, indien Claude Code in 'n omgewing met netwerktoegang tot daardie API's loop. HTTP hooks maak standaard POST-versoeke vanaf die masjien wat Claude Code laat loop. Korporatiewe brandmure en VPN's pas normaal toe. Die sandbox-prokser wat in die dokumentasie genoem word, beheer omgewingsveranderlike blootstelling, nie netwerkroetering nie.
Verhoog hooks Claude Code’s token gebruik?
Prompt hooks spuit teks in Claude’s konteks, wat tokens verbruik. Opdrag en HTTP hooks beïnvloed nie token gebruik direk nie, maar hul uitvoer (foutboodskappe, voorstelle) word deel van die gesprekskonteks. Uitgangskode 2 met verklarende boodskappe voeg meer konteks by as uitgangskode 1 met eenvoudige blokkering.
Konklusie
Claude Code hooks omskep die KI-assistent van 'n kragtige hulpmiddel na 'n volledig geoutomatiseerde ontwikkelingsplatform. Die gebeurtenis-stelsel verskaf onderskep-punte deur Claude’s werkstroom—van sessie-initialisasie tot konteks-kompaksie.
Opdrag hooks hanteer plaaslike validasi en formatering. HTTP hooks integreer eksterne dienste en databasisse. Prompt hooks wysig gedrag deur konteks-inspuiting. Tesame maak hierdie outomatiseringpatrone moontlik wat spanbeleide afdwing, kodkwaliteit handhaaf, en integreer met bestaande ontwikkelingsinfrastruktuur.
Die bypass-stelsel filter hooks na spesifieke hulpmiddels en lêerpatrone. Uitgangskodes en JSON-uitvoer beheer besluitvloei. Async uitvoer voorkom blokkering op stadige operasies. Die volledige konfigurasie-skema ondersteun alles van eenvoudige auto-formatering tot komplekse veelvlakkige validasi.
Begin met basiese PostToolUse hooks vir kode-formatering. Voeg PreToolUse validasi by soos beleide opduik. Eksperimenteer met prompt hooks vir gedrags wysiging. Bou HTTP-integrasies vir span-wye afdwinging.
Kyk na die amptelike Claude Code dokumentasie vir die volledige hooks-verwysing en opgedateerde konfigurasie-skema namate nuwe vermoëns versend word.
