Claude Code hooks: zo doe je het, stap voor stap

Wat heb je nodig

Wat heb je nodig voor Claude Code hooks?

Hooks zijn onderdeel van Claude Code zelf, dus je hoeft niets extra af te nemen. Je hebt wel een paar kleine programma's nodig, omdat een hook gewoon een commando op je eigen computer is. Heb je Claude Code nog niet draaien, begin dan bij Claude Code installeren. Welk plan je nodig hebt, staat op de Claude-abonnementen.

jq installeren

Op macOS: brew install jq. Op Debian en Ubuntu: sudo apt-get install jq. Op Windows: winget install jqlang.jq. Open daarna een nieuwe terminal, zodat je systeem het nieuwe programma vindt.

Hoe het werkt

Hoe werkt een hook in Claude Code?

Een instructie in je CLAUDE.md is een verzoek: het model kan het vergeten. Een hook is een regel: Claude Code voert hem zelf uit op een vast moment, of het model daaraan denkt of niet. Elke hook bestaat uit drie delen. Het event is het moment, zoals vlak voor of na een tool. De matcher is het filter, bijvoorbeeld alleen de tools Edit en Write. De handler is wat er gebeurt, meestal een shellcommando. Claude Code kent op 28 oktober 2026 33 events; voor een beginner zijn er vier genoeg.

De vorm in settings.json: twee keer het woord hooks

Beginners raken hier vaak de weg kwijt. Bovenaan staat één object "hooks". Daarin zet je per event een lijst met groepen. Elke groep heeft een "matcher" en opnieuw een lijst "hooks" met de handlers. Zo ziet het geraamte eruit:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jouw commando" }
]
}
]
}
}

Heb je al hooks? Zet een nieuw event dan naast de bestaande in hetzelfde "hooks"-object. Een tweede "hooks"-blok bovenaan maakt je JSON ongeldig.

Waar je een hook neerzet

~/.claude/settings.json geldt voor al je projecten, alleen op jouw computer. Daar horen persoonlijke hooks, zoals een melding. .claude/settings.json in je projectmap commit je mee in git, zodat het hele team dezelfde hook krijgt. Daar horen afspraken over het project, zoals de formatter. .claude/settings.local.json is voor jouw uitzonderingen op dat project. Daarnaast kunnen hooks in een plugin, in een skill of in een subagent zitten.

Exitcodes: zo vertelt je script wat er moet gebeuren

Een hook krijgt de gegevens van het moment als JSON binnen, bijvoorbeeld het commando dat Claude wil draaien. Je script antwoordt met een exitcode. Exit 0 betekent: geen bezwaar, ga door. Exit 2 betekent: blokkeren, en wat je naar stderr schrijft krijgt Claude als uitleg. Elke andere code, ook exit 1, telt als een fout in de hook zelf: Claude Code toont een melding en gaat bij de meeste events gewoon door. Wie met exit 1 probeert te blokkeren, blokkeert dus niets.

Voorbeeld 1: melding

Je eerste Claude Code hook: een melding als Claude op je wacht

Je begint met een hook die niets kapot kan maken: een melding op je scherm zodra Claude op je wacht. Dan kun je ander werk doen terwijl Claude bezig is. Deze hook zet je in je persoonlijke instellingen, omdat niet elke collega meldingen wil.

De configuratie voor macOS

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code wacht op je\" with title \"Claude Code\"'"
}
]
}
]
}
}

Melding op Linux of Windows

Linux, als waarde van "command":
"notify-send 'Claude Code' 'Claude Code wacht op je'"

Windows, als waarde van "command" (opent een dialoogvenster, dat soms achter je terminal verschijnt):
"powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code wacht op je', 'Claude Code')\""

Op Linux heb je een meldingsdienst nodig; op een server via SSH werkt notify-send niet. Ontbreekt het programma, installeer dan libnotify-bin op Debian of Ubuntu.

Waarom de matcher leeg is

