claude-notifications

claude-notifications

A Claude Code plugin that sends notifications anywhere — Slack, Discord, email, WhatsApp, desktop (with voice via say), web push, and generic webhooks — driven by Claude Code's hook events. Ships with an optional Electron tray app for one-click channel toggling and visual configuration.

When Claude finishes a task, gets stuck waiting for input, or runs a tool you care about, this plugin fans the event out to whichever channels you've enabled. You walk away from the terminal and still get pinged.

What you get

Channel	Purpose	Required setup
desktop	Native banners (macOS / Linux / Windows). Optional spoken alerts via say.	None — works out of the box
slack	Posts to a Slack channel via Incoming Webhook	Webhook URL
discord	Posts to a Discord channel via webhook	Webhook URL
email	Sends email via SMTP or sendmail	SMTP creds
whatsapp	WhatsApp via Twilio or CallMeBot	Twilio account or CallMeBot apikey
webpush	Phone/web push via ntfy.sh, Pushover, or your own VAPID server	ntfy topic, Pushover keys, or webhook
webhook	Generic JSON POST to your own endpoint with HMAC signing	Your URL
custom	Drop a .sh in ~/.claude-notifications/channels/ and it works	One bash file

Voice notifications use say on macOS, spd-say/espeak on Linux. Pick a voice, rate, and template.

Install

# Clone or install via Claude Code's plugin system once published
git clone https://github.com/fadymondy/claude-notifications ~/.claude/plugins/claude-notifications

Then enable it in your Claude Code settings (~/.claude/settings.json):

{
  "plugins": ["claude-notifications"]
}

Restart Claude Code. The hooks register automatically from hooks/hooks.json.

Configure

Three layers, last wins:

1. Plugin defaults — ${CLAUDE_PLUGIN_ROOT}/config/default.json (don't edit)
2. Your global config — ~/.claude-notifications/config.json (edit this)
3. Project-local — <project>/.claude-notifications.json (routing rules only — never put secrets here)

Easiest path: run /notify-setup <channel> from inside Claude Code. It walks you through one channel at a time.

Or copy the example and edit:

mkdir -p ~/.claude-notifications
cp examples/config.example.json ~/.claude-notifications/config.json
chmod 600 ~/.claude-notifications/config.json
$EDITOR ~/.claude-notifications/config.json

Minimal example — Slack only

{
  "channels": {
    "slack": {
      "enabled": true,
      "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXXXXXX",
      "channel": "#claude",
      "events": ["notification", "stop"]
    }
  }
}

That's it. When Claude finishes (stop) or asks for input (notification), Slack pings.

Adding voice alerts

{
  "channels": {
    "desktop": {
      "enabled": true,
      "voice": {
        "enabled": true,
        "name": "",
        "rate": 180,
        "style": "title"
      },
      "sound": "Funk",
      "events": ["notification", "stop"]
    }
  }
}

style picks what gets spoken: title, body, or both. Or set text to a custom template — {title}, {body}, {project}, {event} are substituted.

Natural human voices on macOS. Leave voice.name blank and the plugin uses your System Voice — whatever you've picked in System Settings → Accessibility → Spoken Content → System Voice. Pick a Siri voice there (Voice 1-5, named Ava / Tom / Zoe / etc. depending on macOS version) and notifications will sound like Siri. The plugin doesn't try to second-guess your choice.

To download a Siri voice: System Settings → Accessibility → Spoken Content → System Voice → click the dropdown → Manage Voices… → pick a variation (American/British/Australian/etc.) → tap a voice's cloud icon to download → click Done.

To override the system voice for just Claude notifications, set voice.name to an exact entry from say -v '?'.

Tray app (optional, recommended)