claude-notification-plugin 1.0.59 → 1.0.63

package/.claude-plugin/plugin.json

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

package/README.md

@@ -6,18 +6,19 @@ Cross-platform notifications for Claude Code task completion. Sends alerts to Te
 
 - 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)
+- 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)
 
-Add the marketplace and install:
+Auto-updates, seamless integration with the plugin ecosystem.
 
 ```shell
 /plugin marketplace add Bazilio-san/claude-plugins
@@ -26,26 +27,15 @@ Add the marketplace and install:
 /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**.
+Go to `/plugin` → **Marketplaces** tab → select `bazilio-plugins` → **Enable auto-update**.
 
-To configure Telegram credentials, run:
+For a detailed visual walkthrough, see [step-by-step installation guide with screenshots](INSTALL_MARKETPLACE_AND_PLUGIN.md).
 
-```shell
-/claude-notification-plugin:setup
-```
 
 ### Option B: npm global package
 
+Simple install, works without the plugin system.
+
 ```bash
 npm install -g claude-notification-plugin
 claude-notify-install
@@ -89,39 +79,27 @@ 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.
-
-`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            |
+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).
+
+| Config option | Env var override | Default | Description |
+|---|---|---|---|
+| `telegram.enabled` | `CLAUDE_NOTIFY_TELEGRAM` | `true` | Telegram messages |
+| `telegram.token` | `CLAUDE_NOTIFY_TELEGRAM_TOKEN` | — | Bot token |
+| `telegram.chatId` | `CLAUDE_NOTIFY_TELEGRAM_CHAT_ID` | — | Chat ID |
+| `telegram.deleteAfterHours` | — | `24` | Auto-delete old messages (hours, `0` to disable) |
+| `telegram.includeLastCcMessageInTelegram` | `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM` | `true` | Append Claude's last message to Telegram notification (truncated to 3500 chars) |
+| `desktopNotification.enabled` | `CLAUDE_NOTIFY_DESKTOP` | `true` | Desktop notifications (toast / Notification Center / notify-send) |
+| `sound.enabled` | `CLAUDE_NOTIFY_SOUND` | `true` | Sound alert |
+| `sound.file` | — | platform default | Path to a custom sound file |
+| `voice.enabled` | `CLAUDE_NOTIFY_VOICE` | `true` | Voice announcement (TTS) |
+| `notifyOnWaiting` | `CLAUDE_NOTIFY_WAITING` | `false` | Notify when Claude is waiting for input (e.g. permission prompts) |
+| `webhookUrl` | `CLAUDE_NOTIFY_WEBHOOK_URL` | `""` | POST notification data (JSON) to this URL. Payload: `title`, `project`, `branch`, `duration`, `trigger`, `voicePhrase`, `hookEvent` |
+| `sendUserPromptToWebhook` | `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK` | `false` | Also send user prompts to the webhook. Payload: `title`, `project`, `trigger`, `prompt`, `hookEvent` |
+| `minSeconds` | — | `15` | Skip notifications for tasks shorter than this (seconds) |
+| `debug` | `CLAUDE_NOTIFY_DEBUG` | `false` | Include voice phrase text and full hook event JSON in notifications |
+| — | `CLAUDE_NOTIFY_DISABLE` | `0` | Disable all notifications (`1` to disable) |
+
+Default sound files: Windows `C:/Windows/Media/notify.wav`, macOS `/System/Library/Sounds/Glass.aiff`, Linux `/usr/share/sounds/freedesktop/stereo/complete.oga`.
 
 ### Per-project configuration
 
@@ -164,7 +142,6 @@ Notifications include project name, git branch (when available), duration, and t
 Project: my-project
 Branch: feature-auth
 Duration: 45s
-Trigger: Stop
 ```
 
 When Claude is waiting for input (and `notifyOnWaiting` is enabled):
@@ -175,7 +152,6 @@ When Claude is waiting for input (and `notifyOnWaiting` is enabled):
 Project: my-project
 Branch: feature-auth
 Duration: 30s