Een lege matcher pakt alle soorten meldingen. Wil je alleen een melding als Claude om toestemming vraagt, zet dan "permission_prompt" als matcher. Met "idle_prompt" krijg je alleen een melding als Claude ongeveer een minuut klaar is en jij nog niets hebt getypt. Je kunt ze combineren als "permission_prompt|idle_prompt".

Voorbeeld 2: formatter

Claude Code hook na elke bewerking: automatisch opmaken met Prettier

Je kunt in CLAUDE.md zetten dat Claude na elke wijziging Prettier moet draaien, maar dan hoop je dat hij het onthoudt. Met een PostToolUse-hook gebeurt het altijd, ook na een lange sessie. Prettier is een formatter: een programma dat code in een vaste opmaak zet. Deze hook hoort bij het project, dus je zet hem in de projectmap en commit hem mee.

De configuratie voor .claude/settings.json

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown"
}
]
}
]
}
}

Wat het commando doet

Claude Code geeft de hook JSON mee met onder meer tool_input.file_path, het bestand dat net bewerkt is. jq -r haalt dat pad eruit, en xargs geeft het door aan Prettier. De toevoeging --ignore-unknown zit niet in het officiële voorbeeld; wij zetten hem erbij zodat Prettier bestanden overslaat die hij niet kent, zoals een .txt of .env, in plaats van bij elke bewerking een foutmelding te geven.

Geen JavaScript-project?

Het patroon blijft hetzelfde; alleen het programma achter xargs verandert. Werk je in Python, gebruik dan de formatter die je team al heeft, zoals ruff of black. Let op: deze hook ziet alleen bewerkingen via Edit en Write. Wijzigt Claude een bestand via een shellcommando, dan gaat hij niet af. Wil je dat ook vangen, gebruik dan een FileChanged-hook of een Stop-hook die aan het eind van elke beurt de gewijzigde bestanden nakijkt.

Voorbeeld 3: blokkade

Claude Code hook die gevaarlijke commando's blokkeert

De derde hook houdt commando's tegen die je nooit per ongeluk wilt laten draaien, zoals alles weggooien met rm -rf of de geschiedenis op GitHub overschrijven met een force push. Een PreToolUse-hook draait vóór het commando, in elke permissiemodus. Ook als je Claude veel vrijheid geeft, gaat deze controle dus eerst.

Het script: .claude/hooks/blokkeer-gevaarlijk.sh

#!/bin/bash
# Blokkeert commando's die je niet per ongeluk wilt laten draaien.
INPUT=$(cat)
COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')

VERBODEN=("rm -rf" "git push --force" "git push -f" "git reset --hard" "drop table")

for patroon in "${VERBODEN[@]}"; do
if printf '%s' "$COMMAND" | grep -qiF -- "$patroon"; then
echo "Geblokkeerd door hook: '$patroon' is in dit project niet toegestaan. Stel een veiliger alternatief voor of vraag de gebruiker het zelf te doen." >&2
exit 2
fi
done

exit 0

De configuratie: PreToolUse naast PostToolUse

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/blokkeer-gevaarlijk.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown"
}
]
}
]
}
}

Waarom de melding in het script ertoe doet

Bij exit 2 leest Claude wat je naar stderr schrijft. Een melding als is niet toegestaan, stel een veiliger alternatief voor zorgt dat Claude een andere route zoekt, zoals één map gericht verwijderen, in plaats van het verboden commando in een andere vorm te proberen. De lijst met verboden woorden pas je aan op je project. grep -qiF zoekt de letterlijke tekst zonder op hoofdletters te letten, dus DROP TABLE wordt ook gevangen.

Een vangnet, geen beveiliging

Deze hook zoekt naar tekst. rm -fr in plaats van rm -rf, of hetzelfde commando in een script, glipt erdoor. Anthropic zegt dat ook over permissieregels: een regel als Bash(rm *) stopt de vorm die Claude meestal schrijft, maar is geen beveiligingsgrens. Zie de hook als vangnet tegen vergissingen. Wil je echt afschermen wat Claude op je schijf en het netwerk mag, gebruik dan de sandbox met /sandbox, en lees Claude Code en privacy.

Op Windows

