claude-notification-plugin 1.0.44 → 1.0.49

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-notification-plugin",
-  "version": "1.0.44",
+  "version": "1.0.49",
   "description": "Claude Code notifications щт task completion: Telegram, Windows toast, sound, and voice",
   "author": {
     "name": "Viacheslav Makarov",

package/README.md

@@ -1,13 +1,13 @@
 # claude-notification-plugin
 
-Notifications for Claude Code task completion. Sends alerts to Telegram and Windows when Claude finishes working.
+Cross-platform notifications for Claude Code task completion. Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
 
 ## Features
 
-- Windows desktop notifications (toast)
+- Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send)
 - Telegram bot messages with auto-delete
-- Sound alert (hidden PowerShell, no popup windows)
-- Voice announcement with number-to-words and pluralization (EN, RU)
+- 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)
@@ -22,8 +22,12 @@ 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
@@ -67,12 +71,12 @@ Config file: `~/.claude/notifier.config.json`
     "deleteAfterHours": 24,
     "includeLastCcMessageInTelegram": true
   },
-  "windowsNotification": {
+  "desktopNotification": {
     "enabled": true
   },
   "sound": {
     "enabled": true,
-    "file": "C:/Windows/Media/notify.wav"
+    "file": ""
   },
   "voice": {
     "enabled": true
@@ -85,6 +89,8 @@ Config file: `~/.claude/notifier.config.json`
 
 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.
@@ -102,7 +108,7 @@ These env vars override the global config per channel (`"1"` = on, `"0"` = off):
 | Variable                 | Channel                    |
 |--------------------------|----------------------------|
 | `CLAUDE_NOTIFY_TELEGRAM` | Telegram messages          |
-| `CLAUDE_NOTIFY_WINDOWS`  | Windows toast notifications|
+| `CLAUDE_NOTIFY_DESKTOP`  | Desktop notifications      |
 | `CLAUDE_NOTIFY_SOUND`    | Sound alert                |
 | `CLAUDE_NOTIFY_VOICE`    | Voice announcement (TTS)   |
 | `CLAUDE_NOTIFY_WAITING`  | Waiting-for-input events   |
@@ -118,7 +124,7 @@ Add to `.claude/settings.local.json` in the project root to control channels per
   "env": {
     "DISABLE_CLAUDE_NOTIFIER": 0,
     "CLAUDE_NOTIFY_TELEGRAM": 1,
-    "CLAUDE_NOTIFY_WINDOWS": 1,
+    "CLAUDE_NOTIFY_DESKTOP": 1,
     "CLAUDE_NOTIFY_SOUND": 1,
     "CLAUDE_NOTIFY_VOICE": 1,
     "CLAUDE_NOTIFY_WAITING": 1,

package/bin/install.js

@@ -136,6 +136,14 @@ async function main () {
   // Create / update config
   fs.mkdirSync(claudeDir, { recursive: true });
 
+  const platform = process.platform;
+  let defaultSoundFile;
+  switch (platform) {
+    case 'darwin': defaultSoundFile = '/System/Library/Sounds/Glass.aiff'; break;
+    case 'linux': defaultSoundFile = '/usr/share/sounds/freedesktop/stereo/complete.oga'; break;
+    default: defaultSoundFile = 'C:/Windows/Media/notify.wav';
+  }
+
   const defaults = {
     telegram: {
       enabled: true,
@@ -143,12 +151,12 @@ async function main () {
       chatId: '',
       deleteAfterHours: 24,
     },
-    windowsNotification: {
+    desktopNotification: {
       enabled: true,
     },
     sound: {
       enabled: true,
-      file: 'C:/Windows/Media/notify.wav',
+      file: defaultSoundFile,
     },
     voice: {
       enabled: true,
@@ -213,6 +221,18 @@ async function main () {
     console.log('Telegram: not configured (edit config later)');
   }
 
+  if (platform === 'darwin') {
+    console.log('');
+    console.log('Tip: install terminal-notifier for better macOS notifications:');
+    console.log('  brew install terminal-notifier');
+  }
+
+  if (platform === 'linux') {
+    console.log('');
+    console.log('Tip: for voice announcements, install espeak:');
+    console.log('  sudo apt install espeak');
+  }
+
   console.log('');
   console.log('To disable per project, add to .claude/settings.local.json:');
   console.log('  { "env": { "DISABLE_CLAUDE_NOTIFIER": "1" } }');

package/notifier/notifier.js

@@ -10,6 +10,22 @@ import { spawn } from 'child_process';
 // CONFIG
 // ----------------------
 
+const PLATFORM = process.platform; // 'win32' | 'darwin' | 'linux'
+
+function getDefaultSoundFile () {
+  switch (PLATFORM) {
+    case 'darwin': return '/System/Library/Sounds/Glass.aiff';
+    case 'linux': return '/usr/share/sounds/freedesktop/stereo/complete.oga';
+    default: return 'C:/Windows/Media/notify.wav';
+  }
+}
+
+function debugLog (config, ...args) {
+  if (config.debug) {
+    console.error('[claude-notifier]', ...args);
+  }
+}
+
 function loadConfig () {
   const configPath = path.join(os.homedir(), '.claude', 'notifier.config.json');
 
@@ -21,12 +37,12 @@ function loadConfig () {
       deleteAfterHours: 24,
       includeLastCcMessageInTelegram: true,
     },
-    windowsNotification: {
+    desktopNotification: {
       enabled: true,
     },
     sound: {
       enabled: true,
-      file: 'C:/Windows/Media/notify.wav',
+      file: getDefaultSoundFile(),
     },
     voice: {
       enabled: true,
@@ -43,8 +59,8 @@ function loadConfig () {
       if (user.telegram) {
         config.telegram = { ...config.telegram, ...user.telegram };
       }
-      if (user.windowsNotification) {
-        config.windowsNotification = { ...config.windowsNotification, ...user.windowsNotification };
+      if (user.desktopNotification) {
+        config.desktopNotification = { ...config.desktopNotification, ...user.desktopNotification };
       }
       if (user.sound) {
         config.sound = { ...config.sound, ...user.sound };
@@ -77,8 +93,8 @@ function loadConfig () {
   if (process.env.CLAUDE_NOTIFY_TELEGRAM !== undefined) {
     config.telegram.enabled = process.env.CLAUDE_NOTIFY_TELEGRAM === '1';
   }
-  if (process.env.CLAUDE_NOTIFY_WINDOWS !== undefined) {
-    config.windowsNotification.enabled = process.env.CLAUDE_NOTIFY_WINDOWS === '1';
+  if (process.env.CLAUDE_NOTIFY_DESKTOP !== undefined) {
+    config.desktopNotification.enabled = process.env.CLAUDE_NOTIFY_DESKTOP === '1';
   }
   if (process.env.CLAUDE_NOTIFY_SOUND !== undefined) {
     config.sound.enabled = process.env.CLAUDE_NOTIFY_SOUND === '1';
@@ -139,6 +155,57 @@ function saveState (state) {
 // TELEGRAM
 // ----------------------
 
+function escapeHtml (text) {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function markdownToTelegramHtml (md) {
+  const codeBlocks = [];
+  const inlineCodes = [];
+
+  // Extract fenced code blocks
+  let result = md.replace(/```[\s\S]*?```/g, (m) => {
+    const idx = codeBlocks.length;
+    const inner = m.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    codeBlocks.push(`<pre>${escapeHtml(inner)}</pre>`);
+    return `\x00CB${idx}\x00`;
+  });
+
+  // Extract inline code
+  result = result.replace(/`([^`]+)`/g, (_, code) => {
+    const idx = inlineCodes.length;
+    inlineCodes.push(`<code>${escapeHtml(code)}</code>`);
+    return `\x00IC${idx}\x00`;
+  });
+
+  // Escape HTML in remaining text
+  result = escapeHtml(result);
+
+  // Headers → bold
+  result = result.replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>');
+
+  // Bold: **text**
+  result = result.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+
+  // Italic: *text* (but not inside words with asterisks)
+  result = result.replace(/(?<!\w)\*([^*]+?)\*(?!\w)/g, '<i>$1</i>');
+
+  // Strikethrough: ~~text~~
+  result = result.replace(/~~(.+?)~~/g, '<s>$1</s>');
+
+  // Links: [text](url)
+  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // Restore code blocks and inline codes
+  result = result.replace(/\x00CB(\d+)\x00/g, (_, i) => codeBlocks[i]);
+  result = result.replace(/\x00IC(\d+)\x00/g, (_, i) => inlineCodes[i]);
+
+  return result;
+}
+
 async function sendTelegram (config, state) {
   if (!config.telegram.enabled || !config.telegram.token || !config.telegram.chatId) {
     return;
@@ -152,7 +219,7 @@ async function sendTelegram (config, state) {
       chat_id: config.telegram.chatId,
       text: state._telegramText,
     };
-    body.parse_mode = 'Markdown';
+    body.parse_mode = 'HTML';
     const res = await fetch(`${baseUrl}/sendMessage`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -167,6 +234,26 @@ async function sendTelegram (config, state) {
         id: data.result.message_id,
         ts: Date.now(),
       });
+    } else if (!data.ok && body.parse_mode) {
+      // Retry without formatting if HTML parsing failed
+      const retryRes = await fetch(`${baseUrl}/sendMessage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          chat_id: body.chat_id,
+          text: body.text,
+        }),
+      });
+      const retryData = await retryRes.json();
+      if (retryData.ok && retryData.result?.message_id) {
+        if (!state.sentMessages) {
+          state.sentMessages = [];
+        }
+        state.sentMessages.push({
+          id: retryData.result.message_id,
+          ts: Date.now(),
+        });
+      }
     }
   } catch {
     // silent fail
@@ -200,11 +287,32 @@ async function sendTelegram (config, state) {
 }
 
 // ----------------------
-// WINDOWS NOTIFICATION
+// DESKTOP NOTIFICATION
 // ----------------------
 
-async function sendWindowsNotification (config, message) {
-  if (!config.windowsNotification.enabled) {
+function sendNativeFallback (config, message) {
+  try {
+    switch (PLATFORM) {
+      case 'darwin': {
+        const escaped = message.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        spawn('osascript', ['-e', `display notification "${escaped}" with title "Claude Code"`], {
+          stdio: 'ignore',
+        });
+        break;
+      }
+      case 'linux':
+        spawn('notify-send', ['Claude Code', message], {
+          stdio: 'ignore',
+        });
+        break;
+    }
+  } catch (err) {
+    debugLog(config, 'native notification fallback failed:', err.message);
+  }
+}
+
+async function sendDesktopNotification (config, message) {
+  if (!config.desktopNotification.enabled) {
     return;
   }
   try {
@@ -212,11 +320,12 @@ async function sendWindowsNotification (config, message) {
     notifier.notify({
       title: 'Claude Code',
       message,
-      sound: true,
+      sound: false,
       wait: false,
     });
-  } catch {
-    // node-notifier not available (e.g. plugin cache without node_modules)
+  } catch (err) {
+    debugLog(config, 'node-notifier failed, trying native fallback:', err.message);
+    sendNativeFallback(config, message);
   }
 }
 
@@ -228,15 +337,30 @@ function playSound (config) {
   if (!config.sound.enabled) {
     return;
   }
+  const file = config.sound.file;
   try {
-    const file = config.sound.file.replace(/'/g, "''");
-    const psCommand = `(New-Object Media.SoundPlayer '${file}').PlaySync()`;
-    spawn('powershell', ['-Command', psCommand], {
-      stdio: 'ignore',
-      windowsHide: true,
-    });
-  } catch {
-    // silent fail
+    switch (PLATFORM) {
+      case 'win32': {
+        const psCommand = `(New-Object Media.SoundPlayer '${file.replace(/'/g, "''")}').PlaySync()`;
+        spawn('powershell', ['-Command', psCommand], {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        break;
+      }
+      case 'darwin':
+        spawn('afplay', [file], { stdio: 'ignore' });
+        break;
+      case 'linux': {
+        const child = spawn('paplay', [file], { stdio: 'ignore' });
+        child.on('error', () => {
+          spawn('aplay', [file], { stdio: 'ignore' });
+        });
+        break;
+      }
+    }
+  } catch (err) {
+    debugLog(config, 'playSound failed:', err.message);
   }
 }
 
@@ -375,19 +499,34 @@ function speakResult (config, duration) {
   if (!config.voice.enabled) {
     return;
   }
+  const text = getVoicePhrase(duration);
   try {
-    const text = getVoicePhrase(duration);
-    const psCommand = [
-      'Add-Type -AssemblyName System.Speech;',
-      '$s = New-Object System.Speech.Synthesis.SpeechSynthesizer;',
-      `$s.Speak("${text.replace(/"/g, '`"')}");`,
-    ].join('');
-    spawn('powershell', ['-Command', psCommand], {
-      stdio: 'ignore',
-      windowsHide: true,
-    });
-  } catch {
-    // silent fail
+    switch (PLATFORM) {
+      case 'win32': {
+        const psCommand = [
+          'Add-Type -AssemblyName System.Speech;',
+          '$s = New-Object System.Speech.Synthesis.SpeechSynthesizer;',
+          `$s.Speak("${text.replace(/"/g, '`"')}");`,
+        ].join('');
+        spawn('powershell', ['-Command', psCommand], {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        break;
+      }
+      case 'darwin':
+        spawn('say', [text], { stdio: 'ignore' });
+        break;
+      case 'linux': {
+        const child = spawn('spd-say', [text], { stdio: 'ignore' });
+        child.on('error', () => {
+          spawn('espeak', [text], { stdio: 'ignore' });
+        });
+        break;
+      }
+    }
+  } catch (err) {
+    debugLog(config, 'speakResult failed:', err.message);
   }
 }
 
@@ -460,7 +599,7 @@ process.stdin.on('end', async () => {
     `${title}\n\nProject: ${project}\nDuration: ${duration}s\nTrigger: ${eventType}`;
 
   let telegramMessage =
-    `${title}\n\nProject: *${project}*\nDuration: ${duration}s\nTrigger: ${eventType}`;
+    `${escapeHtml(title)}\n\nProject: <b>${escapeHtml(project)}</b>\nDuration: ${duration}s\nTrigger: ${eventType}`;
 
   if (config.telegram.includeLastCcMessageInTelegram && event.last_assistant_message) {
     const maxLen = 3500;
@@ -468,15 +607,18 @@ process.stdin.on('end', async () => {
     if (lastMsg.length > maxLen) {
       lastMsg = lastMsg.slice(0, maxLen) + '…';
     }
-    telegramMessage += `\n\n${lastMsg}`;
+    telegramMessage += `\n\n${markdownToTelegramHtml(lastMsg)}`;
   }
 
   if (config.debug) {
-    const debugBlock = '\n\n*Debug:*\n'
+    const debugBlockMd = '\n\n*Debug:*\n'
       + (config.voice.enabled ? `\nVoice: ${getVoicePhrase(duration)}` : '')
       + `\n\nHook input:\n\`\`\`json\n${JSON.stringify(event, null, 2)}\n\`\`\``;
-    message += debugBlock;
-    telegramMessage += debugBlock;
+    const debugBlockHtml = '\n\n<b>Debug:</b>\n'
+      + (config.voice.enabled ? `\nVoice: ${escapeHtml(getVoicePhrase(duration))}` : '')
+      + `\n\nHook input:\n<pre>${escapeHtml(JSON.stringify(event, null, 2))}</pre>`;
+    message += debugBlockMd;
+    telegramMessage += debugBlockHtml;
   }
 
   state._telegramText = `\u{1F916} ${telegramMessage}`;
@@ -484,7 +626,7 @@ process.stdin.on('end', async () => {
   delete state._telegramText;
   saveState(state);
 
-  await sendWindowsNotification(config, message);
+  await sendDesktopNotification(config, message);
   playSound(config);
   speakResult(config, duration);
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "claude-notification-plugin",
   "productName": "claude-notification-plugin",
-  "version": "1.0.44",
-  "description": "Claude Code notifications щт task completion: Telegram, Windows toast, sound, and voice",
+  "version": "1.0.49",
+  "description": "Cross-platform Claude Code notifications on task completion: Telegram, desktop (Windows/macOS/Linux), sound, and voice",
   "type": "module",
   "engines": {
     "node": ">=18.0.0"
@@ -30,7 +30,10 @@
     "claude-code",
     "notifications",
     "telegram",
-    "hooks"
+    "hooks",
+    "macos",
+    "linux",
+    "cross-platform"
   ],
   "author": {
     "name": "Viacheslav Makarov",