-Trigger: Notification
 ```
 
 ## Telegram Setup
@@ -190,19 +166,31 @@ Trigger: Notification
 
 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.
+
 ## Uninstall
 
 ### Plugin install
 
 Uninstall via the plugin manager or remove `--plugin-dir` flag.
 
-### npm install
+### npm
 
 ```bash
 claude-notify-uninstall
 npm uninstall -g claude-notification-plugin
 ```
 
+## Testing (load without install)
+
+```bash
+claude --plugin-dir /path/to/claude-notification-plugin
+```
+
+Hooks are registered automatically.
+
 ## License
 
 MIT

package/bin/listener-cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawn, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PID_FILE = path.join(os.homedir(), '.claude', '.listener.pid');
+const LOG_FILE = path.join(os.homedir(), '.claude', '.listener.log');
+const CONFIG_FILE = path.join(os.homedir(), '.claude', 'notifier.config.json');
+const LISTENER_SCRIPT = path.join(__dirname, '..', 'listener', 'listener.js');
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'start':
+    startDaemon();
+    break;
+  case 'stop':
+    stopDaemon();
+    break;
+  case 'status':
+    showStatus();
+    break;
+  case 'logs':
+    showLogs();
+    break;
+  case 'restart':
+    stopDaemon();
+    setTimeout(() => startDaemon(), 1000);
+    break;
+  default:
+    console.log('Usage: claude-notify-listener <start|stop|status|logs|restart>');
+    console.log('');
+    console.log('Commands:');
+    console.log('  start    Start the listener daemon');
+    console.log('  stop     Stop the listener daemon');
+    console.log('  status   Show daemon status');
+    console.log('  logs     Show recent log entries');
+    console.log('  restart  Restart the daemon');
+    process.exit(command ? 1 : 0);
+}
+
+function startDaemon () {
+  // Check if already running
+  const existingPid = readPid();
+  if (existingPid && isProcessAlive(existingPid)) {
+    console.log(`Listener is already running (PID: ${existingPid})`);
+    process.exit(1);
+  }
+
+  // Clean stale PID file
+  if (existingPid) {
+    try {
+      fs.unlinkSync(PID_FILE);
+    } catch {
+      // ignore
+    }
+  }
+
+  // Validate config
+  if (!fs.existsSync(CONFIG_FILE)) {
+    console.error(`Config not found: ${CONFIG_FILE}`);
+    console.error('Run claude-notify-install first, or create the config manually.');
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch (err) {
+    console.error(`Invalid config: ${err.message}`);
+    process.exit(1);
+  }
+
+  const token = process.env.CLAUDE_NOTIFY_TELEGRAM_TOKEN || config.telegramToken || config.telegram?.token;
+  const chatId = process.env.CLAUDE_NOTIFY_TELEGRAM_CHAT_ID || config.telegramChatId || config.telegram?.chatId;
+
+  if (!token || !chatId) {
+    console.error('Missing telegramToken or telegramChatId in config.');
+    console.error('These are required for the listener to receive messages.');
+    process.exit(1);
+  }
+
+  if (!config.listener?.projects || Object.keys(config.listener.projects).length === 0) {
+    console.error('No projects defined in config.listener.projects');
+    console.error('');
+    console.error('Add projects to your config:');
+    console.error(JSON.stringify({
+      listener: {
+        projects: {
+          default: { path: '/path/to/your/project' },
+        },
+      },
+    }, null, 2));
+    process.exit(1);
+  }
+
+  // Ensure log directory exists
+  fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+
+  // Open log file for child stdio
+  const logFd = fs.openSync(LOG_FILE, 'a');
+
+  // Spawn detached child
+  const child = spawn(process.execPath, [LISTENER_SCRIPT], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env: { ...process.env },
+    windowsHide: true,
+  });
+
+  child.unref();
+  fs.closeSync(logFd);
+
+  // Write PID
+  fs.mkdirSync(path.dirname(PID_FILE), { recursive: true });
+  fs.writeFileSync(PID_FILE, String(child.pid));
+
+  console.log(`Listener started (PID: ${child.pid})`);
+  console.log(`Log: ${LOG_FILE}`);
+  console.log(`Projects: ${Object.keys(config.listener.projects).join(', ')}`);
+}
+
+function stopDaemon () {
+  const pid = readPid();
+  if (!pid) {
+    console.log('Listener is not running (no PID file)');
+    return;
+  }
+
+  if (!isProcessAlive(pid)) {
+    console.log(`Listener is not running (stale PID: ${pid})`);
+    cleanPid();
+    return;
+  }
+
+  console.log(`Stopping listener (PID: ${pid})...`);
+
+  try {
+    if (process.platform === 'win32') {
+      execSync(`taskkill /PID ${pid} /T /F`, {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+    } else {
+      process.kill(pid, 'SIGTERM');
+      // Wait for graceful shutdown
+      let tries = 10;
+      while (tries-- > 0 && isProcessAlive(pid)) {
+        execSync('sleep 0.5', { stdio: 'ignore' });
+      }
+      if (isProcessAlive(pid)) {
+        process.kill(pid, 'SIGKILL');
+      }
+    }
+  } catch {
+    // Process may already be dead
+  }
+
+  cleanPid();
+  console.log('Listener stopped');
+}
+
+function showStatus () {
+  const pid = readPid();
+  if (!pid) {
+    console.log('Status: not running');
+    return;
+  }
+
+  if (!isProcessAlive(pid)) {
+    console.log(`Status: not running (stale PID: ${pid})`);
+    cleanPid();
+    return;
+  }
+
+  console.log(`Status: running (PID: ${pid})`);
+  console.log(`Log: ${LOG_FILE}`);
+
+  // Show last few log lines
+  try {
+    if (fs.existsSync(LOG_FILE)) {
+      const content = fs.readFileSync(LOG_FILE, 'utf-8');
+      const lines = content.trim().split('\n');
+      const last = lines.slice(-5);
+      console.log('\nRecent log:');
+      for (const line of last) {
+        console.log(`  ${line}`);
+      }
+    }
+  } catch {
+    // ignore
+  }
+}
+
+function showLogs () {
+  try {
+    if (!fs.existsSync(LOG_FILE)) {
+      console.log('No log file found');
+      return;
+    }
+    const content = fs.readFileSync(LOG_FILE, 'utf-8');
+    const lines = content.trim().split('\n');
+    const last = lines.slice(-50);
+    for (const line of last) {
+      console.log(line);
+    }
+  } catch (err) {
+    console.error(`Failed to read log: ${err.message}`);
+  }
+}
+
+function readPid () {
+  try {
+    if (fs.existsSync(PID_FILE)) {
+      const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim(), 10);
+      return isNaN(pid) ? null : pid;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function cleanPid () {
+  try {
+    if (fs.existsSync(PID_FILE)) {
+      fs.unlinkSync(PID_FILE);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+function isProcessAlive (pid) {
+  try {
+    if (process.platform === 'win32') {
+      const result = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+        encoding: 'utf-8',
+        windowsHide: true,
+        stdio: ['pipe', 'pipe', 'ignore'],
+      });
+      return result.includes(String(pid));
+    }
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/commands/listener.md

@@ -0,0 +1,100 @@
+---
+description: Manage the Telegram Listener daemon (start, stop, status, logs, restart)
+---
+
+# Listener Management
+
+Manage the Telegram Listener daemon that receives tasks from Telegram and executes them via `claude -p`.
+
+The user invokes this command as `/claude-notification-plugin:listener <action>`.
+
+## Actions
+
+Determine the action from the user's input. If no action is provided, show the help text below and ask which action they want.
+
+### start
+
+Start the listener daemon.
+
+1. Determine the plugin root path — use the directory where this command file lives: `${CLAUDE_PLUGIN_ROOT}`. The listener CLI script is at `${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js`.
+2. Run in a shell:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js" start
+   ```
+3. Show the output to the user. If it says "Listener started", confirm success. If there is an error (missing config, missing projects, already running), explain what to do.
+
+### stop
+
+Stop the listener daemon.
+
+1. Run:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js" stop
+   ```
+2. Show the output.
+
+### status
+
+Show the listener status.
+
+1. Run:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js" status
+   ```
+2. Show the output.
+
+### logs
+
+Show recent log entries.
+
+1. Run:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js" logs
+   ```
+2. Show the output.
+
+### restart
+
+Restart the listener daemon.
+
+1. Run:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/listener-cli.js" restart
+   ```
+2. Show the output.
+
+## Help text
+
+If the user doesn't specify an action, show:
+
+```
+Telegram Listener — receives tasks from Telegram and executes via claude -p.
+
+Usage:
+  /claude-notification-plugin:listener start    — Start the daemon
+  /claude-notification-plugin:listener stop     — Stop the daemon
+  /claude-notification-plugin:listener status   — Show status
+  /claude-notification-plugin:listener logs     — Show recent logs
+  /claude-notification-plugin:listener restart  — Restart the daemon
+
+Prerequisites:
+  1. Telegram bot configured (token + chatId in ~/.claude/notifier.config.json)
+  2. "listener.projects" section in config with at least one project
+
+See LISTENER.md for detailed documentation.
+```
+
+## Important
+
+- The `${CLAUDE_PLUGIN_ROOT}` variable resolves to the plugin installation directory. Always use it to build the path to `bin/listener-cli.js`.
+- If the config doesn't have a `listener.projects` section, tell the user to add one and show a minimal example:
+  ```json
+  {
+    "listener": {
+      "projects": {
+        "default": { "path": "/path/to/your/project" }
+      }
+    }
+  }
+  ```
+- If Telegram credentials are missing, suggest running `/claude-notification-plugin:setup` first.