# Claude Code Notifications: Get Pinged on Slack, Discord, WhatsApp or Voice

> Claude Code notifications through hooks: a free, open-source plugin that pings you on Slack, Discord, email, WhatsApp, desktop voice or web push when a run finishes or needs you.

*2026-10-19T12:49:01Z*

# Claude Code Notifications: Get Pinged on Slack, Discord, WhatsApp or Voice

Claude Code notifications are the missing piece of a long run. You start a big task, switch to something else, and have no idea whether it finished twenty minutes ago or has been waiting on your answer the whole time.

**Claude Notifications** is an open-source Claude Code plugin that fixes this. It listens to Claude Code's hook events and sends them to the channels you choose: Slack, Discord, email, WhatsApp, a desktop banner with an optional spoken line, web push, or any webhook you own.

![Claude Code notifications: article cover](https://notifications.fadymondy.com/uploads/sites/75fee555-861d-4fd2-a230-87330aba3018/media/claude-code-notifications-launch-en.png)

## The problem

Long Claude Code runs have two quiet failure modes:

- It **finished**, and you didn't notice.
- It **stopped to ask you something**, and nothing happened until you looked back at the terminal.

The second one costs the most. The run isn't broken. It is just waiting for you, and the clock keeps running.

## How it works

Claude Code has [hooks](https://docs.claude.com/en/docs/claude-code/hooks): commands it runs at lifecycle events. The plugin registers a hook for each event in `hooks/hooks.json`. Every hook calls one script, `scripts/notify.sh <event>`, which:

1. reads the hook's JSON from stdin and turns it into a title and body;
2. works out which channels apply to that event;
3. runs every enabled channel in parallel, each time-bound to 5 seconds;
4. logs the result and exits 0, so a slow or broken channel never blocks Claude.

The events you can route are `notification`, `stop`, `subagent-stop`, `session-start`, `session-end`, `user-prompt`, `pre-tool`, `post-tool` and `manual`. Most people only need two: `stop` (it finished) and `notification` (it needs you). The README warns that `pre-tool`, `post-tool` and `user-prompt` fire many times per turn, so leave them off unless you really want the noise.

![Know when it's done](https://notifications.fadymondy.com/uploads/sites/75fee555-861d-4fd2-a230-87330aba3018/media/claude-notifications-know-when-its-done-en.png)

![Know when it's stuck](https://notifications.fadymondy.com/uploads/sites/75fee555-861d-4fd2-a230-87330aba3018/media/claude-notifications-know-when-its-stuck-en.png)

## Channels

| Channel | What it does | Setup |
|---|---|---|
| `desktop` | Native banners on macOS, Linux and Windows, with optional spoken alerts | None |
| `slack` | Posts to a channel through an Incoming Webhook | Webhook URL |
| `discord` | Posts through a Discord webhook | Webhook URL |
| `email` | SMTP or `sendmail` | SMTP credentials |
| `whatsapp` | Via Twilio or CallMeBot | Twilio account or CallMeBot API key |
| `webpush` | Phone or web push via ntfy.sh, Pushover or your own VAPID server | ntfy topic, Pushover keys or a webhook |
| `webhook` | JSON POST to your endpoint, HMAC-signed | Your URL |

That is seven built-in handlers. You can add more: put a `.sh` file in `~/.claude-notifications/channels/` and the dispatcher uses it. The README shows the full contract (read env vars like `CN_TITLE` and `CN_BODY`, finish within 5 seconds, exit 0 if unconfigured).

![Pick your channels](https://notifications.fadymondy.com/uploads/sites/75fee555-861d-4fd2-a230-87330aba3018/media/claude-notifications-pick-your-channels-en.png)

## Getting started

Install (from the README):

```bash
git clone https://github.com/fadymondy/claude-notifications ~/.claude/plugins/claude-notifications
```

Then enable it in `~/.claude/settings.json`:

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

Restart Claude Code. The hooks register from `hooks/hooks.json`. The repo also ships a `marketplace.json`, so you can add it as a plugin marketplace if you prefer that route.

You need `bash` 3.2+, `jq` and `curl`. Desktop banners use `osascript` and `say` on macOS, `notify-send` and `spd-say` or `espeak` on Linux, and PowerShell on Windows.

### Slack in one block

Easiest path: run `/notify-setup slack` inside Claude Code. Or edit `~/.claude-notifications/config.json` yourself:

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

When Claude finishes (`stop`) or asks for input (`notification`), Slack pings. Keep real webhook URLs out of project files: the project-local `.claude-notifications.json` is for routing rules only, and every credential also accepts an environment variable such as `CN_SLACK_WEBHOOK_URL`.

### Add a voice line

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

On macOS, leaving `voice.name` empty uses your System Voice from Accessibility settings. `style` picks what is spoken: `title`, `body` or `both`.

### Slash commands, skills and an agent

- `/notify <title> | <body>` sends a notification now.
- `/notify-test [channel]` pings every enabled channel, or one.
- `/notify-setup [channel]` walks you through a channel.
- Three skills (`notify`, `notify-config`, `notify-channel`) and a `notification-manager` agent help you edit config, build a new channel or debug silence.

### Route events to channels

Two ways, and the top-level map wins:

```json
{ "events": { "stop": ["slack", "desktop"], "notification": ["desktop"] } }
```

## The optional tray app

There is also an Electron tray app for macOS, Windows and Linux. It lets you toggle channels from the menu, edit credentials in a form, send a test per channel, see the routing matrix and tail the live log. It reads and writes the same `config.json` as the bash dispatcher, so both stay in sync. Prebuilt installers are on the [Releases page](https://github.com/fadymondy/claude-notifications/releases), or build from the `app/` folder.

## Honest limits

- It only sees what Claude Code exposes through hooks. It can tell you a run stopped or needs attention, not what is happening inside the run.
- WhatsApp goes through Twilio or CallMeBot, so you need an account or key with one of them.
- Each channel call is cut off at 5 seconds, so a very slow webhook can be dropped. Failures go to `~/.claude-notifications/logs/notify.log` instead of blocking you.
- Noisy events (`pre-tool`, `post-tool`, `user-prompt`) will flood a channel if you enable them.

## Debugging silence

```bash
tail -f ~/.claude-notifications/logs/notify.log
```

The log shows which event fired, which channels matched and which failed. The usual causes: the channel's `events` array doesn't include the event, a Slack or Discord webhook returns 404, macOS has banners blocked for Terminal, or `voice.enabled` is missing. `claude --debug hooks` confirms Claude Code sees the hook bindings.

## FAQ

**How do I get a notification when Claude Code finishes?** Claude Code fires a Stop hook when it finishes responding. The plugin listens to it and sends the `stop` event to the channels you enabled.

**How do I know when Claude Code is waiting for my input?** Route the `notification` event to a channel. That hook fires when Claude Code needs your attention.

**Does it work on Windows, macOS and Linux?** Yes. The tray app builds for all three, and desktop banners use each system's native mechanism. The bash dispatcher needs bash, `jq` and `curl`.

**Is it free?** It is open source under the MIT license.

**Can I add a channel that isn't built in?** Yes. Drop a bash script in `~/.claude-notifications/channels/`, or run `/notify-channel build me a Telegram channel` and let the agent scaffold it.

## Next steps

- Read why I built it: [Why I built Claude Notifications](https://fadymondy.com/en/blog/why-i-built-claude-notifications).
- Star or fork the code on [GitHub](https://github.com/fadymondy/claude-notifications).
- See the launch on [Product Hunt](https://www.producthunt.com/products/claude-notifications).
- Product site: [notifications.fadymondy.com](https://notifications.fadymondy.com).

---

Source: https://notifications.fadymondy.com/en/blog/claude-code-notifications-slack-discord-whatsapp-voice