Add Event Notifications Plugin for Claude Code Hooks

[nodeGarden]

Add Event Notifications Plugin for Claude Code Hooks

Overview

Adds an event notifications plugin that provides audio announcements and OS notifications for Claude Code hook events. Built on top of the plugin manager system, this demonstrates the plugin architecture in action.

Important

This was vibe coded with Claude

---

What's Included

This PR builds on the plugin manager system (#21) and adds:

Event Notifications Plugin

• Audio announcements via TTS (Text-to-Speech)
• OS notifications for important hook events
• Multiple TTS providers: ElevenLabs, OpenAI TTS, pyttsx3 (offline)
• Configurable per hook type via config/audio_config.json
• Zero dependencies required - all TTS providers are optional

Plugin Features

• ✅ Handles all 9 hook types (SessionStart, SessionEnd, PreToolUse, PostToolUse, Stop, SubagentStop, Notification, PreCompact, UserPromptSubmit)
• ✅ Configurable enable/disable per hook
• ✅ Custom messages per hook type
• ✅ Automatic source_app detection (env → config → folder name)
• ✅ Background execution (non-blocking)
• ✅ Graceful fallback if TTS unavailable

File Structure

.claude/hooks/plugins/event_notifications/
├── plugin.json                      # Plugin metadata
├── config/
│   └── audio_config.json           # Per-hook configuration
├── src/
│   ├── plugin.py                   # Main entry point
│   ├── audio_announcer.py          # TTS orchestration
│   ├── tts_providers.py            # Provider implementations
│   └── _announce_background.py    # Background execution wrapper
└── test.py                         # Plugin test suite

Configuration

Plugin Metadata (plugin.json)

{
  "name": "event_notifications",
  "version": "1.0.0",
  "description": "Event notifications via audio announcements and OS notifications",
  "enabled": true,
  "priority": 50,
  "hooks": ["SessionStart", "SessionEnd", "PreToolUse", "PostToolUse", "Stop", "SubagentStop", "Notification", "PreCompact", "UserPromptSubmit"],
  "entry_point": "src.plugin:handle_hook"
}

Hook Configuration (config/audio_config.json)

{
  "PostToolUse": {
    "enabled": false,
    "message": "{source_app} used {tool_name}"
  },
  "Stop": {
    "enabled": true,
    "message": "{source_app} completed all tasks"
  }
}

TTS Provider Support

1. ElevenLabs

• High quality voices
• Requires API key: ELEVENLABS_API_KEY
• Optional package: elevenlabs

2. OpenAI TTS

• Natural sounding voices
• Requires API key: OPENAI_API_KEY
• Optional package: openai

3. pyttsx3 (Offline) (Recommended)

• Works without internet
• No API key required
• Optional package: pyttsx3

Fallback: If no TTS provider is available, notifications are silently skipped.

Usage Examples

Enable Notifications for Specific Hooks

Edit .claude/hooks/plugins/event_notifications/config/audio_config.json:

{
  "Stop": {
    "enabled": true,
    "message": "Task completed"
  },
  "SubagentStop": {
    "enabled": true,
    "message": "Subagent finished"
  }
}

Customize Messages with Variables

Available variables: {source_app}, {session_id}, {tool_name}, etc.

{
  "PostToolUse": {
    "enabled": true,
    "message": "{source_app} used {tool_name}"
  }
}

Set Source App Name

Three ways (priority order):

1. Environment variable: export CLAUDE_SOURCE_APP="my-app"
2. Config file: Create .claude/hooks/config.json with {"source_app": "my-app"}
3. Auto-detection: Uses project folder name automatically

Testing

Test the Plugin

# Test all hooks
cd .claude/hooks/plugins/event_notifications
python3 test.py

# Test specific hook via plugin manager
cd .claude/hooks
python3 plugin_manager.py --test Stop

List All Plugins

cd .claude/hooks
python3 plugin_manager.py --list

Expected output:

Discovered Plugins:
------------------------------------------------------------
event_notifications v1.0.0 (✓ enabled)
  Hooks: SessionStart, SessionEnd, PreToolUse, PostToolUse, Stop, SubagentStop, Notification, PreCompact, UserPromptSubmit

Dependencies

All optional - plugin works without any of these:

# Install TTS providers (optional)
pip install elevenlabs  # For ElevenLabs TTS
pip install openai      # For OpenAI TTS
pip install pyttsx3     # For offline TTS

Integration with Plugin Manager

This plugin demonstrates:

• ✅ Auto-discovery from plugins/ directory
• ✅ Metadata validation via plugin.json
• ✅ Priority-based execution (priority: 50)
• ✅ Fail-safe error handling (never crashes hooks)
• ✅ Graceful degradation (works without TTS)
• ✅ Source app detection (env → config → folder name)

Benefits

For Users

• Ambient awareness - Know when tasks complete without watching the screen
• Multi-tasking - Work on other things while Claude processes
• Configurable - Enable only the notifications you want
• Zero setup - Works with folder name auto-detection

For Developers

• Reference implementation - Shows how to build a complete plugin
• Best practices - Background execution, config loading, error handling
• Extensible - Easy to add new TTS providers or notification types

Changes Summary

New Files:

• plugins/event_notifications/ - Complete plugin implementation (12 files)
  • plugin.json - Plugin metadata
  • config/audio_config.json - Hook configuration
  • src/plugin.py - Main entry point
  • src/audio_announcer.py - TTS orchestration
  • src/tts_providers.py - Provider implementations
  • src/_announce_background.py - Background execution
  • test.py - Plugin test suite

Dependencies on:

• PR Add Plugin Manager System for Claude Code Hooks #21 (Plugin Manager System) - Required base infrastructure

Breaking Changes

None. This is a purely additive feature.

Migration Notes

If you were using the old audio announcements system:

1. The new plugin-based system replaces standalone audio hooks
2. Configuration is now in plugins/event_notifications/config/audio_config.json
3. All features are preserved with better organization

Related PRs

• Add Plugin Manager System for Claude Code Hooks #21 - Plugin Manager System (required)

---

Branch: feature/event-notifications
Base: main
Commits: 4

• 033dcbc Add plugin manager system for hooks
• 8c3571f Improve plugin system with logging, validation, and dev tools
• 5f7384f Add comprehensive test suite for plugin manager
• 9518d3e Add source_app auto-detection to hook plugins
• 935d97e Add event notifications plugin

Testing:

• ✅ Plugin manager tests: 9/9 passing
• ✅ Event notifications plugin discovered and enabled
• ✅ Source app detection working (env → config → folder name)

Documentation:

• ✅ Plugin configuration examples
• ✅ TTS provider setup instructions
• ✅ Testing guide included