Installeer Git for Windows, zodat Claude Code de Bash-tool en Git Bash gebruikt; dan werkt het script zoals het er staat. Zonder Git Bash gebruikt Claude Code de PowerShell-tool, en dan pakt de matcher Bash die commando's niet. Zet de matcher in dat geval op "Bash|PowerShell" en schrijf het script in PowerShell, met "shell": "powershell" in de hook.

Werkt het?

Werkt het? Zo test je je Claude Code hooks veilig

Een hook die werkt, zie je meestal niet. Daarom test je bewust, op een manier waarbij er niets misgaat als de hook toch niet vuurt. Daarna laat je Claude zelf je configuratie nalopen.

De controle: test de blokkade met een onschuldig commando

Vraag Claude niet om echt rm -rf te draaien; als de hook faalt, gebeurt het dan echt. Vraag in plaats daarvan: Voer dit commando uit: echo "test git reset --hard". Het script zoekt naar de tekst, dus het blokkeert ook deze echo. Je ziet het goed werken als Claude meldt dat het commando is geblokkeerd, met jouw tekst uit het script. Gaat de echo toch door, dan kan er niets kapot en weet je dat de hook niet vuurt. Druk op Ctrl+O voor de transcriptweergave: daar zie je bij een blokkade de melding, en bij een fout in de hook een regel als PreToolUse hook error.

De eerste prompt om te plakken

Lees ~/.claude/settings.json en .claude/settings.json in dit project.
1. Maak een tabel van elke hook: event, matcher, wat het commando doet.
2. Controleer of de JSON geldig is en of elke hook in het goede bestand staat: persoonlijk in ~/.claude, teamafspraken in .claude.
3. Noem per hook wat er gebeurt als het commando faalt of jq ontbreekt.
4. Pas nog niets aan. Stel alleen wijzigingen voor, met de reden erbij.

Waarom deze prompt werkt

Stap 3 is het belangrijkste. Een hook die faalt, laat bij de meeste events alles gewoon door, en dat merk je pas als het een keer misgaat. Door Claude per hook te laten benoemen wat er bij een fout gebeurt, zie je meteen welke hook een vangnet is en welke alleen gemak. Stap 4 houdt jou aan het stuur: je leest eerst, dan pas past Claude iets aan.

Of laat Claude de hook schrijven

Claude Code heeft een meegeleverde skill /update-config. Typ bijvoorbeeld /update-config voeg een hook toe die na elke bewerking prettier draait en Claude past het juiste settings-bestand aan. Handig, maar lees het resultaat met de prompt hierboven na. Werk je in de VS Code-extensie, dan kun je hooks ook bekijken en aanpassen via het /-menu, onderdeel Customize, Hooks; zie Claude Code in VS Code.

Problemen

Claude Code hooks werken niet? Meldingen en oplossingen

Zoek je symptoom in de eerste kolom. De meldingen tussen aanhalingstekens komen letterlijk uit Claude Code. Kom je er niet uit, start Claude Code dan met claude --debug en zoek in het logbestand onder ~/.claude/debug naar regels die met Hooks: beginnen.

Ons oordeel

Ons oordeel: wanneer Claude Code hooks de moeite waard zijn

In onze trainingen zien we dat hooks het meeste opleveren bij regels die je team nu al heeft, maar die mensen en modellen soms vergeten: opmaak, tests, bestanden waar niemand aan mag komen. Ze leveren het minste op als je ze inzet voor dingen waar oordeel bij nodig is.

Wanneer wel

Je merkt dat je Claude steeds hetzelfde moet zeggen: draai de formatter, raak .env niet aan, push niet naar main. Je werkt met meerdere mensen aan één repository en wilt dat iedereen dezelfde regels krijgt. Of je laat Claude lang zelfstandig werken en wilt een seintje als hij op je wacht. Dan is een hook goedkoop: een command-hook draait lokaal, zonder dat het model eraan te pas komt.

Wanneer niet, of nog niet

