claude-notification-plugin

Cross-platform notifications for Claude Code task completion. Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.

Features

• Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send)
• Telegram bot messages with auto-delete
• Sound alert (Windows: PowerShell, macOS: afplay, Linux: paplay/aplay)
• Voice announcement with number-to-words and pluralization (EN, RU) (Windows: SAPI, macOS: say, Linux: spd-say/espeak)
• Separate notifications for task completion and waiting-for-input events
• Skips short tasks (< 15s by default)
• Granular per-channel enable/disable (globally and per-project)
• Debug mode with full hook event dump

Install

Option A: Claude Code Plugin (recommended)

Add the marketplace and install:

/plugin marketplace add Bazilio-san/claude-plugins
/plugin install claude-notification-plugin@bazilio-plugins
/reload-plugins
/claude-notification-plugin:setup

For a detailed visual walkthrough, see step-by-step installation guide with screenshots.

Or load directly for testing:

claude --plugin-dir /path/to/claude-notification-plugin

Hooks are registered automatically.

To enable auto-updates, go to /plugin → Marketplaces tab → select bazilio-plugins → Enable auto-update.

To configure Telegram credentials, run:

/claude-notification-plugin:setup

Option B: npm global package

npm install -g claude-notification-plugin
claude-notify-install

The installer will:

1. Ask for Telegram bot credentials (or keep existing ones on re-run)
2. Create/update config at ~/.claude/notifier.config.json
3. Register hooks in ~/.claude/settings.json

Re-running claude-notify-install after an update merges new config options without overwriting your existing settings.

Configuration

Config file: ~/.claude/notifier.config.json

{
  "telegram": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "chatId": "YOUR_CHAT_ID",
    "deleteAfterHours": 24,
    "includeLastCcMessageInTelegram": true
  },
  "desktopNotification": {
    "enabled": true
  },
  "sound": {
    "enabled": true,
    "file": ""
  },
  "voice": {
    "enabled": true
  },
  "minSeconds": 15,
  "notifyOnWaiting": false,
  "debug": false
}

Each channel has an enabled flag (true/false) for global control.

sound.file — path to a sound file. Leave empty for platform default (Windows: C:/Windows/Media/notify.wav, macOS: /System/Library/Sounds/Glass.aiff, Linux: /usr/share/sounds/freedesktop/stereo/complete.oga).

deleteAfterHours — auto-delete old Telegram messages after the specified number of hours (default: 24, set 0 to disable).

includeLastCcMessageInTelegram — append Claude's last assistant message to the Telegram notification (default: true). Only affects Telegram, not Windows toast notifications. Long messages are truncated to 3500 characters.

notifyOnWaiting — send notifications when Claude is waiting for user input, e.g. permission prompts (default: false, set true to enable).

debug — include extra info in notifications: voice phrase text, full hook event JSON (formatted as code block in Telegram). Default: false.

Environment variables TELEGRAM_TOKEN and TELEGRAM_CHAT_ID override config file values.

Per-channel environment variables

These env vars override the global config per channel ("1" = on, "0" = off):

Per-project configuration

Add to .claude/settings.local.json in the project root to control channels per project:

{
  "env": {
    "DISABLE_CLAUDE_NOTIFIER": 0,
    "CLAUDE_NOTIFY_TELEGRAM": 1,
    "CLAUDE_NOTIFY_DESKTOP": 1,
    "CLAUDE_NOTIFY_SOUND": 1,
    "CLAUDE_NOTIFY_VOICE": 1,
    "CLAUDE_NOTIFY_WAITING": 1,
    "CLAUDE_NOTIFY_DEBUG": 0,
    "CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM": 1
  }
}

To disable all notifications for a project:

{
  "env": {
    "DISABLE_CLAUDE_NOTIFIER": "1"
  }
}

Notification format

Notifications include project name, duration, and the trigger event:

🤖 Claude finished coding

Project: my-project
Duration: 45s
Trigger: Stop

When Claude is waiting for input (and notifyOnWaiting is enabled):

🤖 Claude waiting for input

Project: my-project
Duration: 30s
Trigger: Notification

Telegram Setup

1. Open Telegram, find @BotFather
2. Send /newbot, follow prompts, pick a name
3. Copy the bot token (format: 123456789:ABCdef...)
4. Send any message to your new bot
5. Open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
6. Find "chat":{"id":123456789} in the response — that's your Chat ID
7. Run claude-notify-install and enter the token and chat ID

Alternative for Chat ID: add @userinfobot to a chat and it will reply with the ID.

Uninstall

Plugin install

Uninstall via the plugin manager or remove --plugin-dir flag.

npm install

claude-notify-uninstall
npm uninstall -g claude-notification-plugin

License

MIT