
notifications
Système de notifications avancé avec queue persistante, dispatchers multiples et gestion complète
- GitHub stars
- 9
Install
/plugin install notifications@atournayre-claude-plugin-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add atournayre/claude-marketplace.
Contents
Discovered from sourceAgents 4
Changelog
Toutes les modifications notables du plugin notifications seront documentées ici.
Le format est basé sur Keep a Changelog, et ce projet adhère au Semantic Versioning.
[1.0.2] - 2026-01-26
Fixed
- Correction structure
plugin.jsonpour conformité manifest Claude Codeauthor: conversion string → objet avecnameetemailrepository: conversion objet → string simple- Suppression clés invalides :
hooks,scripts,requirements,features
[1.0.1] - 2026-01-25
Fixed
- Suppression import inutilisé
format_notification_message - Cleanups whitespace dans
notification.py - Mise à jour imports utilitaires desktop notification
Added
- Nouvelle fonction
play_beep()pour notifications desktop avec support :- PulseAudio via
paplay(préféré) - Fallback sur terminal beep (BEL)
- Gestion timeouts et fallbacks gracieux
- PulseAudio via
- Support
get_friendly_title()pour titres notifications plus lisibles - Play beep lors des notifications desktop
1.0.0 - 2026-01-25
🔧 Corrigé
Chemins d'installation
- Utilisation de
${CLAUDE_PLUGIN_ROOT}dans la configuration des hooks pour portabilité - Utilisation de variables d'environnement
CLAUDE_PLUGIN_ROOTetCLAUDE_PLUGIN_DIRpour imports Python dynamiques - Fallback sur calcul via
Path(__file__)si variables absentes - Fichiers corrigés :
scripts/dispatch-notifications.py- Import dynamique du module hooksscripts/mark-notification-read.py- Import dynamique du module hookshooks/notification.py- Import dynamique des utilitaires
- Configuration hooks corrigée dans README avec syntaxe
${CLAUDE_PLUGIN_ROOT} - Compatible installation standard ET développement local
🎉 Ajouté
Infrastructure
- Système de queue persistante
queue.jsonlpour toutes les notifications - Auto-détection multi-projet du fichier queue
- Backend
FileQueueBackendpour gestion centralisée - Support statuts
unread/readpour traçabilité
Hooks
notification.py: Hook principal pour capture événementswrite_notification.py: API Python pour écriture notifications- Utils complets dans
hooks/utils/notification/:backends/file_queue.py: Backend queue.jsonldata.py: Structures de donnéesdesktop.py: Notifications desktopfactory.py: Factory backendsformatters.py: Formatage messageshistory.py: Gestion historiqueicons.py: Icônes système
Scripts CLI
dispatch-notifications.py: Dispatcher configurable avec support :notify-send: Notifications desktop Linux (auto-read)phpstorm: Préparé pour intégration IDE (futur)custom: Support dispatchers personnalisés
view-notifications.sh: Visualisation colorée historiquemark-notification-read.py: Marquage manuel read/unread
Configuration
- Variables d'environnement :
CLAUDE_FILE_QUEUE_FILE: Chemin custom queueCLAUDE_NOTIFICATION_DISPATCHER: Type dispatcher
- Configuration hooks Claude Code complète
- Système auto-détection intelligent (4 niveaux)
Fonctionnalités
- Support priorités :
low,normal,high,critical - Support types :
info,success,warning,error,permission_prompt,task_complete,test - Métadonnées extensibles par notification
- Emojis et formatage avancé
- Timeouts adaptatifs selon priorité
- Session tracking et project tracking
Documentation
- README.md complet avec :
- Guide installation
- Exemples utilisation
- Architecture détaillée
- Guide migration
- Troubleshooting
docs/notification-system-simple.md: Architecture système- Documentation API complète
- Exemples code Python et CLI
🔧 Configuration
Configuration minimale requise dans .claude/settings.json :
{
"env": {
"CLAUDE_FILE_QUEUE_FILE": "",
"CLAUDE_NOTIFICATION_DISPATCHER": "notify-send"
},
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/hooks/notification.py --desktop && ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/dispatch-notifications.py"
}
]
}
]
}
}
Le chemin vers le marketplace garantit la stabilité lors des mises à jour du plugin.
📦 Contenu du plugin
notifications/
├── .claude-plugin/plugin.json
├── hooks/
│ ├── notification.py
│ ├── write_notification.py
│ └── utils/notification/
│ ├── backends/file_queue.py
│ ├── data.py
│ ├── desktop.py
│ ├── factory.py
│ ├── formatters.py
│ ├── history.py
│ └── icons.py
├── scripts/
│ ├── dispatch-notifications.py
│ ├── mark-notification-read.py
│ └── view-notifications.sh
├── docs/
│ └── notification-system-simple.md
├── README.md
└── CHANGELOG.md
✨ Avantages
- ✅ Source unique : toutes notifications dans
queue.jsonl - ✅ Historique persistant : aucune perte
- ✅ Multi-projet : isolation automatique
- ✅ Extensible : dispatchers custom faciles
- ✅ Traçabilité : statuts et métadonnées
- ✅ Simple : architecture épurée vs ancien système
🔄 Migration
Remplace l'ancien hook customize/hooks/notification.py (simple logging) par ce système complet.
🐛 Bugs connus
Aucun bug connu à cette version.
📝 Notes
Cette version 1.0.0 est la première release stable du système de notifications.
Elle remplace l'ancien système basique de customize par une architecture complète et extensible.
Plugin Notifications
Système de notifications avancé pour Claude Code avec queue persistante, dispatchers multiples et gestion complète.
📋 Vue d'ensemble
Ce plugin fournit une infrastructure complète de notifications pour Claude Code :
- Queue persistante :
queue.jsonlpour historique et traçabilité - Auto-détection multi-projet : Chaque projet a sa propre queue
- Dispatchers configurables :
notify-send,phpstorm(futur), custom - Gestion complète : read/unread, priorités, types, métadonnées
- Scripts CLI : Commandes pour visualiser, dispatcher, marquer
🚀 Installation
/plugin install notifications@atournayre-claude-plugin-marketplace
⚙️ Configuration
Configuration Minimale
.claude/settings.json :
{
"env": {
"CLAUDE_FILE_QUEUE_FILE": "",
"CLAUDE_NOTIFICATION_DISPATCHER": "notify-send"
},
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/hooks/notification.py --desktop && ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/dispatch-notifications.py"
}
]
}
]
}
}
Note : Le chemin pointe vers le marketplace plutôt que vers le cache versionné. Cela garantit que les hooks utilisent toujours la version la plus récente du plugin sans nécessiter de mise à jour de configuration lors des upgrades.
Variables d'environnement
| Variable | Description | Valeur par défaut |
|---|---|---|
CLAUDE_FILE_QUEUE_FILE | Chemin custom vers queue.jsonl | Auto-détection |
CLAUDE_NOTIFICATION_DISPATCHER | Type de dispatcher | notify-send |
Auto-détection du fichier queue
Le système cherche le fichier queue.jsonl dans cet ordre :
CLAUDE_FILE_QUEUE_FILE(si configuré)$CLAUDE_PROJECT_PATH/.claude/notifications/queue.jsonl(hooks).claude/notifications/queue.jsonldu projet (remontée)~/.claude/notifications/queue.jsonl(fallback global)
📝 Utilisation
Écrire une notification
Programmatique (Python) :
from write_notification import write_notification
write_notification(
message="Mon message",
type="info",
emoji="📋",
priority="normal"
)
CLI :
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/hooks/write_notification.py "Message" info 📋 normal
Dispatcher les notifications
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/dispatch-notifications.py
Le dispatcher :
- Lit toutes les notifications
unread - Les affiche via le dispatcher configuré
- Marque comme
read(comportement configurable)
Visualiser l'historique
bash ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/view-notifications.sh
Affichage coloré avec :
- Timestamp
- Emoji
- Message
- Priorité
Marquer comme lu
# Marquer une notification spécifique
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/mark-notification-read.py <notification_id>
# Tout marquer comme read
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/mark-notification-read.py --all
Astuce : Crée un alias shell pour simplifier :
# Dans ~/.bashrc ou ~/.zshrc
NOTIF_PLUGIN="$HOME/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications"
alias notif-dispatch="python3 $NOTIF_PLUGIN/scripts/dispatch-notifications.py"
alias notif-view="bash $NOTIF_PLUGIN/scripts/view-notifications.sh"
alias notif-mark="python3 $NOTIF_PLUGIN/scripts/mark-notification-read.py"
🎨 Format des notifications
{
"id": "uuid",
"timestamp": "2026-01-25T17:00:00",
"status": "unread",
"title": "🔐 permission_prompt",
"message": "Demande de permission bash",
"type": "permission_prompt",
"emoji": "🔐",
"priority": "normal",
"session_title": "...",
"project_name": "...",
"metadata": {}
}
Types de notifications
info: Information généralesuccess: Succès d'opérationwarning: Avertissementerror: Erreurpermission_prompt: Demande de permissiontask_complete: Tâche terminéetest: Notification de test
Priorités
low: Priorité basse (timeout 3s)normal: Priorité normale (timeout 5s)high: Priorité haute (timeout 10s)critical: Critique (permanent)
🔧 Dispatchers
notify-send (défaut)
Affiche via les notifications desktop Linux. Marque automatiquement comme read.
Configuration :
{
"env": {
"CLAUDE_NOTIFICATION_DISPATCHER": "notify-send"
}
}
phpstorm (futur)
Affichera dans PhpStorm via le plugin. Nécessite marquage manuel.
Custom
Crée ton propre dispatcher en éditant dispatch-notifications.py :
def dispatch_custom(notification: Dict[str, Any]) -> bool:
"""Dispatcher custom."""
# Logique custom
return True
# Dans main():
elif dispatcher_type == 'custom':
success = dispatch_custom(notification)
if success:
notification['status'] = 'read' # Auto-read ou pas
Configuration :
{
"env": {
"CLAUDE_NOTIFICATION_DISPATCHER": "custom"
}
}
🏗️ Architecture
Hook → write_notification.py → queue.jsonl
→ dispatch-notifications.py → notify-send (ou autre dispatcher)
Avantages :
- ✅ Source unique : toutes les notifications passent par
queue.jsonl - ✅ Historique persistant : jamais de perte
- ✅ Multi-projet : auto-détection du projet courant
- ✅ Extensible : dispatchers configurables
- ✅ Traçabilité : statuts read/unread
📂 Structure
notifications/
├── .claude-plugin/
│ └── plugin.json
├── hooks/
│ ├── notification.py # Hook principal
│ ├── write_notification.py # Écriture dans queue
│ └── utils/
│ └── notification/
│ ├── __init__.py
│ ├── backends/
│ │ └── file_queue.py # Backend queue.jsonl
│ ├── data.py # Structure données
│ ├── desktop.py # Notifications desktop
│ ├── factory.py # Factory backends
│ ├── formatters.py # Formatage messages
│ ├── history.py # Gestion historique
│ └── icons.py # Icônes système
├── scripts/
│ ├── dispatch-notifications.py # Dispatcher
│ ├── mark-notification-read.py # Marquage read
│ └── view-notifications.sh # Visualisation
├── docs/
│ └── notification-system-simple.md # Doc architecture
├── README.md
└── CHANGELOG.md
🔄 Migration depuis ancien système
Si tu utilisais l'ancien hook notification.py de customize, voici les changements :
Avant (customize)
{
"hooks": {
"notification": "customize/hooks/notification.py"
}
}
Simple logging JSON, TTS optionnel.
Après (notifications)
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/hooks/notification.py --desktop && ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/dispatch-notifications.py"
}
]
}
]
}
}
Système complet avec queue, dispatchers, gestion read/unread. Le chemin vers le marketplace assure la stabilité lors des mises à jour.
🧪 Tests
Envoyer une notification de test :
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/hooks/write_notification.py "Test" test 🧪 normal
python3 ~/.claude/plugins/marketplaces/atournayre-claude-plugin-marketplace/notifications/scripts/dispatch-notifications.py
🐛 Troubleshooting
Notifications pas affichées
- Vérifier
notify-sendinstallé :which notify-send - Vérifier permissions scripts :
chmod +x scripts/* - Vérifier dispatcher configuré :
echo $CLAUDE_NOTIFICATION_DISPATCHER
Queue pas trouvée
- Vérifier auto-détection : chercher
.claude/notifications/queue.jsonl - Forcer chemin :
CLAUDE_FILE_QUEUE_FILE=/path/to/queue.jsonl
Warnings libnotify
libnotify-WARNING: Running in confined mode
Normal en mode confiné (Snap, Flatpak). Les notifications s'affichent quand même.
📄 Licence
MIT
👤 Auteur
Aurélien Tournayre
- GitHub: @atournayre
- Email: aurelien.tournayre@gmail.com
🔗 Liens
Système de notifications simplifié
Principe
Source unique : queue.jsonl dans .claude/notifications/ du projet
Flux :
Event → queue.jsonl (toujours)
→ dispatcher (lit unread et affiche)
Pas de "backend" à choisir, la queue est obligatoire.
Configuration minimale
{
"env": {
"CLAUDE_FILE_QUEUE_FILE": "",
"CLAUDE_NOTIFICATION_DISPATCHER": "notify-send"
},
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/notification.py --desktop && ~/.claude/scripts/dispatch-notifications.py"
}
]
}
]
}
}
Variables :
CLAUDE_FILE_QUEUE_FILE: Chemin custom (vide = auto-détection)CLAUDE_NOTIFICATION_DISPATCHER:notify-send,phpstorm(futur), etc.
Auto-détection du fichier queue
Priorité :
CLAUDE_FILE_QUEUE_FILE(si configuré)$CLAUDE_PROJECT_PATH/.claude/notifications/queue.jsonl(hooks).claude/notifications/queue.jsonldu projet (remontée)~/.claude/notifications/queue.jsonl(fallback global)
Multi-projet : Chaque projet a son propre queue.jsonl.
Format des notifications
{
"id": "uuid",
"timestamp": "2026-01-25T17:00:00",
"status": "unread",
"title": "🔐 permission_prompt",
"message": "Demande de permission bash",
"type": "permission_prompt",
"emoji": "🔐",
"priority": "normal",
"session_title": "...",
"project_name": "...",
"metadata": {}
}
Écrire une notification (programmatique)
from write_notification import write_notification
write_notification(
message="Mon message",
type="info",
emoji="📋",
priority="normal"
)
Ou en CLI :
~/.claude/hooks/write_notification.py "Message" info 📋 normal
Dispatcher
Le dispatcher lit les notifications unread et les affiche :
~/.claude/scripts/dispatch-notifications.py
Dispatcher notify-send (auto-read) :
- Lit les
unread - Affiche via
notify-send - Marque automatiquement comme
read
Dispatcher phpstorm (futur, manual-read) :
- Lit les
unread - Affiche dans l'IDE
- Utilisateur clique → marque comme
read
Marquage manuel
# Marquer une notification
~/.claude/scripts/mark-notification-read.py <notification_id>
# Tout marquer comme read
~/.claude/scripts/mark-notification-read.py --all
Utilitaires
# Voir joliment
~/.claude/scripts/view-notifications.sh
# Lister les unread
cat .claude/notifications/queue.jsonl | jq 'select(.status == "unread")'
# Compter unread
cat .claude/notifications/queue.jsonl | jq -r 'select(.status == "unread")' | wc -l
Architecture simplifiée
Avant (complexe) :
Hook → BackendFactory → FileQueueBackend → queue.jsonl
→ NotifySendBackend → notify-send
→ TerminalBackend → log
Après (simple) :
Hook → write_notification.py → queue.jsonl
→ dispatch-notifications.py → notify-send (ou autre)
Avantages :
- ✅ Moins de code (suppression BackendFactory, NotificationData, etc.)
- ✅ Plus clair (un seul chemin : queue obligatoire)
- ✅ Plus flexible (dispatcher séparé, facile à étendre)
- ✅ Multi-projet natif (auto-détection)
Développer un dispatcher custom
Éditer dispatch-notifications.py :
def dispatch_custom(notification: Dict[str, Any]) -> bool:
"""Dispatcher custom."""
# Logique custom
return True
# Dans main():
elif dispatcher_type == 'custom':
success = dispatch_custom(notification)
if success:
notification['status'] = 'read' # Auto-read ou pas
Configurer :
{
"env": {
"CLAUDE_NOTIFICATION_DISPATCHER": "custom"
}
}
Tests d'intégration - Notifications Desktop Claude Code
Prérequis
Vérifier que notify-send est installé :
which notify-send
# Si absent : sudo apt install libnotify-bin
Test 1 : Notification de complétion
Objectif : Vérifier qu'une notification desktop s'affiche à la fin d'une tâche
Étapes :
- Lancer Claude Code dans un projet
- Exécuter une commande simple :
ls - Attendre que Claude termine
- Vérifier qu'une notification desktop apparaît avec :
- Icône : ✅
- Titre : "Claude Code - Tâche terminée" ou titre de session si défini
- Corps : Session ID + durée
Résultat attendu : Notification visible avec emoji ✅
Test 2 : Emojis par type de notification
2.1 Permission Prompt (🔐)
Étapes :
- Configurer Claude Code pour demander permission sur certaines actions
- Exécuter une action nécessitant permission
- Vérifier notification avec 🔐
Résultat attendu : Notification "🔐 Claude Code" ou "🔐 [titre session]"
2.2 Idle Prompt (⏰)
Étapes :
- Lancer Claude Code
- Attendre 60+ secondes sans donner d'input
- Vérifier notification idle_prompt
Résultat attendu : Notification "⏰ Claude Code" indiquant attente input
2.3 Auth Success (✅)
Étapes :
- Se déconnecter de Claude Code
- Se reconnecter
- Vérifier notification auth_success
Résultat attendu : Notification "✅ Claude Code"
2.4 Elicitation Dialog (❓)
Étapes :
- Utiliser un outil MCP nécessitant input utilisateur
- Vérifier notification elicitation_dialog
Résultat attendu : Notification "❓ Claude Code"
Test 3 : Titre de session (via /rename)
3.1 Sans titre de session
Étapes :
- Lancer nouvelle session Claude Code (sans
/rename) - Exécuter une tâche
- Observer notification
Résultat attendu :
- Titre : "✅ Claude Code - Tâche terminée"
- Corps : "Session: abc123\nDurée: X.Xs"
3.2 Avec titre de session
Étapes :
- Lancer nouvelle session
- Exécuter
/rename "Amélioration notifications desktop" - Exécuter une tâche
- Observer notification
Résultat attendu :
- Titre : "✅ Amélioration notifications desktop"
- Corps : "Durée: X.Xs"
Test 4 : Désactivation des notifications
Étapes :
- Modifier
.claude/settings.json:{ "env": { "CLAUDE_DESKTOP_NOTIFY": "false" } } - Redémarrer Claude Code
- Exécuter une tâche
Résultat attendu : Aucune notification desktop (TTS peut toujours fonctionner)
Test 5 : Fallback gracieux
Étapes :
- Sauvegarder
notify-send:sudo mv /usr/bin/notify-send /usr/bin/notify-send.bak - Lancer Claude Code
- Exécuter une tâche
- Vérifier que le hook ne crash pas
- Restaurer
notify-send:sudo mv /usr/bin/notify-send.bak /usr/bin/notify-send
Résultat attendu : Pas de crash, pas d'erreur visible, hook se termine proprement
Test 6 : Notification subagent
Étapes :
- Lancer une tâche nécessitant un sous-agent
- Attendre fin du sous-agent
- Observer notification
Résultat attendu :
- Titre : "🤖 [titre session]" ou "🤖 Sous-agent terminé"
- Urgency : low
Checklist finale
- Test 1 : Notification complétion ✅
- Test 2.1 : Emoji permission_prompt 🔐
- Test 2.2 : Emoji idle_prompt ⏰
- Test 2.3 : Emoji auth_success ✅
- Test 2.4 : Emoji elicitation_dialog ❓
- Test 3.1 : Sans titre session (titre générique)
- Test 3.2 : Avec titre session (/rename)
- Test 4 : Désactivation CLAUDE_DESKTOP_NOTIFY=false
- Test 5 : Fallback sans notify-send
- Test 6 : Notification sous-agent 🤖
- Pas de régression TTS existant
- Logs JSON fonctionnent toujours
Notes
- Les notifications desktop s'affichent en plus du TTS existant
- Les emojis doivent être visibles dans le titre de la notification
- Le titre de session doit être lu depuis
sessions-index.json - Tous les hooks doivent fail silently en cas d'erreur
Sponsors
Details
- Marketplace
- atournayre/claude-marketplace
- Source
- notifications
- Category
- Community