Snelle Samenvatting: Claude Code hooks zijn automatiseringsscripts die worden uitgevoerd op specifieke levenscycluspunten tijdens AI-coderingssessies, waardoor ontwikkelaars aangepaste commando's kunnen uitvoeren, acties kunnen valideren, code kunnen formatteren, meldingen kunnen verzenden en projectregels kunnen afdwingen. Deze hooks integreren met de workflow van Claude via gebeurtenissen zoals SessionStart, PreToolUse en PostToolUse, en ondersteunen op commando gebaseerde, HTTP-gebaseerde en op prompts gebaseerde uitvoeringspatronen met configureerbare time-outs en exit-codegedrag.
Het hook-systeem van Claude Code transformeert de AI-coderingsassistent van een behulpzaam hulpmiddel naar een volledig geautomatiseerde ontwikkelomgeving. De meeste ontwikkelaars realiseren zich niet de mate van controle die via hooks beschikbaar is.
Dit is echter het punt – hooks gaan niet alleen over het uitvoeren van scripts na bestandswijzigingen. Ze bieden interceptiepunten gedurende het gehele besluitvormingsproces van Claude. Voordat het een commando uitvoert. Nadat een toolaanroep mislukt. Wanneer het toestemming nodig heeft. Zelfs voordat gebruikersprompts worden verwerkt.
Deze gids behandelt alles wat de officiële documentatie biedt, plus praktische patronen die volgens communitydiscussies daadwerkelijk werken in productieomgevingen.
Wat Claude Code Hooks Eigenlijk Doen
Volgens de officiële Claude Code-documentatie zijn hooks door de gebruiker gedefinieerde shell-commando's, HTTP-eindpunten of promptinjecties die worden uitgevoerd op specifieke punten in de levenscyclus van Claude Code. Ze ontvangen gestructureerde JSON-invoer via stdin en besturen de workflow via exitcodes of HTTP-antwoorden.
De automatisering gaat dieper dan de meeste handleidingen suggereren. Hooks kunnen de uitvoering van tools volledig blokkeren, extra context injecteren in de redenering van Claude, externe services activeren en validatieregels afdwingen die Claude moet respecteren.
Er bestaan drie kernhooktypen:
- Commando-hooks: Shell-scripts die communiceren via stdout, stderr en exitcodes
- HTTP-hooks: Externe eindpunten die POST-verzoeken ontvangen en JSON-antwoorden retourneren
- Prompt-hooks: Dynamische instructies die op specifieke gebeurtenissen in de context van Claude worden geïnjecteerd
Elk type dient verschillende automatiseringspatronen. Commando-hooks behandelen lokale validatie en opmaak. HTTP-hooks integreren met externe services en databases. Prompt-hooks wijzigen het gedrag van Claude zonder externe processen.
Hook-levenscyclus en Gebeurtenissensysteem
De officiële documentatie definieert meerdere hookgebeurtenissen (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, en andere) die worden geactiveerd tijdens de uitvoeringsflow van Claude Code. Begrijpen wanneer elke gebeurtenis plaatsvindt, bepaalt welke automatisering mogelijk wordt.
| Gebeurtenis | Wanneer het wordt geactiveerd | Kan blokkeren |
|---|---|---|
| SessionStart | Wanneer een sessie begint of hervat | Nee |
| UserPromptSubmit | Wanneer u een prompt verzendt, voordat Claude deze verwerkt | Ja |
| PreToolUse | Voordat een toolaanroep wordt uitgevoerd | Ja |
| PermissionRequest | Wanneer een toestemmingsdialoog verschijnt | Ja |
| PostToolUse | Nadat een toolaanroep succesvol is | Nee |
| PostToolUseFailure | Nadat een toolaanroep is mislukt | Nee |
| Notification | Wanneer Claude Code een melding verzendt | Nee |
| SubmitMessage | Wanneer Claude een bericht naar de gebruiker verzendt | Nee |
| ContextCompaction | Wanneer het contextvenster de limieten nadert | Nee |
De blokkeerfunctie is het belangrijkst. PreToolUse-hooks kunnen gevaarlijke bewerkingen voorkomen voordat ze worden uitgevoerd. Exit code 1 blokkeert de actie. Exit code 0 staat deze toe. Exit code 2 vraagt Claude om opnieuw te overwegen.
Maar wacht. PostToolUse-hooks kunnen acties niet ongedaan maken, aangezien de tool al is uitgevoerd. Deze beperking bepaalt hoe validatielogica wordt gestructureerd. Kritieke controles behoren tot PreToolUse. Opschoning en opmaak behoren tot PostToolUse.
Blader door AI Tool Perks bij het Instellen van Claude Code
Als u met Claude Code hooks werkt, kiest u mogelijk ook andere AI-tools rond uw workflow. Get AI Perks verzamelt startup-credits en softwarekortingen voor AI- en cloudtools op één plek. Het platform bevat meer dan 200 aanbiedingen, met perkvoorwaarden en claimbegeleiding voor elk van hen.
Zoekt u naar Claude of Andere AI Tool Perks?
Bekijk Get AI Perks om:
- door aanbiedingen van Claude en andere AI-tools te bladeren
- perkvoorwaarden te vergelijken voordat u zich aanmeldt
- startup-kortingen te vinden voor uw toolstack
👉 Bezoek Get AI Perks om huidige AI-software-perks te ontdekken.
Configuratie en Bestandsstructuur
Hooks worden gedefinieerd in het bestand .claude/settings.json binnen een project. Het configuratieschema ondersteunt globale hooks en op tools specifieke matchers die filteren wanneer hooks worden uitgevoerd.
Basisstructuur voor commando-hooks:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
De variabele ${file} wordt uitgebreid tot het daadwerkelijke bestandspad van de toolinvoer. Volgens de officiële documentatie ondersteunen hooks dergelijke variabele-uitbreidingen in de velden command en args.
Hook Locatie Hiërarchie
Claude Code controleert meerdere locaties op hookdefinities, met een duidelijke prioriteitsvolgorde:
- Projectniveau: .claude/settings.json in de huidige werkruimte
- Gebruikersniveau: ~/.claude/settings.json voor alle sessies
- Door plug-ins geleverd: Hooks gebundeld met geïnstalleerde plug-ins
Project-hooks hebben voorrang op gebruikers-hooks voor dezelfde gebeurtenis. Dit maakt projectspecifieke opmaakregels mogelijk met behoud van globale meldingshandlers.
Matcher Patronen voor Selectieve Uitvoering
Het matchersysteem filtert hooks naar specifieke tools of voorwaarden. Zonder matchers worden hooks geactiveerd voor elke instantie van hun gebeurtenis.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Het veld pathPattern accepteert glob-syntaxis. Het veld toolName komt overeen met de ingebouwde tools van Claude zoals edit_file, execute_command, read_file en create_directory.
Communitydiscussies tonen aan dat combinaties van matchers werken met EN-logica. Alle gespecificeerde matchers moeten overeenkomen om de hook te activeren.
Commando-hooks: Shell-scriptintegratie
Commando-hooks voeren shell-commando's of scripts uit met gestructureerde JSON-invoer. Ze vertegenwoordigen het meest voorkomende hooktype voor lokale automatisering.
De officiële documentatie specificeert dat commando-hooks JSON via stdin ontvangen met deze structuur:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripts parsen deze invoer om beslissingen te nemen. Een Python-validatiehook kan er als volgt uitzien:#!/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(“Kan beschermde bestanden niet bewerken”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Exit code 0 staat de bewerking toe. Exit code 1 blokkeert deze en toont het stderr-bericht aan Claude. Exit code 2 activeert speciaal gedrag afhankelijk van de gebeurtenis.
Gedrag van Exit Code 2
Volgens de officiële documentatie van de hooks heeft exit code 2 een gebeurtenisspecifieke betekenis (PreToolUse: blokkeert en vraagt om heroverweging; UserPromptSubmit: biedt context zonder te blokkeren; PermissionRequest: blokkeert toestemming):
- PreToolUse: Blokkeert de tool en vraagt Claude om opnieuw te overwegen met het stderr-bericht als context
- UserPromptSubmit: Biedt de stderr-uitvoer als aanvullende context zonder te blokkeren
- PermissionRequest: Blokkeert de toestemmingsverlening
Dit creëert een middenweg tussen hard blokkeren en toestaan. Claude ontvangt feedback over waarom de actie problematisch kan zijn en kan zijn aanpak aanpassen.
Asynchrone Commando-hooks
Het vlag `async: true` voert hooks op de achtergrond uit zonder de workflow van Claude te blokkeren. Dit is belangrijk voor langzame bewerkingen zoals implementatiemeldingen of metriekverzameling.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Wanneer een asynchrone hook wordt geactiveerd, start Claude Code het proces en gaat onmiddellijk verder. Het veld timeout stelt de maximale uitvoeringstijd in seconden in. Indien niet gespecificeerd, gebruiken asynchrone hooks een standaard time-out van 10 minuten.
Eerlijk gezegd: asynchrone hooks kunnen geen bewerkingen blokkeren, aangezien ze worden uitgevoerd nadat Claude verdergaat. Ze werken voor logging, meldingen en opruiming – niet voor validatie.
HTTP-hooks: Integratie met Externe Services
HTTP-hooks posten JSON-payloads naar externe eindpunten en parsen antwoorden voor besturingsbeslissingen. Ze maken integratie met validatieservices, databases en externe tools mogelijk.
Basisconfiguratie voor HTTP-hooks:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
De payloadstructuur komt overeen met de invoer van commando-hooks, maar wordt ontvangen als POST-verzoekbody. Het antwoord bepaalt de volgende actie van Claude.
Verwerking van HTTP-antwoorden
Volgens de officiële documentatie interpreteren HTTP-hooks antwoorden op basis van de statuscode en de inhoud van de body:
| Statuscode | Effect | Bron Bericht |
|---|---|---|
| 200 | Bewerking toestaan | Antwoord body (optioneel) |
| 400 | Bewerking blokkeren | Antwoord body getoond aan Claude |
| 500 | Hook-fout, bewerking toestaan | Gelogd maar niet getoond aan Claude |
| Overig | Bewerking toestaan | Hook-fout blokkeert de workflow niet |
De antwoordbody kan een berichtveld bevatten dat Claude ziet als context. Dit stelt validatieservices in staat om uit te leggen waarom een bewerking werd geblokkeerd.
Interpolatie van Omgevingsvariabelen
HTTP-hooks ondersteunen ${VAR}-syntaxis in url, headers en andere tekenreekvelden. Variabelen worden uitgebreid vanuit de omgeving waarin Claude Code draait.
Volgens de officiële MCP-documentatie omvat de expansie van omgevingsvariabelen een standaard fallback-syntaxis: ${VAR:-default} wordt uitgebreid tot VAR als het is ingesteld, anders wordt de standaardwaarde gebruikt.
Beveiligingsbeperking: Volgens GitHub-issue #28044 kunnen HTTP-hooks alleen toegang krijgen tot omgevingsvariabelen die expliciet zijn vermeld in het configuratieveld `allowedEnvVars`. Dit voorkomt onbedoelde blootstelling van referenties.
Prompt-hooks: Context Injectie
Prompt-hooks injecteren dynamische instructies in de context van Claude op specifieke gebeurtenissen. Ze wijzigen het gedrag zonder externe processen of API-aanroepen.
| { “event”: “SessionStart”, “prompt”: “U werkt aan een TypeScript-project. Gebruik altijd strikte null-controles en geef de voorkeur aan async/await boven promises.” } |
De geïnjecteerde tekst wordt onderdeel van de systeeminstruncties van Claude voor die sessie. Prompt-hooks kunnen ook sjabloonvariabelen gebruiken die worden uitgebreid op basis van gebeurtenisgegevens.
Dynamische Prompt Generatie
Volgens de officiële documentatie ondersteunen prompt-hooks commandovelden die dynamische prompts genereren:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Het commando ontvangt de standaard JSON-invoer via stdin en voert de prompttekst uit naar stdout. Dit maakt contextbewuste instructiegeneratie mogelijk op basis van de projectstatus.
Agent-gebaseerde Hooks
Agent-hooks specificeren een subagent die de gebeurtenis afhandelt in plaats van directe promptinjectie. De subagent ontvangt context over de gebeurtenis en kan redeneringen in meerdere stappen uitvoeren.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Een toolaanroep is mislukt. Analyseer de fout en stel oplossingen voor.” } |
De benoemde subagent moet worden gedefinieerd in de projectconfiguratie. Agent-hooks maken complexe beslissingslogica mogelijk die eenvoudige promptinjectie niet kan bieden.
Praktische Hook Patronen
Communitydiscussies en officiële voorbeelden onthullen specifieke automatiseringspatronen die betrouwbaar werken in productie.
Code Automatisch Opmaak Na Wijzigingen
Het meest voorkomende patroon formatteert code automatisch nadat Claude bestanden heeft gewijzigd:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
De variabele ${toolInput.path} wordt uitgebreid naar het pad van het gewijzigde bestand. PostToolUse zorgt ervoor dat de opmaak gebeurt na succesvolle wijzigingen, maar blokkeert de workflow van Claude niet.
Wijzigingen in Beschermde Bestanden Blokkeren
PreToolUse-hooks dwingen regels voor bestandbescherming af:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Het script valideert het doelpad tegen beschermde patronen en sluit af met code 1 om verboden bewerkingen te blokkeren.
Notificatie Ontvangen Wanneer Claude Input Nodig Heeft
Volgens de officiële workflowgids kunnen Notification-hooks desktopwaarschuwingen activeren of berichten naar externe services verzenden:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Dit wordt geactiveerd telkens wanneer Claude Code een melding verzendt, inclusief wanneer er wordt gewacht op gebruikersinvoer of na voltooiing van een taak.
Context Opnieuw Injecteren Na Compaction
ContextCompaction-hooks herstellen belangrijke context wanneer het gespreksvenster vol raakt:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
De commando-uitvoer wordt terug geïnjecteerd in de context van Claude na compaction die oudere berichten verwijdert. Dit voorkomt verlies van kritieke projectspecifieke instructies.
Audit Configuratie Wijzigingen
Volg wanneer Claude configuratiebestanden wijzigt:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asynchrone uitvoering voorkomt het blokkeren van Claude terwijl git-bewerkingen worden voltooid. Dit creëert een audit trail van configuratiewijzigingen zonder handmatig staging.
JSON-uitvoer en Beslissingscontrole
Commando-hooks kunnen gestructureerde JSON uitvoeren om gedetailleerde feedback te geven die verder gaat dan eenvoudige exitcodes. Volgens de officiële referentie maakt JSON-uitvoer meerveldige antwoorden mogelijk die Claude interpreteert voor besluitvorming.
| { “allowed”: false, “message”: “Dit bestand is beschermd door teambeleid”, “suggestion”: “Maak een nieuw bestand aan in plaats daarvan in src/features/” } |
Het veld `allowed` bepaalt of de bewerking doorgaat. Het bericht wordt aan Claude getoond als context. Het veld `suggestion` biedt alternatieve benaderingen.
Opdat hooks JSON kunnen uitvoeren, moeten ze:
- Geldige JSON naar stdout schrijven
- Afsluiten met code 0 (voor toegestaan) of 1 (voor geblokkeerd)
- Ten minste het `allowed` booleaanse veld bevatten
Claude Code parset de JSON en gebruikt deze om de feedbacklus te verbeteren. Exitcodes bepalen nog steeds de primaire beslissing, maar JSON biedt rijkere context.
Referentie Hook Input Velden
Alle hooks ontvangen een JSON-object via stdin met gemeenschappelijke velden plus gebeurtenisspecifieke gegevens. Het begrijpen van het volledige schema maakt meer geavanceerde hooklogica mogelijk.
Gemeenschappelijke Input Velden
Elke hook ontvangt deze basisvelden:
- event: De naam van de hook-gebeurtenis (bijv. "PreToolUse")
- sessionId: Unieke identificatie voor de huidige Claude-sessie
- turnId: Identificatie voor de huidige conversatiebeurt
- timestamp: ISO 8601-tijdstempel wanneer de gebeurtenis werd geactiveerd
Tool Gebeurtenis Velden
PreToolUse, PostToolUse en PostToolUseFailure gebeurtenissen bevatten:
- toolName: Naam van de tool die wordt aangeroepen (edit_file, execute_command, etc.)
- toolInput: Object met de invoerparameters van de tool
- toolResponse: Tool uitvoergegevens (alleen PostToolUse)
- error: Foutdetails inclusief bericht en code (alleen PostToolUseFailure)
De toolInput-structuur varieert per tool. Voor edit_file bevat het pad en inhoud. Voor execute_command bevat het commando en argumenten.
Permission Gebeurtenis Velden
PermissionRequest-gebeurtenissen bevatten:
- permissionType: Type toestemming gevraagd (file_write, command_execute, etc.)
- requestedAction: Specifieke actie waarvoor toestemming is vereist
- resourcePath: Bestandspad of resource-identificatie beïnvloed
MCP Tool Hooks
Volgens de officiële hook-referentie kunnen hooks overeenkomen met Model Context Protocol (MCP) tools met het `mcpTool`-matcher-veld. Dit maakt hookuitvoering mogelijk wanneer Claude externe tools gebruikt die door MCP-servers worden geleverd.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
De `mcpTool`-waarde komt overeen met de toolnaam in het formaat `server-name/tool-name`. Dit maakt validatielogica mogelijk voor databasequeries, API-aanroepen of andere externe bewerkingen.
GitHub-functieverzoeken geven een groeiende interesse aan in diepere MCP-integratie, inclusief hooks die MCP-servermeldingen kunnen inspecteren en reageren op externe gebeurtenissen.
Veiligheidsoverwegingen
Hooks worden uitgevoerd met dezelfde rechten als Claude Code zelf. Dit creëert veiligheidsimplicaties voor omgevingen met meerdere gebruikers en gedeelde configuraties.
Sandbox voor Commando-uitvoering
Volgens GitHub-issue #28044 worden HTTP-hooks via een sandbox-proxy geleid die netwerktoegang beperkt en omgevingsvariabelen filtert. Commando-hooks hebben geen dergelijke beperkingen – ze draaien met volledige shelltoegang.
De documentatie raadt deze praktijken aan:
- Sla nooit referenties op in hook-commando's
- Gebruik omgevingsvariabelen voor gevoelige gegevens
- Valideer alle invoer van ${...}-uitbreidingen
- Implementeer time-outlimieten voor externe services
- Gebruik asynchrone hooks voor niet-kritieke bewerkingen om blokkades bij fouten te voorkomen
Isolatie van Hook-uitvoering
Hooks op gebruikersniveau in `~/.claude/settings.json` zijn van toepassing op alle projecten. Dit creëert risico's bij het werken met verschillende vertrouwensgrenzen. Projectniveau hooks hebben voorrang op gebruikers hooks, maar kunnen deze niet volledig uitschakelen.
Het menu /hooks in Claude Code toont alle actieve hooks voor de huidige sessie. Het controleren van deze lijst voordat u aan gevoelige projecten werkt, helpt potentiële beveiligingsrisico's te identificeren.
Debuggen en Probleemoplossing
Hook-fouten komen niet altijd duidelijk naar voren in het gesprek van Claude. De officiële documentatie biedt verschillende benaderingen voor debugging.
Hook Uitvoer Logboeken
Claude Code logt de uitvoering van hooks naar de sessie debug-uitvoer. Volgens de troubleshootinggids onthult het inschakelen van debug-logging:
- Welke hooks overeenkwamen voor elke gebeurtenis
- De JSON-invoer die naar elke hook is gestuurd
- Stdout en stderr uitvoer van hookprocessen
- Exitcodes en uitvoeringstijd
- HTTP-antwoordcodes en bodies voor HTTP-hooks
Schakel debug-logging in door `CLAUDE_DEBUG=1` in de omgeving in te stellen voordat u Claude Code start.
Hooks Onafhankelijk Testen
Commando-hooks kunnen buiten Claude Code worden getest door handmatig JSON-invoer te construeren:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Dit valideert de hooklogica zonder daadwerkelijke Claude-bewerkingen te activeren. De exitcode en stdout/stderr-uitvoer moeten overeenkomen met het verwachte gedrag.
Veelvoorkomende Hook Fouten
Communitydiscussies identificeren de volgende veelvoorkomende problemen:
- Time-outfouten: Standaard time-out van 10 minuten te kort voor trage bewerkingen – verhoog met het `timeout`-veld
- Fouten bij paduitbreiding: Variabelen zoals ${file} zijn niet gedefinieerd voor gebeurtenissen die geen bestandscontext bevatten
- Toestemmingsfouten: Hookscripts hebben geen uitvoeringsrechten – voer `chmod +x script.sh` uit
- JSON-parsefouten: Slecht gevormde JSON-uitvoer van hooks – valideer met `jq` voordat u terugkeert
- Onbeschikbaarheid van omgevingsvariabelen: Variabelen worden niet doorgegeven aan het hookproces – controleer de omgeving van Claude Code
Hook Prestatie-implicaties
Synchrone hooks blokkeren de workflow van Claude tot voltooiing. De standaard time-out van 10 minuten voorkomt oneindige vastlopers, maar zelfs korte vertragingen stapelen zich op bij meerdere bewerkingen.
Praktijkmensen melden dat eenvoudige validatiehooks een verwaarloosbare impact op de prestaties hebben. Bestandopmaakhooks veroorzaken een merkbare maar acceptabele prestatie-impact. Externe API-aanroepen kunnen wrijving in de workflow veroorzaken. Zware rekenoperaties profiteren van asynchrone uitvoering.
Hook Batching
Meerdere hooks kunnen overeenkomen met dezelfde gebeurtenis. Volgens de referentiedocumentatie worden hooks sequentieel uitgevoerd in de volgorde van definitie. Als een hook de bewerking blokkeert, worden de resterende hooks niet uitgevoerd.
Dit is belangrijk voor de prestaties. Vijf synchrone hooks van elk 200 ms voegen één seconde per gebeurtenis toe. Het combineren van gerelateerde validaties tot een enkele hook vermindert de overhead.
Geavanceerde Patronen
Naast basisautomatisering maken hooks geavanceerde workflowaanpassing mogelijk.
Stateful Hook Keten
Hooks kunnen staat behouden tussen uitvoeringen met behulp van bestanden of databases. Een PostToolUse-hook kan succesvolle bewerkingen vastleggen die een PreToolUse-hook later valideert:
| #!/bin/bash # Succesvolle wijzigingen vastleggen echo “${toolInput.path}” >> .claude/edit-history.txt |
Een bijbehorende PreToolUse-hook kan deze geschiedenis controleren om redundante bewerkingen te voorkomen of volgordebeperkingen af te dwingen.
Voorwaardelijke Hook Activering
Omgevingsvariabelen regelen het hookgedrag tijdens runtime. Het instellen van `CLAUDE_SKIP_HOOKS=1` schakelt hooks uit voor noodsituaties.
Hooks zelf kunnen omgevingsvlaggen controleren:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Strikte validatie toepassen exit 1 fi exit 0 |
Dit maakt gedrag in ontwikkelingsmodus versus productiemodus mogelijk zonder configuratiewijzigingen.
Meerfasen Validatie
PreToolUse-hooks kunnen meerfasen validatie implementeren waarbij exit code 2 Claude toestaat verder te gaan met waarschuwingen:
- Hard failures (exit 1): Gevaarlijke bewerkingen blokkeren
- Soft warnings (exit 2): Claude waarschuwen om opnieuw te overwegen
- Passeren met context (exit 0 + JSON): Extra informatie verstrekken
Dit creëert een validatiespectrum dat genuanceerder is dan een binaire toelaten/weigeren.
Integratie met CI/CD
Volgens de officiële documentatie voor platformintegratie draait Claude Code in CI/CD-omgevingen voor geautomatiseerde codebeoordeling en probleemoplossing. Hooks breiden deze automatisering uit.
GitHub Actions-workflows kunnen hooks definiëren die teambeleid afdwingen tijdens geautomatiseerde sessies:
| -- name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
De `STRICT_MODE`-vlag activeert conditionele validatielogica in hook-scripts. Dit zorgt ervoor dat geautomatiseerde sessies striktere regels volgen dan interactieve ontwikkeling.
Audit Trail Generatie
PostToolUse-hooks in CI-omgevingen creëren gedetailleerde auditlogs van alle Claude-bewerkingen:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Achtergrondlogging heeft geen invloed op de prestaties, maar biedt een volledige bewerkingsgeschiedenis voor naleving en debugging.
Het /hooks Menu
Claude Code biedt een /hooks-commando dat alle actieve hooks voor de huidige sessie weergeeft. Volgens de officiële documentatie toont dit menu:
- Hook gebeurtenistype
- Matcher patronen
- Commando of URL-eindpunt
- Of de hook asynchroon draait
- Configuratiebron (project, gebruiker of plug-in)
Het selecteren van een hook toont de volledige configuratie en maakt tijdelijke uitschakeling mogelijk voor de huidige sessie.
Hooks Uitschakelen of Verwijderen
Hooks kunnen worden uitgeschakeld zonder de configuratie te verwijderen door `"enabled": false` toe te voegen aan de hookdefinitie. Dit behoudt de configuratie en voorkomt uitvoering.
Om een hook permanent te verwijderen, verwijdert u de vermelding ervan uit het desbetreffende `settings.json`-bestand. Wijzigingen worden van kracht bij de volgende herstart van de sessie of bij het uitvoeren van `/reload`.
Hooks in Skills en Agents
Volgens de officiële documentatie zijn hooks die binnen skill- of subagentconfiguraties zijn gedefinieerd, alleen van toepassing wanneer die skill of agent wordt uitgevoerd. Dit maakt gespecialiseerde automatisering mogelijk voor specifieke workflows.
Een debugging subagent kan hooks bevatten die alle toolaanroepen loggen:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Deze hooks worden alleen geactiveerd tijdens debugger-agentessies, niet tijdens normale Claude Code-bewerkingen.
Scripts Refereren via Pad
Hook-commando's ondersteunen zowel relatieve als absolute paden. Relatieve paden worden opgelost vanaf de projectroot waar Claude Code draait.
Best practices uit communitydiscussies:
- Bewaar hookscripts in de map .claude/hooks/
- Gebruik beschrijvende namen: validate-typescript.sh in plaats van hook1.sh
- Maak scripts uitvoerbaar: chmod +x .claude/hooks/*.sh
- Voeg een shebang-regel toe: #!/usr/bin/env bash of #!/usr/bin/env python3
- Voeg foutafhandeling toe met set -e in bash-scripts
Toekomstige Hook Mogelijkheden
GitHub-functieverzoeken onthullen geplande en aangevraagde hookverbeteringen:
- Inline script hooks: Definieer hooklogica direct in settings.json zonder externe bestanden
- MCP tool integratie: Roep MCP-servertools aan vanuit hooks in plaats van shell-commando's
- Multi-agent samenwerking: Hooks die coördineren tussen Claude-instanties op verschillende machines
- Verbeterde typen: TypeScript-typedefinities voor hook input/output schema's
Volgens GitHub-issue #4274 richt het verzoek voor geïntegreerde hooktypen (MCP tool, inline script, API-aanroep) zich op het vereenvoudigen van de configuratie en het verbeteren van de ervaring van de ontwikkelaar.
Veelgestelde Vragen
Kunnen hooks voorkomen dat Claude gevaarlijke commando's uitvoert?
Ja. PreToolUse-hooks kunnen elke tooluitvoering blokkeren door af te sluiten met code 1. Dit omvat bestandswijzigingen, commando-uitvoering en MCP-toolaanroepen. De hook ontvangt de volledige toolinvoer en kan valideren tegen elke criteria voordat de bewerking wordt toegestaan.
Hoe debug ik een hook die niet werkt?
Schakel debug-logging in met `CLAUDE_DEBUG=1` voordat u Claude Code start. Controleer de sessielogs op details van de hookuitvoering, inclusief welke hooks overeenkwamen, de verzonden JSON-invoer, stdout/stderr-uitvoer en exitcodes. Test hooks onafhankelijk door voorbeeld-JSON naar het hookscript te sturen.
Werken hooks met alle Claude Code-platforms?
Hooks werken in de CLI, desktop-app en VS Code-extensie. Volgens de officiële documentatie worden hooks uitgevoerd waar Claude Code draait met toegang tot het bestandssysteem. Browser-gebaseerde Claude en mobiele apps ondersteunen geen hooks vanwege beperkingen in sandboxen.
Kunnen hooks Claude's reacties of gedrag wijzigen?
Prompt-hooks injecteren instructies die het gedrag van Claude beïnvloeden. Agent-hooks delegeren gebeurtenisafhandeling aan gespecialiseerde subagents. Hooks kunnen de gegenereerde tekst of het redeneringsproces van Claude echter niet rechtstreeks wijzigen – ze werken door context te bieden en bewerkingen te blokkeren.
Wat is het verschil tussen asynchrone en synchrone hooks?
Synchrone hooks blokkeren de workflow van Claude tot voltooiing of time-out. Asynchrone hooks worden op de achtergrond uitgevoerd zonder te blokkeren. Synchrone hooks kunnen bewerkingen voorkomen via exitcodes. Asynchrone hooks kunnen niet blokkeren, aangezien Claude verdergaat voordat de hook is voltooid. Gebruik async voor logging en meldingen, sync voor validatie.
Hoe deel ik hooks met een team?
Commit het bestand .claude/settings.json naar versiebeheer. Projectniveau hooks zijn van toepassing op alle teamleden die de repository clonen. Voor organisatiebrede beleidsregels kunnen teams een gedeeld gebruikersniveau instellingenbestand bijhouden dat leden naar ~/.claude/settings.json kopiëren.
Kunnen HTTP-hooks interne API's achter firewalls aanroepen?
Ja, als Claude Code draait in een omgeving met netwerktoegang tot die API's. HTTP-hooks maken standaard POST-verzoeken vanaf de machine die Claude Code uitvoert. Bedrijfsfirewalls en VPN's zijn normaal van toepassing. De sandbox-proxy die in de documentatie wordt vermeld, regelt de blootstelling van omgevingsvariabelen, niet de netwerkroutering.
Verhogen hooks het tokengebruik van Claude Code?
Prompt-hooks injecteren tekst in de context van Claude, wat tokens verbruikt. Commando- en HTTP-hooks hebben geen directe invloed op het tokengebruik, maar hun uitvoer (foutmeldingen, suggesties) wordt onderdeel van de gesprekscontext. Exit code 2 met verklarende berichten voegt meer context toe dan exit code 1 met eenvoudige blokkering.
Conclusie
Claude Code hooks transformeren de AI-assistent van een krachtig hulpmiddel naar een volledig geautomatiseerd ontwikkelplatform. Het gebeurtenissysteem biedt interceptiepunten gedurende de workflow van Claude – van sessie-initialisatie tot contextcompactie.
Commando-hooks behandelen lokale validatie en opmaak. HTTP-hooks integreren externe services en databases. Prompt-hooks wijzigen gedrag door contextinjectie. Samen maken deze automatiseringspatronen mogelijk die teambeleid afdwingen, codekwaliteit handhaven en integreren met bestaande ontwikkelingsinfrastructuur.
Het matchersysteem filtert hooks naar specifieke tools en bestandspatronen. Exitcodes en JSON-uitvoer regelen de besluitvorming. Asynchrone uitvoering voorkomt blokkades bij trage bewerkingen. Het complete configuratieschema ondersteunt alles, van eenvoudige automatische opmaak tot complexe meerfasenvalidatie.
Begin met eenvoudige PostToolUse-hooks voor codeopmaak. Voeg PreToolUse-validatie toe naarmate beleid zich ontwikkelt. Experimenteer met prompt-hooks voor gedragswijziging. Bouw HTTP-integraties voor teambrede handhaving.
Raadpleeg de officiële Claude Code-documentatie voor de volledige hook-referentie en het bijgewerkte configuratieschema naarmate nieuwe mogelijkheden worden uitgebracht.
