Les notifications de Claude Code ne marchent pas ? Une checklist

011. Vérifie que Claude Code a chargé le hook

Tape /hooks dans le prompt de Claude Code. C'est un navigateur en lecture seule de tous les hooks chargés par Claude Code, avec pour chacun sa provenance : paramètres utilisateur, paramètres du projet, paramètres locaux, un plugin ou la session en cours. Sélectionne un hook pour voir la commande exacte et le fichier où il est défini.

Si ton hook n'est pas dans la liste :

• Le JSON est invalide. Les fichiers de paramètres sont en JSON strict. Une virgule finale ou un commentaire // casse le fichier, et Claude Code affiche une Settings Error au démarrage suivant. Lance claude doctor pour voir les entrées rejetées par Claude Code.
• Le fichier n'est pas au bon endroit. Les hooks personnels vont dans ~/.claude/settings.json (sous Windows, %USERPROFILE%\.claude\settings.json). Les hooks de projet vont dans .claude/settings.json à l'intérieur du projet. Lance /status et regarde la ligne Setting sources pour savoir quels fichiers ont été chargés.
• Le nom de l'événement est faux. Les noms d'événements sont sensibles à la casse : Notification, Stop, PermissionRequest. Un nom d'événement inconnu apparaît en Settings Warning et est ignoré.
• Les hooks sont désactivés. "disableAllHooks": true dans n'importe quel fichier de paramètres désactive tous les hooks. Si /hooks affiche Only hooks from managed settings run here, ton organisation a activé allowManagedHooksOnly et tes propres hooks ne s'exécuteront pas.
• La modification n'a pas été prise en compte. Claude Code recharge normalement les paramètres tout seul. Si le hook n'apparaît pas au bout de quelques secondes, redémarre la session.

022. Accepte la confiance de l'espace de travail

En session interactive, Claude Code bloque les hooks de tous les fichiers de paramètres, y compris ton propre ~/.claude/settings.json, tant que tu n'as pas accepté la boîte de dialogue de confiance pour le dossier. Si tu l'as fermée, ou si tu es dans un dossier où tu n'as jamais ouvert Claude Code, tes hooks n'y tourneront pas. Lance claude dans ce dossier et accepte la boîte de dialogue.

033. Vérifie que l'événement se déclenche au moment où tu le crois

Beaucoup de notifications « cassées » sont en fait une question de timing. D'après la référence des hooks d'Anthropic :

Donc si tu testes un hook Notification en tapant dans le terminal, il risque de ne jamais se déclencher. Passe sur une autre fenêtre et attends. Pour une alerte dès la fin d'un tour, utilise Stop ; le guide du Stop hook explique tout.

Vérifie aussi ton mode de permission. Les versions récentes de Claude Code démarrent les sessions interactives en mode auto, où un classifieur approuve la plupart des actions sans demander. Pas de demande, donc pas de notification permission_prompt ni de hook PermissionRequest. Pour tester les alertes de permission, appuie sur Shift+Tab jusqu'à ce que la barre d'état affiche le mode manuel, puis demande à Claude de faire quelque chose qui nécessite une validation. Les modes de permission expliqués donne tous les détails.

Les matchers sont aussi sensibles à la casse. Un matcher PermissionRequest sur bash ne correspondra pas à l'outil Bash.

044. Lance la commande du hook toi-même

Copie la commande depuis /hooks et lance-la dans un terminal avec une entrée d'exemple :

echo '{"hook_event_name":"Stop","cwd":"/tmp","last_assistant_message":"done"}' | ./my-hook.sh
echo $?

Échecs fréquents :

• command not found : utilise un chemin absolu vers le script, ou ${CLAUDE_PROJECT_DIR} pour les scripts du projet.
• Le script ne fait rien du tout : rends-le exécutable avec chmod +x ./my-hook.sh.
• jq: command not found : installe jq, ou parse le JSON avec Python ou Node.js.

055. Lis le log de debug

Lance Claude Code avec claude --debug. Rien de plus ne s'affiche dans le terminal ; le log va dans ~/.claude/debug/<session-id>.txt. Pour choisir le chemin, utilise claude --debug-file /tmp/claude.log et lance tail -f /tmp/claude.log dans un autre terminal. Si la session tourne déjà, /debug active les logs et t'indique où se trouve le fichier.

