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
• Voice announcement
• 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
• Telegram Listener — your remote control for Claude: send a message in Telegram, and the task starts running on your PC

Install

Option A: Claude Code Plugin (recommended)

Auto-updates, seamless integration with the plugin ecosystem.

These commands are run in the Claude Code terminal:

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

Go to /plugin → Marketplaces tab → select bazilio-plugins → Enable auto-update.

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

Option B: npm global package

Simple install, works without the plugin system.

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
  },
  "webhookUrl": "",
  "sendUserPromptToWebhook": false,
  "notifyAfterSeconds": 15,
  "notifyOnWaiting": false,
  "debug": false
}

Environment variables override config values ("1" = on, "0" = off).

telegram.enabled
Enable Telegram messages.
Default: true
ENV: CLAUDE_NOTIFY_TELEGRAM

telegram.token
Bot token from @BotFather.
ENV: CLAUDE_NOTIFY_TELEGRAM_TOKEN

telegram.chatId
Chat ID to send messages to.
ENV: CLAUDE_NOTIFY_TELEGRAM_CHAT_ID

telegram.deleteAfterHours
Auto-delete old Telegram messages after the specified number of hours. Set 0 to disable.
Default: 24

telegram.includeLastCcMessageInTelegram
Append Claude's last assistant message to the Telegram notification. Long messages are truncated to 3500 characters.
Default: true
ENV: CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM

desktopNotification.enabled
Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send).
Default: true
ENV: CLAUDE_NOTIFY_DESKTOP

sound.enabled
Sound alert on task completion.
Default: true
ENV: CLAUDE_NOTIFY_SOUND

sound.file
Path to a custom sound file. Platform defaults: Windows C:/Windows/Media/notify.wav, macOS /System/Library/Sounds/Glass.aiff, Linux /usr/share/sounds/freedesktop/stereo/complete.oga.
Default: platform default

voice.enabled
Voice announcement (TTS) with duration in words.
Default: true
ENV: CLAUDE_NOTIFY_VOICE

notifyOnWaiting
Send notifications when Claude is waiting for user input (e.g. permission prompts).
Default: false
ENV: CLAUDE_NOTIFY_WAITING

webhookUrl
POST notification data (JSON) to this URL. Payload: title, project, branch, duration, trigger, voicePhrase, hookEvent.
ENV: CLAUDE_NOTIFY_WEBHOOK_URL

sendUserPromptToWebhook
Also send user prompts to the webhook. Payload: title, project, trigger, prompt, hookEvent. Requires webhookUrl.
Default: false
ENV: CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK

notifyAfterSeconds
Skip notifications for tasks shorter than this (seconds).
Default: 15
ENV: CLAUDE_NOTIFY_AFTER_SECONDS

debug
Include trigger event type, voice phrase text, and full hook event JSON in notifications.
Default: false
ENV: CLAUDE_NOTIFY_DEBUG

ENV: CLAUDE_NOTIFY_DISABLE
Set to 1 to disable all notifications for the current project.
Default: 0

ENV: CLAUDE_NOTIFY_AFTER_LISTENER
When a task is started by the Telegram Listener, notifications are suppressed by default to avoid duplicates (the listener sends its own status messages). Set to 1 to enable notifier notifications for listener-spawned tasks.
Default: 0

Per-project configuration

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

{
  "env": {
    "CLAUDE_NOTIFY_DISABLE": 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,
    "CLAUDE_NOTIFY_WEBHOOK_URL": "",
    "CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK": 0,
    "CLAUDE_NOTIFY_AFTER_SECONDS": 15
  }
}

To disable all notifications for a project:

{
  "env": {
    "CLAUDE_NOTIFY_DISABLE": "1"
  }
}

Notification format

Notifications include project name, git branch (when available), duration, and the trigger event:

🤖 Claude finished coding

Project: my-project
Branch: feature-auth
Duration: 45s

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

🤖 Claude waiting for input

Project: my-project
Branch: feature-auth
Duration: 30s

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.

Telegram Listener (Telegram → Claude Code)

Your remote control for Claude: send a message in Telegram, and the task starts running on your PC. See LISTENER.md for the full guide.

When installed as a plugin, you can manage the listener daemon directly from Claude Code with the /listener slash command. These commands are run in the Claude Code terminal: /claude-notification-plugin:listener start | stop | status | logs | restart

CLI Commands Registration

When installed as a plugin, CLI commands (claude-notify-listener, etc.) are not in PATH. The /claude-notification-plugin:setup command registers them automatically by placing wrapper scripts next to the claude binary.

To manage manually:

claude-notify-register            # register CLI commands
claude-notify-register list       # show registration status
claude-notify-register unregister # remove CLI commands

When installed via npm install -g, npm links the commands itself — no extra step needed.

Testing (load without install)

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

Uninstall

Plugin install

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

npm

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

Hooks are registered automatically.

License

MIT