Claude Code-hooks uitgelegd: elk event en waar het voor dient

01Hoe een hook is opgebouwd

Een hookconfiguratie heeft drie niveaus:

1. Het hook-event, zoals PreToolUse of Stop.
2. Een matchergroep, die bepaalt wanneer de hook afgaat, bijvoorbeeld "alleen voor de Bash-tool".
3. Een of meer hook-handlers: het onderdeel dat daadwerkelijk wordt uitgevoerd.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Dit voert een lintscript uit nadat Claude een bestand heeft geschreven of bewerkt. Wil je een tweede event toevoegen, zet dan een extra key naast de bestaande in hetzelfde hooks-object.

02Waar hooks staan

Hooks uit verschillende bestanden worden bij elkaar opgeteld en vervangen elkaar niet. Typ /hooks in Claude Code om alle actieve hooks te zien en waar ze vandaan komen.

In een interactieve sessie houdt Claude Code hooks tegen, ook je eigen, totdat je de workspace trust-dialoog voor de map hebt geaccepteerd.

03Handlertypes

De meeste hooks zijn "type": "command", wat een shellcommando uitvoert. Er zijn nog vier andere:

• http: POST de event-JSON naar een URL en leest de response body.
• mcp_tool: roept een tool aan op een MCP-server die je hebt geconfigureerd.
• prompt: stelt een Claude-model één vraag en leest een JSON-beslissing uit.
• agent: start een subagent die eerst bestanden kan lezen voordat hij beslist (experimenteel).

Command hooks draaien met al je gebruikersrechten, via sh -c op macOS en Linux en via Git Bash (of PowerShell) op Windows. Voeg "async": true toe om een hook op de achtergrond te draaien; hij kan dan geen beslissingen meer nemen.

04Matchers

De matcher bepaalt bij welke keren dat een event optreedt de hook draait. Waarop gematcht wordt hangt af van het event: de toolnaam bij tool-events, het notificatietype bij Notification, de manier waarop de sessie is gestart bij SessionStart, enzovoort.

• "*", "" of helemaal geen matcher matcht alles.
• Letters, cijfers, _, -, spaties, | en , worden als exacte namen behandeld. Edit|Write matcht beide tools.
• Al het andere is een JavaScript-regex, dus mcp__memory__.* matcht elke tool van één MCP-server.

Matchers zijn hoofdlettergevoelig. Sommige events, waaronder Stop en UserPromptSubmit, negeren matchers. Bij tool-events kun je één handler verder afbakenen met een if-veld met een permissieregel zoals "Bash(git *)".

05Input: wat je hook binnenkrijgt

Elke hook krijgt JSON via stdin met een paar algemene velden, waaronder session_id, transcript_path, cwd en hook_event_name, plus velden die specifiek zijn voor het event. Een PreToolUse-hook voor een Bash-call krijgt bijvoorbeeld ook tool_name en tool_input.command. Lees het uit met jq of een andere JSON-parser:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Output: exitcodes en JSON

Een hook kan op twee manieren iets teruggeven.

Exitcodes. 0 betekent succes. 2 is een blokkerende fout: bij events die kunnen blokkeren stopt de actie en wordt je stderr de reden. Elke andere code, ook de gebruikelijke 1, is een niet-blokkerende fout: de actie gaat gewoon door en je ziet een melding over een hook-fout. Moet een hook een regel afdwingen, exit dan met 2, niet met 1.

JSON op stdout. Exit met 0 en print één JSON-object voor meer controle. Sommige velden werken overal, zoals continue: false om Claude helemaal te stoppen. Andere zijn per event: Stop gebruikt decision: "block" met een reason, terwijl PreToolUse en PermissionRequest hun beslissing in hookSpecificOutput zetten. Print verder niets op stdout: één verdwaalde regel uit je shellprofiel en Claude Code kan de JSON niet meer lezen.

07Alle hook-events

Anthropic voegt af en toe events toe, dus kijk in de hooks-referentie voor de actuele lijst en de inputvelden van elk event.

08Welke events relevant zijn voor notificaties

Vier events dekken bijna alles waarover je een melding wilt krijgen:

• Stop voor "Claude is klaar". Zie de handleiding over de Stop hook.
• Notification voor "Claude wacht op je", met types als permission_prompt en idle_prompt. Zie de handleiding over de Notification hook.
• PermissionRequest om direct een melding te krijgen, of te antwoorden, zodra er toestemming nodig is. Zie de handleiding over PermissionRequest.
• PreToolUse op de tool AskUserQuestion, om de meerkeuzevragen van Claude te zien of te beantwoorden. Zie vragen beantwoorden vanaf je telefoon.

Wil je een desktopsetup die je zo kunt plakken? Begin dan met een notificatie krijgen als Claude Code klaar is.

09Waar Claude Code Notifier in past

Claude Code Notifier is volledig op deze hooks gebouwd. De gratis command line tool, ccn, draait op Mac, Windows en Linux. Bij de installatie worden zeven hook-entries toegevoegd aan ~/.claude/settings.json, die elk ccn hook uitvoeren, en wordt eenmalig een backup van het bestand gemaakt. ccn draait per event een paar milliseconden en stopt dan weer, dus er blijft niets op de achtergrond draaien.

Op zichzelf toont het desktopnotificaties. Koppel je de iPhone- of Android-app, dan sturen dezelfde hooks je antwoorden terug: een permissie toestaan of weigeren, een vraag beantwoorden of de volgende instructie sturen nadat Claude is gestopt. Het is onafhankelijk en niet gemaakt door Anthropic. Heb je alleen een log of een lint-stap nodig, dan zijn een paar eigen regels simpeler. Meer details vind je op de ccn-pagina.

10FAQ