Le Notification hook de Claude Code : quand il se déclenche et comment l'utiliser

01Les types de notification

Le matcher d'un hook Notification correspond au type de notification. Laisse-le vide pour tous les types, ou liste ceux que tu veux séparés par |. Les types que tu utiliseras le plus :

Il y en a d'autres, comme agent_needs_input et agent_completed pour les sessions en arrière-plan dans la vue agent, et une série de types quota_auto_resume_* pour les attentes liées aux limites d'usage. La référence des hooks contient la liste complète et à jour.

02Les règles de timing

C'est là que beaucoup se font avoir. Le hook Notification suit le même timing que les notifications desktop de Claude Code, donc dans une session terminal il ne se déclenche que quand tu regardes ailleurs :

• permission_prompt lance un minuteur d'environ six secondes quand le prompt apparaît. Chaque frappe le remet à zéro. Si tu réponds vite, il ne se déclenche jamais.
• idle_prompt se déclenche environ 60 secondes après que Claude a terminé, seulement si tu n'as rien tapé depuis et qu'aucun agent en arrière-plan ne tourne encore. Il ne se déclenche pas pendant que Claude Code attend la réinitialisation d'une limite d'utilisation.
• Une demande qui arrive pendant qu'une autre boîte de dialogue est ouverte est chronométrée à partir de son arrivée : sa notification peut donc te parvenir alors qu'elle attend encore derrière la boîte de dialogue ouverte.

Les hôtes qui gèrent les permissions via l'Agent SDK, comme Claude Desktop et l'extension VS Code, chronomètrent permission_prompt différemment : environ six secondes après la demande, sans report quand tu tapes, et rien n'est envoyé si toi ou un hook PermissionRequest répondez avant.

Si tu veux un signal sans délai, utilise un autre événement :

03Ce que reçoit le hook

En plus des champs communs (session_id, transcript_path, cwd, hook_event_name), un hook Notification reçoit le message de la notification, un title optionnel et le notification_type :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Le message est rédigé par Claude Code lui-même, tu peux donc l'afficher tel quel. cwd est pratique quand tu lances plusieurs sessions et que tu veux savoir quel projet te sollicite.

04Ce que le hook peut faire ou non

Un hook Notification ne peut ni bloquer, ni retarder, ni modifier la notification. Son code de sortie et son stderr sont ignorés, et Claude Code ignore systemMessage et continue dans sa sortie JSON. Il ne sert qu'aux effets de bord.

Il y a un seul champ de sortie qu'il peut utiliser : terminalSequence. Les hooks tournent sans terminal, donc ils ne peuvent pas écrire eux-mêmes de séquences d'échappement, mais ils peuvent en transmettre une à Claude Code pour qu'il l'émette. Ça permet à un hook de déclencher une notification native du terminal dans iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal et d'autres, même dans tmux. Ça ne marche que dans une session interactive avec l'interface de Claude Code à l'écran.

Le réglage preferredNotifChannel n'arrête pas non plus le hook. Même avec les notifications intégrées désactivées, l'événement Notification se déclenche toujours. Ce réglage change seulement la façon dont Claude Code lui-même t'alerte ; voir le guide sur la cloche du terminal.

05Exemples

Un handler différent par type

Lance un script distinct pour les demandes de permission et pour les rappels d'inactivité :

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-alert.sh" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/idle-alert.sh" }]
      }
    ]
  }
}

Rends chaque script exécutable avec chmod +x. Les commandes de notification desktop pour Mac, Windows et Linux se trouvent dans comment recevoir une notification quand Claude Code a terminé, on ne les répète donc pas ici.

Afficher le vrai message et le projet

Ce script (macOS et Linux) met le message de Claude Code et le dossier du projet dans la notification, au lieu d'un texte fixe :

#!/bin/bash
# ~/.claude/hooks/notify.sh
input=$(cat)
msg=$(jq -r '.message // "Claude Code needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // "."' <<<"$input")")

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'on run argv' \
            -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
            -e 'end run' "$msg" "Claude Code: $project"
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code: $project" "$msg"
fi
exit 0

Passer le texte en arguments (on run argv) évite de casser l'AppleScript quand le message contient des guillemets. Il faut que jq soit installé.

Une notification native du terminal

L'exemple d'Anthropic utilise terminalSequence avec OSC 777, que comprennent Ghostty, Warp et urxvt :

#!/bin/bash
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Pour iTerm2, Windows Terminal ou WezTerm, utilise plutôt OSC 9, et pour Kitty OSC 99. Toute séquence hors de celles autorisées est ignorée.

06Où se situe Claude Code Notifier

Un hook Notification qui appelle un service de push envoie l'alerte sur ton téléphone, et pour beaucoup ça suffit. Le guide ntfy montre cette approche.

Ce qui manque, c'est la réponse. Quand permission_prompt se déclenche, Claude attend sur une boîte de dialogue à laquelle un hook Notification ne peut pas répondre. Claude Code Notifier gère ça avec les hooks qui le peuvent : PermissionRequest pour renvoyer ta décision et PreToolUse sur AskUserQuestion pour renvoyer ta réponse. Son outil en ligne de commande gratuit, ccn, tourne sur Mac, Windows et Linux et affiche tout seul des notifications desktop. Avec l'app iPhone ou Android associée, tu peux autoriser une fois, autoriser pour la session ou refuser depuis ton téléphone. Si tu as tapé dans les 30 dernières secondes, rien n'attend le téléphone et le terminal te demande comme d'habitude. C'est un outil indépendant, pas développé par Anthropic. L'installation est décrite sur la page ccn.

07FAQ