claude-notification-plugin 1.0.80 → 1.0.88

package/.claude-plugin/plugin.json

@@ -1,14 +1,13 @@
-{
-  "name": "claude-notification-plugin",
-  "version": "1.0.80",
-  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
-  "author": {
-    "name": "Viacheslav Makarov",
-    "email": "npmjs@bazilio.ru"
-  },
-  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
-  "repository": "https://github.com/Bazilio-san/claude-notification-plugin",
-  "license": "MIT",
-  "keywords": ["notification", "telegram", "windows", "sound", "voice", "hooks"],
-  "commands": "./commands/"
-}
+{
+  "name": "claude-notification-plugin",
+  "version": "1.0.88",
+  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
+  "author": {
+    "name": "Viacheslav Makarov",
+    "email": "npmjs@bazilio.ru"
+  },
+  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
+  "repository": "https://github.com/Bazilio-san/claude-notification-plugin",
+  "license": "MIT",
+  "keywords": ["notification", "telegram", "windows", "sound", "voice", "hooks"]
+}

package/README.md

@@ -1,283 +1,276 @@
-# 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,
-  "notifyAfterSeconds": 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`  
-
-
-**notifyAfterSeconds**  
-Skip notifications for tasks shorter than this (seconds).  
-Default: **15**  
-ENV: `CLAUDE_NOTIFY_AFTER_SECONDS`  
-
-
-**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**
-
-ENV: **CLAUDE_NOTIFY_AFTER_LISTENER**  
-When a task is started by the Telegram Listener, notifications are suppressed by default to avoid duplicates (the listener sends its own status messages). Set to `1` to enable notifier notifications for listener-spawned tasks.  
-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,
-    "CLAUDE_NOTIFY_AFTER_SECONDS": 15
-  }
-}
-```
-
-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.
-
-When installed as a plugin, you can manage the listener daemon directly from Claude Code with the `/listener` slash command:
-`/claude-notification-plugin:listener start | stop | status | logs | restart`
-
-## CLI Commands Registration
-
-When installed as a **plugin**, CLI commands (`claude-notify-listener`, etc.) are not in PATH.
-The `/claude-notification-plugin:setup` command registers them automatically by placing wrapper scripts next to the `claude` binary.
-
-To manage manually:
-
-```bash
-claude-notify-register            # register CLI commands
-claude-notify-register list       # show registration status
-claude-notify-register unregister # remove CLI commands
-```
-
-When installed via `npm install -g`, npm links the commands itself — no extra step needed.
-
-## 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
+# Your remote control for Anthropic Claude Code
+
+**Send a message in Telegram, and the task starts running on your PC.**
+
+Cross-platform notifications for Claude Code task completion.
+Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
+
+
+## Features
+
+- **[Telegram Listener](#telegram-listener)** — your remote control for Claude (supports worktrees)
+- Telegram bot messages with auto-delete
+- Webhook notifications (any URL endpoint)
+- Desktop notifications (Windows toast, macOS Notification Center, Linux notify-send)
+- Sound alert
+- Voice announcement
+- Separate notifications for task completion and waiting-for-input events
+- Skips short tasks (< 15s by default)
+- Per-channel enable/disable (globally and per-project)
+
+## Install
+
+```bash
+npm install -g claude-notification-plugin
+```
+
+The installer prompts for Telegram bot credentials and sets everything up.
+Re-run `claude-notify-install` anytime to reconfigure.
+
+## Uninstall
+
+```bash
+npm uninstall -g claude-notification-plugin
+```
+
+## 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,
+  "notifyAfterSeconds": 15,
+  "notifyOnWaiting": false,
+  "debug": false,
+  "listener": {
+    "projects": {
+      "default": {
+        "path": "abs-path-to-project"
+      },
+      "alias1": {
+        "path": "abs-path-to-project"
+      }
+    },
+    "worktreeBaseDir": "abs-path-to-worktrees-root",
+    "autoCreateWorktree": true,
+    "taskTimeoutMinutes": 30,
+    "maxQueuePerWorkDir": 10,
+    "maxTotalTasks": 50,
+    "logDir": "abs-path-to-listener-logs",
+    "taskLogDir": "abs-path-to-task-logs"
+  }
+}
+```
+
+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 N hours. `0` to disable. Default: **24**
+
+**telegram.includeLastCcMessageInTelegram** — Append Claude's last message to the notification (truncated to 3500 chars). Default: **true**
+ENV: `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM`
+
+**desktopNotification.enabled** — Desktop notifications. Default: **true**
+ENV: `CLAUDE_NOTIFY_DESKTOP`
+
+**sound.enabled** — Sound alert on task completion. Default: **true**
+ENV: `CLAUDE_NOTIFY_SOUND`
+
+**sound.file** — Custom sound file path. Default: **platform default**
+
+**voice.enabled** — Voice announcement (TTS) with duration. Default: **true**
+ENV: `CLAUDE_NOTIFY_VOICE`
+
+**notifyOnWaiting** — Notify when Claude is waiting for input. Default: **false**
+ENV: `CLAUDE_NOTIFY_WAITING`
+
+**webhookUrl** — POST notification 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. Requires `webhookUrl`. Default: **false**
+ENV: `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK`
+
+**notifyAfterSeconds** — Skip notifications for tasks shorter than this. Default: **15**
+ENV: `CLAUDE_NOTIFY_AFTER_SECONDS`
+
+**debug** — Include trigger event type and full hook event JSON in notifications. Default: **false**
+ENV: `CLAUDE_NOTIFY_DEBUG`
+
+**CLAUDE_NOTIFY_DISABLE** — Set to `1` to disable all notifications for the current project.
+
+**CLAUDE_NOTIFY_AFTER_LISTENER** — Enable notifier notifications for listener-spawned tasks (suppressed by default to avoid duplicates). Set to `1` to enable.
+
+### Per-project configuration
+
+Add to `.claude/settings.local.json` in the project root:
+
+```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,
+    "CLAUDE_NOTIFY_AFTER_SECONDS": 15
+  }
+}
+```
+
+## 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
+
+Alternative: add **@userinfobot** to a chat and it will reply with the ID.
+
+## Telegram Listener
+
+Background daemon that receives tasks from Telegram and executes them via `claude -p`. The result is sent back to Telegram.
+
+The Listener uses the same bot and `chatId` as notifications.
+
+### 1. Add a `listener` section to config
+
+```json
+{
+  "listener": {
+    "projects": {
+      "default": { "path": "/home/user/my-project" },
+      "api": { "path": "/home/user/projects/api-server" },
+      "web": { "path": "/home/user/projects/web-app" }
+    }
+  }
+}
+```
+
+The `"default"` alias receives messages without a `@project` prefix.
+`api` and `web` are project aliases for easy reference from Telegram.
+
+### 2. Start the listener
+
+```bash
+claude-notify-listener start
+```
+
+### 3. Send tasks from Telegram
+
+```
+fix the login bug                     → runs in "default" project
+@api add pagination to GET /users     → runs in "api" project
+@api/feature/auth implement OAuth2    → runs in a worktree (auto-created)
+```
+
+The bot replies with status and results:
+
+```
+⏳ [@api] Running: add pagination to GET /users
+...
+✅ [@api] Done: add pagination to GET /users
+<claude's output>
+```
+
+### 4. Manage the daemon
+
+```bash
+claude-notify-listener status         # Check if running
+claude-notify-listener stop           # Stop
+claude-notify-listener restart        # Restart
+claude-notify-listener logs           # View last 50 log lines
+```
+
+### 5. Bot commands
+
+All commands start with `/` and execute instantly (not queued).
+
+| Command                       | Description                          |
+|-------------------------------|--------------------------------------|
+| `/status`                     | Status of all projects and worktrees |
+| `/status @project`            | Status of a specific project         |
+| `/queue`                      | Show all queues                      |
+| `/cancel @project[/branch]`   | Cancel the active task               |
+| `/drop @project N`            | Remove task N from queue             |
+| `/clear @project[/branch]`    | Clear queue                          |
+| `/projects`                   | List projects and paths              |
+| `/worktrees @project`         | List worktrees                       |
+| `/worktree @project branch`   | Create a worktree                    |
+| `/rmworktree @project branch` | Remove a worktree                    |
+| `/history`                    | Recent task history                  |
+| `/stop`                       | Stop the listener                    |
+| `/help`                       | Show help                            |
+
+### Listener configuration
+
+| Parameter            | Default               | Description                                         |
+|----------------------|-----------------------|-----------------------------------------------------|
+| `projects`           | (required)            | Map of projects: `alias → { path }`                 |
+| `worktreeBaseDir`    | `~/.claude/worktrees` | Where auto-created worktrees are stored              |
+| `autoCreateWorktree` | `true`                | Auto-create worktrees for unknown branches           |
+| `taskTimeoutMinutes` | `30`                  | Max task execution time (force-stopped when exceeded)|
+| `maxQueuePerWorkDir` | `10`                  | Max tasks in queue per working directory              |
+| `maxTotalTasks`      | `50`                  | Max tasks across all queues                          |
+| `logDir`             | `~/.claude`           | Listener log directory                               |
+| `taskLogDir`         | same as `logDir`      | Task Q&A log directory                               |
+
+### Projects and worktrees
+
+**The queue is tied to the working directory, not the project name:**
+- `@api task` and `@api/feature/auth task` → **different queues** (parallel)
+- `@api task1` and `@api task2` → **same queue** (sequential)
+
+Worktrees are auto-created when you use `@project/branch` syntax (controlled by `autoCreateWorktree`).
+
+```
+/worktree @api feature/payments     ← create
+/worktrees @api                     ← list
+/rmworktree @api feature/payments   ← remove
+```
+
+[Detailed Guide](listener/LISTENER-DETAILED.md) — internals, architecture, troubleshooting, full session example.
+
+## CLI Commands
+
+| Command                  | Description                                                                   |
+|--------------------------|-------------------------------------------------------------------------------|
+| `claude-notify-install`  | Re-run to reinstall plugin registration, Telegram config, hooks, CLI wrappers |
+| `claude-notify-listener` | Manage the Telegram Listener daemon (start/stop/status/logs/restart)          |
+
+## License
+
+MIT