Système de notifications avancé avec queue persistante, dispatchers multiples et gestion complète

GitHub stars
9

Install

/plugin install notifications@atournayre-claude-plugin-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add atournayre/claude-marketplace.

Contents

Discovered from source

Agents 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.json pour conformité manifest Claude Code
    • author : conversion string → objet avec name et email
    • repository : 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
  • 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_ROOT et CLAUDE_PLUGIN_DIR pour imports Python dynamiques
  • Fallback sur calcul via Path(__file__) si variables absentes
  • Fichiers corrigés :
    • scripts/dispatch-notifications.py - Import dynamique du module hooks
    • scripts/mark-notification-read.py - Import dynamique du module hooks
    • hooks/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.jsonl pour toutes les notifications
  • Auto-détection multi-projet du fichier queue
  • Backend FileQueueBackend pour gestion centralisée
  • Support statuts unread / read pour traçabilité
Hooks
  • notification.py : Hook principal pour capture événements
  • write_notification.py : API Python pour écriture notifications
  • Utils complets dans hooks/utils/notification/ :
    • backends/file_queue.py : Backend queue.jsonl
    • data.py : Structures de 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 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 historique
  • mark-notification-read.py : Marquage manuel read/unread
Configuration
  • Variables d'environnement :
    • CLAUDE_FILE_QUEUE_FILE : Chemin custom queue
    • CLAUDE_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.jsonl pour 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

VariableDescriptionValeur par défaut
CLAUDE_FILE_QUEUE_FILEChemin custom vers queue.jsonlAuto-détection
CLAUDE_NOTIFICATION_DISPATCHERType de dispatchernotify-send

Auto-détection du fichier queue

Le système cherche le fichier queue.jsonl dans cet ordre :

  1. CLAUDE_FILE_QUEUE_FILE (si configuré)
  2. $CLAUDE_PROJECT_PATH/.claude/notifications/queue.jsonl (hooks)
  3. .claude/notifications/queue.jsonl du projet (remontée)
  4. ~/.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érale
  • success : Succès d'opération
  • warning : Avertissement
  • error : Erreur
  • permission_prompt : Demande de permission
  • task_complete : Tâche terminée
  • test : 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-send installé : 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

🔗 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é :

  1. CLAUDE_FILE_QUEUE_FILE (si configuré)
  2. $CLAUDE_PROJECT_PATH/.claude/notifications/queue.jsonl (hooks)
  3. .claude/notifications/queue.jsonl du projet (remontée)
  4. ~/.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 :

  1. Lancer Claude Code dans un projet
  2. Exécuter une commande simple : ls
  3. Attendre que Claude termine
  4. 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 :

  1. Configurer Claude Code pour demander permission sur certaines actions
  2. Exécuter une action nécessitant permission
  3. Vérifier notification avec 🔐

Résultat attendu : Notification "🔐 Claude Code" ou "🔐 [titre session]"

2.2 Idle Prompt (⏰)

Étapes :

  1. Lancer Claude Code
  2. Attendre 60+ secondes sans donner d'input
  3. Vérifier notification idle_prompt

Résultat attendu : Notification "⏰ Claude Code" indiquant attente input

2.3 Auth Success (✅)

Étapes :

  1. Se déconnecter de Claude Code
  2. Se reconnecter
  3. Vérifier notification auth_success

Résultat attendu : Notification "✅ Claude Code"

2.4 Elicitation Dialog (❓)

Étapes :

  1. Utiliser un outil MCP nécessitant input utilisateur
  2. 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 :

  1. Lancer nouvelle session Claude Code (sans /rename)
  2. Exécuter une tâche
  3. 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 :

  1. Lancer nouvelle session
  2. Exécuter /rename "Amélioration notifications desktop"
  3. Exécuter une tâche
  4. Observer notification

Résultat attendu :

  • Titre : "✅ Amélioration notifications desktop"
  • Corps : "Durée: X.Xs"

Test 4 : Désactivation des notifications

Étapes :

  1. Modifier .claude/settings.json :
    {
      "env": {
        "CLAUDE_DESKTOP_NOTIFY": "false"
      }
    }
    
  2. Redémarrer Claude Code
  3. Exécuter une tâche

Résultat attendu : Aucune notification desktop (TTS peut toujours fonctionner)


Test 5 : Fallback gracieux

Étapes :

  1. Sauvegarder notify-send :
    sudo mv /usr/bin/notify-send /usr/bin/notify-send.bak
    
  2. Lancer Claude Code
  3. Exécuter une tâche
  4. Vérifier que le hook ne crash pas
  5. 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 :

  1. Lancer une tâche nécessitant un sous-agent
  2. Attendre fin du sous-agent
  3. 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

More from atournayre/claude-marketplace

All 18