claude-notification-plugin 1.0.63 → 1.0.65

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