Je werkt nog maar een paar dagen met Claude Code. Leer dan eerst de plan mode en een goede CLAUDE.md; hooks lossen een probleem op dat je pas ziet als je de basis kent. Ook niet voor beslissingen waar oordeel bij nodig is, zoals of een tekst de juiste toon heeft. Daar zijn prompt- en agent-hooks voor, die een model laten beslissen, maar die kosten tokens en zijn minder voorspelbaar. Agent-hooks noemt Anthropic zelf nog experimenteel.

De fout die we het vaakst zien: een hook die stil faalt

Iemand bouwt een blokkade, ziet een keer de melding en vertrouwt er daarna op. Maar een hook die faalt, omdat jq ontbreekt bij een nieuwe collega, het pad niet klopt of het script niet uitvoerbaar is, laat bij de meeste events alles gewoon door. Anthropic schrijft het letterlijk: een beleidshook met een verkeerd pad laat dan alles door. Test daarom elke blokkerende hook op een nieuwe computer met de echo-test van hierboven, en zet vanaf versie 2.1.295 "onFailure": "block" op hooks die echt moeten tegenhouden.

Klantgegevens en de AVG

Een command-hook draait op je eigen computer en stuurt zelf niets naar buiten. Dat verandert als je een http-hook gebruikt of in je script een externe dienst aanroept: dan gaan de gegevens van de tool mee, en daar kunnen bestandsinhoud of klantgegevens in zitten. Behandel zo'n endpoint als elke andere verwerker, met een verwerkersovereenkomst als er persoonsgegevens langs kunnen komen. Let ook op logbestanden: een hook die elk commando opslaat, slaat ook wachtwoorden of tokens op die in een commando stonden. Meer over de dataroutes van Claude Code lees je in Claude Code en privacy.

Hooks van anderen

Een hook draait met jouw volledige gebruikersrechten. Clone je een repository met hooks in .claude/settings.json, dan vraagt Claude Code je eerst om de map te vertrouwen; lees die hooks voordat je ja zegt. Let op bij scripts met claude -p: daar verschijnt die vraag niet en draaien de hooks van de repository direct. Hetzelfde geldt voor plugins: lees wat een plugin aan hooks meebrengt voordat je hem installeert, zie Claude-plugins.

Een voorbeeld uit het MKB

Neem een klein webbureau dat websites en een paar klantportalen onderhoudt, met twee ontwikkelaars en een projectleider die af en toe zelf kleine wijzigingen met Claude Code doet. Een werkbare start: de formatter en de blokkade in .claude/settings.json van elke repository, met in de blokkadelijst ook de map met exportbestanden van klanten. De melding zet ieder in zijn eigen ~/.claude/settings.json. Bij het onboarden van een nieuwe collega hoort dan één vaste stap: jq installeren en de echo-test draaien. Zo weet het bureau dat de afspraken ook op de nieuwe laptop gelden.

Wat nu?

Wat doe je na je eerste Claude Code hooks?

Werken de drie hooks, dan zijn dit de logische vervolgstappen. Kies er één, niet alles tegelijk.

Meer events en opties

Alle 33 events, de vijf soorten handlers, matchers, het if-veld en de timeouts staan op een rij in Claude Code commands: hooks. Een korte uitleg van hooks naast subagents en skills vind je bij de functies van Claude Code. Wat een hook in één zin is, staat in het woordenboek onder hooks.

Je instructies op orde

Hooks dwingen af, CLAUDE.md legt uit. Die twee horen bij elkaar: zet in je CLAUDE.md waarom de regels bestaan, en laat de hook de regel bewaken. Werk je in VS Code, volg dan Claude Code in VS Code.

Hooks delen met je team

Wil je dezelfde hooks in meerdere repositories, bundel ze dan in een plugin; hoe dat werkt staat bij Claude-plugins. Een kant-en-klare bundel met agents, skills en hooks bekijk je in Everything Claude Code, waar je ook leest waarom je die hooks niet blind aanzet. Wil je reviews als vaste stap, lees dan Claude Code review.

Verder lezen

Hoe je Claude Code in het algemeen goed inzet, lees je in Claude Code gebruiken. Wil je hooks, CLAUDE.md en permissies met je team als één werkwijze neerzetten, dan behandelen we dat in de Claude Code Masterclass.