Cherche les lignes qui commencent par Hooks:. Chacune indique l'événement, la commande, comment elle s'est terminée (finished with status 0, timed out, failed to start) et sa durée. Pour plus de détails sur le matching, définis CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Deux problèmes n'apparaissent qu'ici :

• Ton profil shell affiche quelque chose. Si ~/.bashrc ou ~/.zshrc exécute un echo et que le shell le charge, ce texte se retrouve devant la sortie JSON de ton hook, et Claude Code traite la sortie comme du texte brut. Cherche Hook output does not start with { dans le log. Entoure la sortie du profil avec if [[ $- == *i* ]]; then ... fi pour qu'elle ne s'exécute que dans les shells interactifs.
• Aucun terminal où écrire. Sur Mac et Linux, les hooks de commande tournent sans terminal de contrôle. Un hook qui essaie de faire sonner la cloche ou d'écrire des séquences d'échappement dans /dev/tty échoue en silence. Utilise plutôt une commande de notification de bureau, ou le paramètre preferredNotifChannel de Claude Code, décrit dans le guide de la cloche du terminal.

066. Vérifie le système d'exploitation

Si le log de debug indique que le hook s'est terminé avec le statut 0 et que tu n'as quand même rien vu, c'est le système d'exploitation qui l'a masquée. Vérifie que l'app qui affiche l'alerte a le droit d'envoyer des notifications, et que Concentration (Mac), Ne pas déranger (Windows) ou l'option Ne pas déranger de ton bureau Linux est désactivé. Sous Linux, un daemon de notifications doit tourner.

Les commandes propres à chaque plateforme sont dans les guides pour macOS, Windows et Linux.

07Si tu utilises Claude Code Notifier

Claude Code Notifier est un outil indépendant (pas développé par Anthropic) qui installe un petit programme, ccn, sous forme de hooks Claude Code. Tout ce qui précède reste valable, car ccn est un hook comme un autre. Commence par ses propres vérifications :

1. ccn doctor vérifie les hooks, les identifiants, la connexion au serveur et la détection de présence. Corrige d'abord tout ce qu'il signale.
2. ccn test envoie une notification de test. Si elle arrive, le problème vient de l'événement ou d'un réglage, pas de la chaîne d'envoi.
3. ccn devices liste les téléphones appairés avec cet ordinateur. S'il n'y en a aucun, refais l'appairage avec ccn pair ; le guide d'appairage t'explique tout.
4. ccn config show affiche les réglages effectifs. Vérifie que notify_on_done, notify_on_permission et notify_on_question sont activés, et que quiet_hours ne couvre pas l'heure actuelle. Les réglages modifiés sur le téléphone arrivent sur l'ordinateur avec ccn sync.

Certains comportements ressemblent à des bugs mais sont voulus :

• Tu es devant ton clavier. Si tu as tapé quelque chose dans les 30 dernières secondes, rien n'attend le téléphone et le terminal pose la question comme d'habitude. Avec quiet_when_present activé (par défaut), le téléphone ne reçoit rien tant que tu es dans le terminal où tourne Claude, et une simple carte d'info si tu es actif dans une autre app.
• Alertes en double ou manquantes sur Mac. Ne fais pas tourner l'ancienne app de barre de menus Mac et ccn sur le même Mac.
• Une longue absence. Si un téléphone ou un ordinateur n'est pas utilisé pendant 60 jours, le serveur supprime son appairage : il faut alors refaire l'appairage.

Sur le téléphone, vérifie que les notifications sont autorisées pour l'app, et que Concentration (iPhone) ou Ne pas déranger (Android) ne la rend pas silencieuse. Sur Android, l'optimisation de la batterie peut retarder les notifications de certaines apps ; si les alertes arrivent en retard, autorise l'app à fonctionner sans restriction dans ses paramètres de batterie. Si tu as modifié settings.json à la main, ccn doctor te dit si ses hooks sont toujours en place. ccn upgrade met à jour vers la dernière version.

08FAQ