claude-notification-plugin 1.0.63 → 1.0.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +259 -196
  3. package/package.json +1 -1
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-notification-plugin",
3
- "version": "1.0.63",
3
+ "version": "1.0.66",
4
4
  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
5
5
  "author": {
6
6
  "name": "Viacheslav Makarov",
package/README.md CHANGED
@@ -1,196 +1,259 @@
1
- # claude-notification-plugin
2
-
3
- Cross-platform notifications for Claude Code task completion. Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
4
-
5
- ## Features
6
-
7
- - Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send)
8
- - Telegram bot messages with auto-delete
9
- - Sound alert
10
- - Voice announcement
11
- - Separate notifications for task completion and waiting-for-input events
12
- - Skips short tasks (< 15s by default)
13
- - Granular per-channel enable/disable (globally and per-project)
14
- - Debug mode with full hook event dump
15
- - [Telegram Listener](LISTENER.md) — your remote control for Claude: send a message in Telegram, and the task starts running on your PC
16
-
17
- ## Install
18
-
19
- ### Option A: Claude Code Plugin (recommended)
20
-
21
- Auto-updates, seamless integration with the plugin ecosystem.
22
-
23
- ```shell
24
- /plugin marketplace add Bazilio-san/claude-plugins
25
- /plugin install claude-notification-plugin@bazilio-plugins
26
- /reload-plugins
27
- /claude-notification-plugin:setup
28
- ```
29
-
30
- Go to `/plugin` → **Marketplaces** tab → select `bazilio-plugins` → **Enable auto-update**.
31
-
32
- For a detailed visual walkthrough, see [step-by-step installation guide with screenshots](INSTALL_MARKETPLACE_AND_PLUGIN.md).
33
-
34
-
35
- ### Option B: npm global package
36
-
37
- Simple install, works without the plugin system.
38
-
39
- ```bash
40
- npm install -g claude-notification-plugin
41
- claude-notify-install
42
- ```
43
-
44
- The installer will:
45
- 1. Ask for Telegram bot credentials (or keep existing ones on re-run)
46
- 2. Create/update config at `~/.claude/notifier.config.json`
47
- 3. Register hooks in `~/.claude/settings.json`
48
-
49
- Re-running `claude-notify-install` after an update merges new config options without overwriting your existing settings.
50
-
51
- ## Configuration
52
-
53
- Config file: `~/.claude/notifier.config.json`
54
-
55
- ```json
56
- {
57
- "telegram": {
58
- "enabled": true,
59
- "token": "YOUR_BOT_TOKEN",
60
- "chatId": "YOUR_CHAT_ID",
61
- "deleteAfterHours": 24,
62
- "includeLastCcMessageInTelegram": true
63
- },
64
- "desktopNotification": {
65
- "enabled": true
66
- },
67
- "sound": {
68
- "enabled": true,
69
- "file": ""
70
- },
71
- "voice": {
72
- "enabled": true
73
- },
74
- "webhookUrl": "",
75
- "sendUserPromptToWebhook": false,
76
- "minSeconds": 15,
77
- "notifyOnWaiting": false,
78
- "debug": false
79
- }
80
- ```
81
-
82
- Each channel has an `enabled` flag (`true`/`false`) for global control. Environment variables override config values (`"1"` = on, `"0"` = off, or a string for URLs).
83
-
84
- | Config option | Env var override | Default | Description |
85
- |---|---|---|---|
86
- | `telegram.enabled` | `CLAUDE_NOTIFY_TELEGRAM` | `true` | Telegram messages |
87
- | `telegram.token` | `CLAUDE_NOTIFY_TELEGRAM_TOKEN` | — | Bot token |
88
- | `telegram.chatId` | `CLAUDE_NOTIFY_TELEGRAM_CHAT_ID` | — | Chat ID |
89
- | `telegram.deleteAfterHours` | — | `24` | Auto-delete old messages (hours, `0` to disable) |
90
- | `telegram.includeLastCcMessageInTelegram` | `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM` | `true` | Append Claude's last message to Telegram notification (truncated to 3500 chars) |
91
- | `desktopNotification.enabled` | `CLAUDE_NOTIFY_DESKTOP` | `true` | Desktop notifications (toast / Notification Center / notify-send) |
92
- | `sound.enabled` | `CLAUDE_NOTIFY_SOUND` | `true` | Sound alert |
93
- | `sound.file` | — | platform default | Path to a custom sound file |
94
- | `voice.enabled` | `CLAUDE_NOTIFY_VOICE` | `true` | Voice announcement (TTS) |
95
- | `notifyOnWaiting` | `CLAUDE_NOTIFY_WAITING` | `false` | Notify when Claude is waiting for input (e.g. permission prompts) |
96
- | `webhookUrl` | `CLAUDE_NOTIFY_WEBHOOK_URL` | `""` | POST notification data (JSON) to this URL. Payload: `title`, `project`, `branch`, `duration`, `trigger`, `voicePhrase`, `hookEvent` |
97
- | `sendUserPromptToWebhook` | `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK` | `false` | Also send user prompts to the webhook. Payload: `title`, `project`, `trigger`, `prompt`, `hookEvent` |
98
- | `minSeconds` | — | `15` | Skip notifications for tasks shorter than this (seconds) |
99
- | `debug` | `CLAUDE_NOTIFY_DEBUG` | `false` | Include voice phrase text and full hook event JSON in notifications |
100
- | — | `CLAUDE_NOTIFY_DISABLE` | `0` | Disable all notifications (`1` to disable) |
101
-
102
- Default sound files: Windows `C:/Windows/Media/notify.wav`, macOS `/System/Library/Sounds/Glass.aiff`, Linux `/usr/share/sounds/freedesktop/stereo/complete.oga`.
103
-
104
- ### Per-project configuration
105
-
106
- Add to `.claude/settings.local.json` in the project root to control channels per project:
107
-
108
- ```json
109
- {
110
- "env": {
111
- "CLAUDE_NOTIFY_DISABLE": 0,
112
- "CLAUDE_NOTIFY_TELEGRAM": 1,
113
- "CLAUDE_NOTIFY_DESKTOP": 1,
114
- "CLAUDE_NOTIFY_SOUND": 1,
115
- "CLAUDE_NOTIFY_VOICE": 1,
116
- "CLAUDE_NOTIFY_WAITING": 1,
117
- "CLAUDE_NOTIFY_DEBUG": 0,
118
- "CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM": 1,
119
- "CLAUDE_NOTIFY_WEBHOOK_URL": "",
120
- "CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK": 0
121
- }
122
- }
123
- ```
124
-
125
- To disable all notifications for a project:
126
-
127
- ```json
128
- {
129
- "env": {
130
- "CLAUDE_NOTIFY_DISABLE": "1"
131
- }
132
- }
133
- ```
134
-
135
- ## Notification format
136
-
137
- Notifications include project name, git branch (when available), duration, and the trigger event:
138
-
139
- ```
140
- 🤖 Claude finished coding
141
-
142
- Project: my-project
143
- Branch: feature-auth
144
- Duration: 45s
145
- ```
146
-
147
- When Claude is waiting for input (and `notifyOnWaiting` is enabled):
148
-
149
- ```
150
- 🤖 Claude waiting for input
151
-
152
- Project: my-project
153
- Branch: feature-auth
154
- Duration: 30s
155
- ```
156
-
157
- ## Telegram Setup
158
-
159
- 1. Open Telegram, find **@BotFather**
160
- 2. Send `/newbot`, follow prompts, pick a name
161
- 3. Copy the bot token (format: `123456789:ABCdef...`)
162
- 4. **Send any message to your new bot**
163
- 5. Open `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
164
- 6. Find `"chat":{"id":123456789}` in the response — that's your Chat ID
165
- 7. Run `claude-notify-install` and enter the token and chat ID
166
-
167
- Alternative for Chat ID: add **@userinfobot** to a chat and it will reply with the ID.
168
-
169
- ## Telegram Listener (Telegram → Claude Code)
170
-
171
- 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.
172
-
173
- ## Uninstall
174
-
175
- ### Plugin install
176
-
177
- Uninstall via the plugin manager or remove `--plugin-dir` flag.
178
-
179
- ### npm
180
-
181
- ```bash
182
- claude-notify-uninstall
183
- npm uninstall -g claude-notification-plugin
184
- ```
185
-
186
- ## Testing (load without install)
187
-
188
- ```bash
189
- claude --plugin-dir /path/to/claude-notification-plugin
190
- ```
191
-
192
- Hooks are registered automatically.
193
-
194
- ## License
195
-
196
- MIT
1
+ # claude-notification-plugin
2
+
3
+ Cross-platform notifications for Claude Code task completion. Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
4
+
5
+ ## Features
6
+
7
+ - Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send)
8
+ - Telegram bot messages with auto-delete
9
+ - Sound alert
10
+ - Voice announcement
11
+ - Separate notifications for task completion and waiting-for-input events
12
+ - Skips short tasks (< 15s by default)
13
+ - Granular per-channel enable/disable (globally and per-project)
14
+ - Debug mode with full hook event dump
15
+ - **[Telegram Listener](LISTENER.md)** — your remote control for Claude: send a message in Telegram, and the task starts running on your PC
16
+
17
+ ## Install
18
+
19
+ ### Option A: Claude Code Plugin (recommended)
20
+
21
+ Auto-updates, seamless integration with the plugin ecosystem.
22
+
23
+ ```shell
24
+ /plugin marketplace add Bazilio-san/claude-plugins
25
+ /plugin install claude-notification-plugin@bazilio-plugins
26
+ /reload-plugins
27
+ /claude-notification-plugin:setup
28
+ ```
29
+
30
+ Go to `/plugin` → **Marketplaces** tab → select `bazilio-plugins` → **Enable auto-update**.
31
+
32
+ For a detailed visual walkthrough, see [step-by-step installation guide with screenshots](INSTALL_MARKETPLACE_AND_PLUGIN.md).
33
+
34
+
35
+ ### Option B: npm global package
36
+
37
+ Simple install, works without the plugin system.
38
+
39
+ ```bash
40
+ npm install -g claude-notification-plugin
41
+ claude-notify-install
42
+ ```
43
+
44
+ The installer will:
45
+ 1. Ask for Telegram bot credentials (or keep existing ones on re-run)
46
+ 2. Create/update config at `~/.claude/notifier.config.json`
47
+ 3. Register hooks in `~/.claude/settings.json`
48
+
49
+ Re-running `claude-notify-install` after an update merges new config options without overwriting your existing settings.
50
+
51
+ ## Configuration
52
+
53
+ Config file: `~/.claude/notifier.config.json`
54
+
55
+ ```json
56
+ {
57
+ "telegram": {
58
+ "enabled": true,
59
+ "token": "YOUR_BOT_TOKEN",
60
+ "chatId": "YOUR_CHAT_ID",
61
+ "deleteAfterHours": 24,
62
+ "includeLastCcMessageInTelegram": true
63
+ },
64
+ "desktopNotification": {
65
+ "enabled": true
66
+ },
67
+ "sound": {
68
+ "enabled": true,
69
+ "file": ""
70
+ },
71
+ "voice": {
72
+ "enabled": true
73
+ },
74
+ "webhookUrl": "",
75
+ "sendUserPromptToWebhook": false,
76
+ "minSeconds": 15,
77
+ "notifyOnWaiting": false,
78
+ "debug": false
79
+ }
80
+ ```
81
+
82
+ Environment variables override config values (`"1"` = on, `"0"` = off).
83
+
84
+
85
+ **telegram.enabled**
86
+ Enable Telegram messages.
87
+ Default: **true**
88
+ ENV: `CLAUDE_NOTIFY_TELEGRAM`
89
+
90
+
91
+ **telegram.token**
92
+ Bot token from @BotFather.
93
+ ENV: `CLAUDE_NOTIFY_TELEGRAM_TOKEN`
94
+
95
+
96
+ **telegram.chatId**
97
+ Chat ID to send messages to.
98
+ ENV: `CLAUDE_NOTIFY_TELEGRAM_CHAT_ID`
99
+
100
+
101
+ **telegram.deleteAfterHours**
102
+ Auto-delete old Telegram messages after the specified number of hours. Set `0` to disable.
103
+ Default: **24**
104
+
105
+
106
+ **telegram.includeLastCcMessageInTelegram**
107
+ Append Claude's last assistant message to the Telegram notification. Long messages are truncated to 3500 characters.
108
+ Default: **true**
109
+ ENV: `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM`
110
+
111
+
112
+ **desktopNotification.enabled**
113
+ Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send).
114
+ Default: **true**
115
+ ENV: `CLAUDE_NOTIFY_DESKTOP`
116
+
117
+
118
+ **sound.enabled**
119
+ Sound alert on task completion.
120
+ Default: **true**
121
+ ENV: `CLAUDE_NOTIFY_SOUND`
122
+
123
+
124
+ **sound.file**
125
+ 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`.
126
+ Default: **platform default**
127
+
128
+
129
+ **voice.enabled**
130
+ Voice announcement (TTS) with duration in words.
131
+ Default: **true**
132
+ ENV: `CLAUDE_NOTIFY_VOICE`
133
+
134
+
135
+ **notifyOnWaiting**
136
+ Send notifications when Claude is waiting for user input (e.g. permission prompts).
137
+ Default: **false**
138
+ ENV: `CLAUDE_NOTIFY_WAITING`
139
+
140
+
141
+ **webhookUrl**
142
+ POST notification data (JSON) to this URL. Payload: `title`, `project`, `branch`, `duration`, `trigger`, `voicePhrase`, `hookEvent`.
143
+ ENV: `CLAUDE_NOTIFY_WEBHOOK_URL`
144
+
145
+
146
+ **sendUserPromptToWebhook**
147
+ Also send user prompts to the webhook. Payload: `title`, `project`, `trigger`, `prompt`, `hookEvent`. Requires `webhookUrl`.
148
+ Default: **false**
149
+ ENV: `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK`
150
+
151
+
152
+ **minSeconds**
153
+ Skip notifications for tasks shorter than this (seconds).
154
+ Default: **15**
155
+
156
+
157
+ **debug**
158
+ Include trigger event type, voice phrase text, and full hook event JSON in notifications.
159
+ Default: **false**
160
+ ENV: `CLAUDE_NOTIFY_DEBUG`
161
+
162
+
163
+ ENV: **CLAUDE_NOTIFY_DISABLE**
164
+ Set to `1` to disable all notifications for the current project.
165
+ Default: **0**
166
+
167
+ ### Per-project configuration
168
+
169
+ Add to `.claude/settings.local.json` in the project root to control channels per project:
170
+
171
+ ```json
172
+ {
173
+ "env": {
174
+ "CLAUDE_NOTIFY_DISABLE": 0,
175
+ "CLAUDE_NOTIFY_TELEGRAM": 1,
176
+ "CLAUDE_NOTIFY_DESKTOP": 1,
177
+ "CLAUDE_NOTIFY_SOUND": 1,
178
+ "CLAUDE_NOTIFY_VOICE": 1,
179
+ "CLAUDE_NOTIFY_WAITING": 1,
180
+ "CLAUDE_NOTIFY_DEBUG": 0,
181
+ "CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM": 1,
182
+ "CLAUDE_NOTIFY_WEBHOOK_URL": "",
183
+ "CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK": 0
184
+ }
185
+ }
186
+ ```
187
+
188
+ To disable all notifications for a project:
189
+
190
+ ```json
191
+ {
192
+ "env": {
193
+ "CLAUDE_NOTIFY_DISABLE": "1"
194
+ }
195
+ }
196
+ ```
197
+
198
+ ## Notification format
199
+
200
+ Notifications include project name, git branch (when available), duration, and the trigger event:
201
+
202
+ ```
203
+ 🤖 Claude finished coding
204
+
205
+ Project: my-project
206
+ Branch: feature-auth
207
+ Duration: 45s
208
+ ```
209
+
210
+ When Claude is waiting for input (and `notifyOnWaiting` is enabled):
211
+
212
+ ```
213
+ 🤖 Claude waiting for input
214
+
215
+ Project: my-project
216
+ Branch: feature-auth
217
+ Duration: 30s
218
+ ```
219
+
220
+ ## Telegram Setup
221
+
222
+ 1. Open Telegram, find **@BotFather**
223
+ 2. Send `/newbot`, follow prompts, pick a name
224
+ 3. Copy the bot token (format: `123456789:ABCdef...`)
225
+ 4. **Send any message to your new bot**
226
+ 5. Open `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
227
+ 6. Find `"chat":{"id":123456789}` in the response — that's your Chat ID
228
+ 7. Run `claude-notify-install` and enter the token and chat ID
229
+
230
+ Alternative for Chat ID: add **@userinfobot** to a chat and it will reply with the ID.
231
+
232
+ ## Telegram Listener (Telegram → Claude Code)
233
+
234
+ 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.
235
+
236
+ ## Testing (load without install)
237
+
238
+ ```bash
239
+ claude --plugin-dir /path/to/claude-notification-plugin
240
+ ```
241
+
242
+ ## Uninstall
243
+
244
+ ### Plugin install
245
+
246
+ Uninstall via the plugin manager or remove `--plugin-dir` flag.
247
+
248
+ ### npm
249
+
250
+ ```bash
251
+ claude-notify-uninstall
252
+ npm uninstall -g claude-notification-plugin
253
+ ```
254
+
255
+ Hooks are registered automatically.
256
+
257
+ ## License
258
+
259
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "claude-notification-plugin",
3
3
  "productName": "claude-notification-plugin",
4
- "version": "1.0.63",
4
+ "version": "1.0.66",
5
5
  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
6
6
  "type": "module",
7
7
  "engines": {