claude-notification-plugin 1.0.59 → 1.0.65

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-notification-plugin",
-  "version": "1.0.59",
+  "version": "1.0.65",
   "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
   "author": {
     "name": "Viacheslav Makarov",

package/README.md

@@ -1,208 +1,261 @@
-# 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:
-
-```shell
-/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](INSTALL_MARKETPLACE_AND_PLUGIN.md).
-
-Or load directly for testing:
-
-```bash
-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:
-
-```shell
-/claude-notification-plugin:setup
-```
-
-### Option B: npm global package
-
-```bash
-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`
-
-```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,
-  "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).
-
-`webhookUrl` — URL to send a POST request with full notification data (JSON). If empty, no request is sent. On `Stop`/`Notification` events the payload includes `title`, `project`, `branch`, `duration`, `trigger`, `voicePhrase`, and `hookEvent` (the raw hook input). Useful for integrating with custom dashboards, logging services, or automation pipelines.
-
-`sendUserPromptToWebhook` — also send user prompts to the webhook URL (default: `false`). When enabled, each `UserPromptSubmit` event sends a POST with `title`, `project`, `trigger`, `prompt` (user's message text), and `hookEvent`. Requires `webhookUrl` to be set.
-
-`debug` — include extra info in notifications: voice phrase text, full hook event JSON (formatted as code block in Telegram). Default: `false`.
-
-Environment variables `CLAUDE_NOTIFY_TELEGRAM_TOKEN` and `CLAUDE_NOTIFY_TELEGRAM_CHAT_ID` override config file values.
-
-### Per-channel environment variables
-
-These env vars override the global config per channel (`"1"` = on, `"0"` = off):
-
-| Variable                                              | Channel                                 |
-|-------------------------------------------------------|-----------------------------------------|
-| `CLAUDE_NOTIFY_TELEGRAM`                              | Telegram messages                       |
-| `CLAUDE_NOTIFY_DESKTOP`                               | Desktop notifications                   |
-| `CLAUDE_NOTIFY_SOUND`                                 | Sound alert                             |
-| `CLAUDE_NOTIFY_VOICE`                                 | Voice announcement (TTS)                |
-| `CLAUDE_NOTIFY_WAITING`                               | Waiting-for-input events                |
-| `CLAUDE_NOTIFY_DEBUG`                                 | Debug mode                              |
-| `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM`   | Include last Claude message in Telegram |
-| `CLAUDE_NOTIFY_WEBHOOK_URL`                           | Webhook URL for POST requests           |
-| `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK`           | Send user prompts to webhook            |
-
-### Per-project configuration
-
-Add to `.claude/settings.local.json` in the project root to control channels per project:
-
-```json
-{
-  "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
-  }
-}
-```
-
-To disable all notifications for a project:
-
-```json
-{
-  "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
-Trigger: Stop
-```
-
-When Claude is waiting for input (and `notifyOnWaiting` is enabled):
-
-```
-🤖 Claude waiting for input
-
-Project: my-project
-Branch: feature-auth
-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
-
-```bash
-claude-notify-uninstall
-npm uninstall -g claude-notification-plugin
-```
-
-## License
-
-MIT
+# 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](LISTENER.md)** — 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.
+
+```shell
+/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](INSTALL_MARKETPLACE_AND_PLUGIN.md).
+
+
+### Option B: npm global package
+
+Simple install, works without the plugin system.
+
+```bash
+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`
+
+```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,
+  "minSeconds": 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`  
+
+
+**minSeconds**  
+Skip notifications for tasks shorter than this (seconds).  
+Default: **15**  
+
+
+**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**
+
+### Per-project configuration
+
+Add to `.claude/settings.local.json` in the project root to control channels per project:
+
+```json
+{
+  "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
+  }
+}
+```
+
+To disable all notifications for a project:
+
+```json
+{
+  "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](LISTENER.md)** for the full guide.
+
+## Testing (load without install)
+
+```bash
+claude --plugin-dir /path/to/claude-notification-plugin
+```
+
+## Uninstall
+
+### Plugin install
+
+Uninstall via the plugin manager or remove `--plugin-dir` flag.
+
+### npm
+
+```bash
+claude-notify-uninstall
+npm uninstall -g claude-notification-plugin
+```
+
+Hooks are registered automatically.
+
+## License
+
+MIT