claude-notification-plugin 1.0.66 → 1.0.72

package/.claude-plugin/plugin.json

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

package/README.md

@@ -73,7 +73,7 @@ Config file: `~/.claude/notifier.config.json`
   },
   "webhookUrl": "",
   "sendUserPromptToWebhook": false,
-  "minSeconds": 15,
+  "notifyAfterSeconds": 15,
   "notifyOnWaiting": false,
   "debug": false
 }
@@ -149,9 +149,10 @@ Default: **false**
 ENV: `CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK`  
 
 
-**minSeconds**  
+**notifyAfterSeconds**  
 Skip notifications for tasks shorter than this (seconds).  
 Default: **15**  
+ENV: `CLAUDE_NOTIFY_AFTER_SECONDS`  
 
 
 **debug**  
@@ -180,7 +181,8 @@ Add to `.claude/settings.local.json` in the project root to control channels per
     "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_SEND_USER_PROMPT_TO_WEBHOOK": 0,
+    "CLAUDE_NOTIFY_AFTER_SECONDS": 15
   }
 }
 ```

package/bin/install.js

@@ -163,7 +163,7 @@ async function main () {
     },
     webhookUrl: '',
     sendUserPromptToWebhook: false,
-    minSeconds: 15,
+    notifyAfterSeconds: 15,
     notifyOnWaiting: false,
     debug: false,
   };

package/commands/setup.md

@@ -18,7 +18,7 @@ Help the user configure the notification plugin. The config file is `~/.claude/n
    - If auto-detection fails, ask the user to enter the Chat ID manually.
    - If Chat ID already exists, show it and ask if the user wants to keep it.
 
-4. **Write the config** to `~/.claude/notifier.config.json`. Merge with existing config — do NOT overwrite settings that already exist (`minSeconds`, `notifyOnWaiting`, `debug`, channel `enabled` flags, etc.). Only update `telegram.token` and `telegram.chatId` with the values from this session.
+4. **Write the config** to `~/.claude/notifier.config.json`. Merge with existing config — do NOT overwrite settings that already exist (`notifyAfterSeconds`, `notifyOnWaiting`, `debug`, channel `enabled` flags, etc.). Only update `telegram.token` and `telegram.chatId` with the values from this session.
 
    Default config structure (for new installs):
    ```json
@@ -32,7 +32,7 @@ Help the user configure the notification plugin. The config file is `~/.claude/n
      "windowsNotification": { "enabled": true },
      "sound": { "enabled": true, "file": "C:/Windows/Media/notify.wav" },
      "voice": { "enabled": true },
-     "minSeconds": 15,
+     "notifyAfterSeconds": 15,
      "notifyOnWaiting": false,
      "debug": false
    }

package/listener/LISTENER-DETAILED.md

@@ -0,0 +1,984 @@
+# Telegram Listener - Detailed Guide
+
+Telegram Listener is a background daemon that receives tasks from a Telegram chat
+and executes them on your machine via `claude -p`. The result is sent back to Telegram.
+
+**[Quick Start here](../LISTENER.md)**
+
+# Detailed Guide
+
+## Table of Contents
+
+- [What is the Listener](#what-is-the-listener)
+- [Long polling: how it works](#long-polling-how-it-works)
+- [Detached process: why the listener lives without a terminal](#detached-process-why-the-listener-lives-without-a-terminal)
+- [PID file and duplicate protection](#pid-file-and-duplicate-protection)
+- [Listener components](#listener-components)
+- [Message processing flow](#message-processing-flow)
+- [Configuration](#configuration)
+- [Sending tasks](#sending-tasks)
+- [Projects and worktrees](#projects-and-worktrees)
+- [Task queues](#task-queues)
+- [Bot commands](#bot-commands)
+- [Task lifecycle](#task-lifecycle)
+- [State files](#state-files)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Full session example](#full-session-example)
+
+---
+
+## What is the Listener
+
+The Listener is **not a web server**. It does not listen on ports, does not accept incoming connections, and does not require a public IP, domain, or SSL.
+
+The Listener is a regular Node.js program that runs an infinite loop:
+
+```
+while (true) {
+  1. Send an HTTP request to Telegram: "Any new messages?"
+  2. Telegram responds: "Yes, here are 3 messages" (or "No, nothing")
+  3. Process each message
+  4. goto 1
+}
+```
+
+The Listener fetches data from Telegram itself (outgoing requests), rather than Telegram connecting to it (incoming). That's why it works behind any NAT, firewall, or VPN — from anywhere with internet access.
+
+---
+
+## Long polling: how it works
+
+```
+Listener (your computer)              Telegram server
+────────────────────────              ──────────────
+
+GET /getUpdates?timeout=30  ────►     "Let's wait up to 30 seconds,
+                                       maybe someone will write..."
+
+    (listener hangs and waits,
+     connection is open)
+
+                                      After 15 sec a user
+                                      wrote "@proj1 fix bug"
+
+◄──── {"result": [{"message":...}]}   "There's a message, here it is!"
+
+Processing... launching claude...
+
+GET /getUpdates?timeout=30  ────►     "Waiting again..."
+
+    (30 seconds of silence, nobody writes)
+
+◄──── {"result": []}                  "Nothing in 30 sec"
+
+GET /getUpdates?timeout=30  ────►     ...and so on in a loop
+```
+
+**How `timeout=30` works**: this is not a polling interval of once every 30 seconds. It tells Telegram: "keep the connection open for up to 30 seconds. If a message arrives during this time — respond **immediately**. If not — respond with an empty result."
+
+In practice, delivery latency is:
+- If a message arrives while waiting → **instant** (less than a second)
+- Worst case (message arrives right after a response) → up to 30 seconds
+
+The `offset` parameter in the request ensures each message is processed exactly once: after receiving messages, the listener remembers `update_id + 1` and passes it in the next request, so Telegram doesn't return already-processed messages.
+
+---
+
+## Detached process: why the listener lives without a terminal
+
+When you run `claude-notify-listener start`, the following happens:
+
+```
+Your terminal
+     │
+     └─► listener-cli.js start
+              │
+              ├─ Check: is it already running?
+              ├─ Check config
+              │
+              ├─ spawn("node listener.js", { detached: true })
+              │       │
+              │       └─► listener.js ← SEPARATE OS PROCESS
+              │           Not attached to the terminal.
+              │           Lives on its own.
+              │           PID written to ~/.claude/.listener.pid
+              │
+              ├─ child.unref()  ← "don't wait for child process to finish"
+              ├─ console.log("Started PID: 12345")
+              └─ exit
+     │
+     Terminal is free (or closed)
+
+     listener.js continues running.
+```
+
+`detached: true` — creates a process not tied to the parent.
+`child.unref()` — allows `listener-cli.js` to exit without waiting for the child.
+
+Result: the listener runs as a background OS process. It is not tied to a terminal or to Claude Code — only to the operating system. It will only stop when:
+- The `claude-notify-listener stop` command is issued (or `/stop` in Telegram)
+- The computer is shut down or restarted
+- It crashes due to an error
+
+---
+
+## PID file and duplicate protection
+
+The PID file (`~/.claude/.listener.pid`) is simply a text file with the process number:
+
+```
+12345
+```
+
+Why it's needed:
+- **`start`** — check whether the listener is already running
+- **`stop`** — determine which process to kill
+- **`status`** — show whether it's running and with which PID
+
+### What if the listener crashes but the PID file remains?
+
+This is a normal situation. Every `start` and `status` performs a check:
+
+```
+1. Read PID from file → 12345
+2. Check: is process 12345 alive?
+     Windows: tasklist /FI "PID eq 12345"
+     Linux:   kill -0 12345
+
+3a. Process is ALIVE
+     → "Listener is already running (PID: 12345)"
+     → A new one is not started
+
+3b. Process is DEAD
+     → PID file is stale, delete it
+     → Start a new listener normally
+```
+
+The scenario where the OS reuses the PID for another process is extremely unlikely, and even if it happens, the listener will simply show "already running" and you can delete the PID file manually (`rm ~/.claude/.listener.pid`) and start again.
+
+### Two listener instances
+
+Running two listeners is impossible — the PID file prevents it. And this is important: two listeners on the same bot break long polling. Whichever calls `getUpdates` first gets the messages. The second gets an empty response. Messages would be randomly lost between the two processes.
+
+---
+
+## Listener components
+
+```
+┌────────────────────────────────────────────┐
+│              listener.js (OS process)      │
+│                                            │
+│  ┌────────────────┐    ┌───────────────┐   │
+│  │ TelegramPoller │    │   WorkQueue   │   │
+│  │                │    │ (per-workDir) │   │
+│  │ long polling   │    │ active + FIFO │   │
+│  │ getUpdates()   │    │ .json on disk │   │
+│  │ sendMessage()  │    └───────┬───────┘   │
+│  └───────┬────────┘            │           │
+│          │                     │           │
+│  ┌───────┴────────┐    ┌───────┴───────┐   │
+│  │ MessageParser  │    │  TaskRunner   │   │
+│  │                │    │               │   │
+│  │ @proj/branch   │    │ spawn claude  │   │
+│  │ /commands      │    │ timeouts      │   │
+│  └────────────────┘    │ kill          │   │
+│                        └───────────────┘   │
+│  ┌────────────────┐    ┌───────────────┐   │
+│  │WorktreeManager │    │    Logger     │   │
+│  │                │    │               │   │
+│  │ git worktree   │    │ .log file     │   │
+│  │ add/remove     │    │ rotation 5MB  │   │
+│  │ auto-discover  │    └───────────────┘   │
+│  └────────────────┘                        │
+└────────────────────────────────────────────┘
+```
+
+| Module | File | Description |
+|---|---|---|
+| **TelegramPoller** | `telegram-poller.js` | Long polling to the Telegram API. Receives messages, sends replies. Splits long messages into chunks |
+| **MessageParser** | `message-parser.js` | Parses message text: is it a command (`/status`) or a task (`@proj1 fix bug`)? Extracts project, branch, task text |
+| **WorkQueue** | `work-queue.js` | Manages task queues. Each working directory has a separate FIFO queue. Guarantees: one `claude` process per directory. Persists state to disk |
+| **TaskRunner** | `task-runner.js` | Runs `claude -p "task"` as a child process. Monitors timeouts. Can kill the process on cancellation. Emits events: complete, error, timeout |
+| **WorktreeManager** | `worktree-manager.js` | Creates and removes git worktrees. Auto-discovery via `git worktree list`. Maps `@project/branch` to a path on disk |
+| **Logger** | `logger.js` | Writes log to `~/.claude/.listener.log`. Rotation when exceeding 5 MB (old file → `.log.old`) |
+
+---
+
+## Message processing flow
+
+```
+Telegram message
+       │
+       ▼
+TelegramPoller.getUpdates()
+       │
+       ├─ chat_id matches config? ── No ──► ignore + log warning
+       │
+       ▼ Yes
+MessageParser.parse(text)
+       │
+       ├─ Starts with "/"? ──► Command
+       │    ├─ /status, /queue, /cancel, /drop, /clear
+       │    ├─ /projects, /worktrees, /worktree, /rmworktree
+       │    ├─ /history, /help, /stop
+       │    └─ Execute → reply in Telegram
+       │
+       └─ Otherwise ──► Task
+            │
+            ├─ "@proj1/feature/auth fix bug"
+            │    → project = "proj1"
+            │    → branch = "feature/auth"
+            │    → text = "fix bug"
+            │
+            ├─ "@proj1 fix bug"
+            │    → project = "proj1"
+            │    → branch = null (main)
+            │    → text = "fix bug"
+            │
+            └─ "fix bug"
+                 → project = "default"
+                 → branch = null (main)
+                 → text = "fix bug"
+            │
+            ▼
+WorktreeManager.resolveWorkDir(project, branch)
+       │
+       ├─ branch = null → path from config (main worktree)
+       ├─ branch found in worktrees → worktree path
+       ├─ branch not found + autoCreate = true → git worktree add
+       └─ branch not found + autoCreate = false → error
+       │
+       ▼
+WorkQueue.enqueue(workDir, task)
+       │
+       ├─ workDir is free (active = null)
+       │    → active = task
+       │    → TaskRunner.run(workDir, task)
+       │    → claude -p "fix bug" --output-format text
+       │    → Telegram: "⏳ Running: fix bug"
+       │
+       └─ workDir is busy (active != null)
+            → queue.push(task)
+            → Telegram: "📋 Queued (position N)"
+       │
+       ▼ (when claude finishes)
+TaskRunner emit 'complete'/'error'/'timeout'
+       │
+       ├─ Send result to Telegram
+       └─ WorkQueue.onTaskComplete(workDir)
+            ├─ Queue is empty → active = null
+            └─ More tasks → shift() → TaskRunner.run()
+```
+
+---
+
+## Configuration
+
+Full example of `~/.claude/notifier.config.json` with the listener section:
+
+```json
+{
+  "telegram": {
+    "token": "123456789:ABCdefGHIjklMNO...",
+    "chatId": "987654321",
+    "enabled": true,
+    "deleteAfterHours": 24
+  },
+  "listener": {
+    "projects": {
+      "default": {
+        "path": "/home/user/main-project"
+      },
+      "api": {
+        "path": "/home/user/projects/api-server",
+        "worktrees": {
+          "feature/auth": "/home/user/projects/api-wt-auth"
+        }
+      },
+      "web": {
+        "path": "/home/user/projects/web-app"
+      }
+    },
+    "worktreeBaseDir": "~/.claude/worktrees",
+    "autoCreateWorktree": true,
+    "taskTimeoutMinutes": 30,
+    "maxQueuePerWorkDir": 10,
+    "maxTotalTasks": 50
+  }
+}
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `projects` | — (required) | Map of projects: `alias → { path, worktrees? }` |
+| `worktreeBaseDir` | `~/.claude/worktrees` | Where auto-created worktrees are stored |
+| `autoCreateWorktree` | `true` | Automatically create a worktree if the branch is not found |
+| `taskTimeoutMinutes` | `30` | Maximum task execution time in minutes. Force-stopped when exceeded |
+| `maxQueuePerWorkDir` | `10` | Maximum tasks in the queue for a single working directory |
+| `maxTotalTasks` | `50` | Maximum tasks across all queues combined |
+
+### What is `projects`?
+
+Each project is an alias (short name) + path to a directory on disk:
+
+```json
+{
+  "api": {
+    "path": "/home/user/projects/api-server"
+  }
+}
+```
+
+Now in Telegram you can write `@api refactor the code`, and Claude will run in the `/home/user/projects/api-server` directory.
+
+The **`default`** alias is special. Messages without `@project` go to it:
+
+```json
+{
+  "default": {
+    "path": "/home/user/main-project"
+  }
+}
+```
+
+---
+
+## Sending tasks
+
+### Message format
+
+In the Telegram chat with the bot:
+
+```
+@project task                      ← task in the main worktree of the project
+@project/branch task               ← task in the worktree of a specific branch
+task without @                     ← task in the "default" project
+```
+
+### Examples
+
+```
+add a README to the project
+```
+→ runs in the `default` project (if configured)
+
+```
+@api fix the authentication bug
+```
+→ runs in `/home/user/projects/api-server`
+
+```
+@api/feature/payments add Stripe integration
+```
+→ runs in the `feature/payments` worktree of the `api` project.
+If the worktree doesn't exist, it will be created automatically.
+
+```
+@web update dependencies
+```
+→ runs in `/home/user/projects/web-app`
+
+### What happens when a task is sent
+
+1. The Listener receives the message from Telegram
+2. Parses `@project/branch` from the beginning of the message
+3. Determines the working directory (workDir)
+4. Checks: is this workDir busy with another task?
+   - **No** → runs `claude -p "task"` immediately, replies with `⏳ Running...`
+   - **Yes** → adds to the queue, replies with `📋 Queued (position N)...`
+5. When Claude finishes → sends the result to Telegram
+6. If there's a next task in the queue → starts it
+
+---
+
+## Projects and worktrees
+
+### Why worktrees?
+
+Git worktrees allow you to have multiple working copies of the same repository in different directories, each on its own branch.
+
+Without worktrees: one repository = one directory = one task at a time.
+
+With worktrees: one repository, but 3 directories on different branches = 3 tasks in parallel.
+
+```
+api-server/                        ← main worktree, branch main
+  └─ src/...
+
+~/.claude/worktrees/api/
+  ├─ feature-auth/                 ← worktree, branch feature/auth
+  │    └─ src/...
+  └─ feature-payments/             ← worktree, branch feature/payments
+       └─ src/...
+```
+
+### How the listener works with worktrees
+
+**The queue is tied to the working directory, not to the project name.**
+
+This means:
+- `@api task` and `@api/feature/auth task` are **different queues**, because they're different directories. They run **in parallel**.
+- `@api task1` and `@api task2` are **the same queue** (both go to the main worktree). `task2` will wait for `task1` to complete.
+
+```
+Project "api"
+  │
+  ├─ main worktree (/home/user/projects/api)
+  │    Queue: [task1] → [task2] → ...    ← strictly sequential
+  │
+  ├─ feature/auth (~/.claude/worktrees/api/feature-auth)
+  │    Queue: [task3] → [task4] → ...    ← strictly sequential
+  │
+  └─ feature/payments (~/.claude/worktrees/api/feature-payments)
+       Queue: [task5] → ...              ← strictly sequential
+
+All three queues run IN PARALLEL.
+Within each — strictly one task at a time.
+```
+
+### Auto-creation of worktrees
+
+When you write `@api/feature/new task`, and a worktree for the `feature/new` branch doesn't exist:
+
+1. The Listener checks: does the `feature/new` branch exist in git?
+   - Yes → `git worktree add ~/.claude/worktrees/api/feature-new feature/new`
+   - No → `git worktree add -b feature/new ~/.claude/worktrees/api/feature-new`
+2. Registers the new worktree in the config
+3. Replies in Telegram: `🌿 Created worktree feature/new for project "api"`
+4. Starts the task in the new worktree
+
+This behavior is controlled by the `autoCreateWorktree` parameter (default: `true`).
+
+### Auto-discovery of worktrees
+
+On startup, the listener scans each project with `git worktree list` and picks up all worktrees that were created manually (via `git worktree add`). You don't need to manually specify each worktree in the config.
+
+### Manual worktree management from Telegram
+
+```
+/worktree @api feature/payments     ← create a worktree
+/worktrees @api                     ← list all worktrees for a project
+/rmworktree @api feature/payments   ← remove a worktree
+```
+
+---
+
+## Task queues
+
+### How it works
+
+Each working directory (workDir) has:
+- **active** — the task currently being executed (or `null`)
+- **queue** — an array of tasks waiting to be executed (FIFO)
+
+While `active !== null`, all new tasks for this workDir go into the `queue`.
+
+### Example: 4 tasks, 2 projects
+
+```
+10:00  You: @api fix the router bug
+       Bot: ⏳ [@api] Running: fix the router bug
+       (api/main: active = "fix the router bug", queue = [])
+
+10:01  You: @web update dependencies
+       Bot: ⏳ [@web] Running: update dependencies
+       (web/main: active = "update dependencies", queue = [])
+       (api and web are running in parallel!)
+
+10:02  You: @api add tests
+       Bot: 📋 [@api] Queued (position 1).
+            Currently running: fix the router bug
+       (api/main: active = "fix the router bug", queue = ["add tests"])
+
+10:03  You: @api refactor the code
+       Bot: 📋 [@api] Queued (position 2).
+            Currently running: fix the router bug
+       (api/main: active = "fix the router bug", queue = ["add tests", "refactor"])
+
+10:05  Bot: ✅ [@web] Done: update dependencies
+            <result>
+       (web/main: active = null, queue = [])
+
+10:08  Bot: ✅ [@api] Done: fix the router bug
+            <result>
+       Bot: ⏳ [@api] Running: add tests
+       (api/main: active = "add tests", queue = ["refactor"])
+       (next task started automatically!)
+
+10:15  Bot: ✅ [@api] Done: add tests
+            <result>
+       Bot: ⏳ [@api] Running: refactor the code
+       (api/main: active = "refactor", queue = [])
+
+10:25  Bot: ✅ [@api] Done: refactor the code
+            <result>
+       (api/main: active = null, queue = [])
+       (all tasks completed)
+```
+
+### Limits
+
+- Maximum **10** tasks in the queue per workDir (configurable: `maxQueuePerWorkDir`)
+- Maximum **50** tasks across all queues combined (configurable: `maxTotalTasks`)
+- If the limit is exceeded, the bot will reply with an error
+
+### Timeout
+
+If a task runs longer than 30 minutes (configurable: `taskTimeoutMinutes`), it is forcefully stopped:
+
+```
+Bot: ⏰ [@api] Task forcefully stopped — timeout exceeded (30 min): refactor the code
+```
+
+After a timeout, the next task from the queue starts automatically.
+
+---
+
+## Bot commands
+
+All commands start with `/` and execute instantly (they are not queued).
+
+### /status — project status
+
+```
+You: /status
+Bot: 📊 Status:
+     Uptime: 2h 15m
+
+     api:
+       main: ▶ fix the router bug (3m 42s) +2 queued
+       feature/auth: ✅ idle
+     web:
+       main: ✅ idle
+```
+
+```
+You: /status @api
+Bot: 📊 Project "api":
+
+     main:
+       ▶ fix the router bug (3m 42s)
+       Queue: 2 tasks
+     feature/auth:
+       ✅ idle
+       Queue: 0 tasks
+```
+
+### /queue — queue contents
+
+```
+You: /queue
+Bot: 📋 Queues:
+
+     @api:
+       ▶ fix the router bug
+       1. add tests
+       2. refactor the code
+```
+
+### /cancel — cancel a task
+
+```
+You: /cancel @api
+Bot: 🛑 [@api] Task cancelled. Starting next.
+     ⏳ [@api] Running: add tests
+```
+
+Cancelling a task in a worktree:
+
+```
+You: /cancel @api/feature/auth
+Bot: 🛑 [@api/feature/auth] Task cancelled
+```
+
+### /drop — remove from queue
+
+Removes a task that **hasn't started executing yet** (waiting in the queue):
+
+```
+You: /drop @api 2
+Bot: 🗑 Removed from queue: refactor the code
+```
+
+The task number is the position in the queue (starting from 1). You can check numbers with `/queue`.
+
+### /clear — clear the queue
+
+Removes all tasks from the queue (the active task continues running):
+
+```
+You: /clear @api
+Bot: 🧹 [@api] Queue cleared (3 tasks)
+```
+
+### /projects — list projects
+
+```
+You: /projects
+Bot: 📂 Projects:
+
+     @default → /home/user/main-project
+     @api → /home/user/projects/api-server
+       /feature/auth → ~/.claude/worktrees/api/feature-auth
+     @web → /home/user/projects/web-app
+```
+
+### /worktrees — project worktrees
+
+```
+You: /worktrees @api
+Bot: 🌳 Worktrees for project "api":
+     • main → /home/user/projects/api-server
+     • feature/auth → ~/.claude/worktrees/api/feature-auth
+     • feature/payments → ~/.claude/worktrees/api/feature-payments
+```
+
+### /worktree — create a worktree
+
+```
+You: /worktree @api feature/payments
+Bot: 🌿 Created worktree for project "api":
+     Branch: feature/payments
+     Path: ~/.claude/worktrees/api/feature-payments
+```
+
+### /rmworktree — remove a worktree
+
+```
+You: /rmworktree @api feature/payments
+Bot: 🗑 Worktree feature/payments removed from project "api"
+```
+
+If a task is running in the worktree, removal will be rejected:
+
+```
+Bot: ❌ Cannot remove worktree: a task is running in it.
+     First /cancel @api/feature/payments
+```
+
+### /history — history
+
+```
+You: /history
+Bot: 📜 Recent tasks:
+
+     ✅ [@api] fix the router bug
+     ✅ [@web] update dependencies
+     🛑 [@api/feature/auth] implement OAuth2
+     ✅ [@api] add tests
+```
+
+### /stop — stop the listener
+
+```
+You: /stop
+Bot: 👋 Listener is shutting down...
+```
+
+All active tasks will be terminated. Queues are saved to disk and will be restored on the next startup.
+
+### /help — help
+
+Shows a brief reference for all commands.
+
+---
+
+## Task lifecycle
+
+### Path of a task from message to result
+
+```
+1. RECEIPT
+   Telegram message → getUpdates() → parsing
+
+2. ROUTING
+   "@api/feature/auth task"
+     → project = "api"
+     → branch = "feature/auth"
+     → workDir = ~/.claude/worktrees/api/feature-auth
+
+3. QUEUING
+   workDir busy?
+     → No: active = task, start immediately
+     → Yes: queue.push(task), reply with position
+
+4. EXECUTION
+   claude -p "task" --output-format text
+     cwd = workDir
+     timeout = 30 min
+   Telegram: "⏳ Running: <task>"
+
+5. WAITING
+   The claude process is working...
+   (listener continues accepting other messages)
+
+6. COMPLETION
+   claude finished:
+     exit 0 → "✅ Done" + stdout
+     exit N → "❌ Error" + stderr
+     timeout → "⏰ Timeout"
+
+7. NEXT TASK
+   queue not empty?
+     → Yes: shift() → goto 4
+     → No: active = null, workDir is free
+```
+
+### What Claude receives
+
+The command that gets executed:
+
+```bash
+claude -p "your message text from Telegram" --output-format text
+```
+
+With the working directory (`cwd`) = project/worktree workDir.
+
+Claude sees the project files, CLAUDE.md, .claude/settings.json, and everything else as if you had launched it manually in that directory.
+
+### What is returned to Telegram
+
+All stdout from claude. This is Claude's text response to your task.
+
+Handling long responses:
+- Up to 4096 characters — a single message
+- 4096–20000 characters — multiple messages (split by lines)
+- Over 20000 — first 2000 and last 2000 characters + full text as a file
+
+---
+
+## State files
+
+All files are stored in `~/.claude/`:
+
+| File | Description |
+|---|---|
+| `.listener.pid` | PID of the running daemon. On `start`, it checks whether the process is alive |
+| `.listener.log` | Operation log. Rotation when exceeding 5 MB (old file → `.log.old`) |
+| `.task_queues.json` | Current state of all queues. Persisted to disk after every change |
+| `.task_history.json` | Last 50 completed tasks (for `/history`) |
+
+### Recovery after reboot
+
+On startup, the listener:
+
+1. Loads `.task_queues.json`
+2. Watchdog checks all `active` tasks:
+   - Process PID is dead → clears active, starts the next one from the queue
+   - Task exceeded timeout → clears active, starts the next one
+3. Tasks waiting in the queue remain and will be executed
+
+This means: if the computer reboots, tasks in the queue won't be lost. But an active task that didn't finish will be marked as stale and skipped.
+
+---
+
+## Security
+
+### Authorization
+
+The Listener processes **only** messages from the `chatId` specified in the config. All other messages are ignored and logged as warnings.
+
+### No shell injection
+
+Task text is passed to claude as an array argument, not through the shell:
+
+```js
+// Like this (safe):
+spawn('claude', ['-p', userText], { ... })
+
+// NOT like this (dangerous):
+exec(`claude -p "${userText}"`)
+```
+
+### Isolation
+
+- One claude process per working directory
+- Strictly one task at a time in a single directory
+- Different directories run in parallel but don't interfere with each other
+
+### Limits
+
+- 10 tasks in the queue per workDir (spam protection)
+- 50 tasks total (overload protection)
+- 10-minute timeout per task (hang protection)
+
+---
+
+## Troubleshooting
+
+### Listener won't start
+
+```bash
+claude-notify-listener status
+# → Status: not running
+```
+
+Check:
+
+1. Does the config exist? `cat ~/.claude/notifier.config.json`
+2. Are `telegramToken` and `telegramChatId` present?
+3. Is there a `listener.projects` section?
+4. Logs: `claude-notify-listener logs`
+
+### Bot doesn't respond
+
+1. Is the listener running? `claude-notify-listener status`
+2. Is the chatId correct? Messages from other chats are ignored (check the log: `WARN Ignored message from chat ...`)
+3. Is the bot added to the chat? Write `/help` to the bot — if there's no response, check the token
+
+### Task is stuck
+
+```
+/cancel @project
+```
+
+Or restart the listener:
+
+```bash
+claude-notify-listener restart
+```
+
+The watchdog will automatically clear stale tasks on the next startup.
+
+### Claude can't find project files
+
+Check the path in the config:
+
+```
+/projects
+```
+
+Make sure the path exists and contains the correct repository.
+
+---
+
+## Full session example
+
+Suppose you have two projects: an API server and a web application.
+
+### Configuration
+
+```json
+{
+  "telegram": {
+    "token": "123456789:ABCdef...",
+    "chatId": "987654321"
+  },
+  "listener": {
+    "projects": {
+      "api": { "path": "/home/user/projects/api" },
+      "web": { "path": "/home/user/projects/web" }
+    }
+  }
+}
+```
+
+### Telegram session
+
+```
+=== 10:00 — Startup ===
+
+You (terminal): claude-notify-listener start
+              → Listener started (PID: 12345)
+
+=== 10:01 — First task ===
+
+You: @api add endpoint GET /users with pagination
+Bot: ⏳ [@api] Running: add endpoint GET /users with pagination
+
+    Behind the scenes: process started
+    claude -p "add endpoint GET /users with pagination" --output-format text
+    cwd = /home/user/projects/api
+
+=== 10:02 — Task to another project (in parallel!) ===
+
+You: @web add a /users page that calls GET /users
+Bot: ⏳ [@web] Running: add a /users page that calls GET /users
+
+    Now two claude processes are running in parallel:
+    one in /home/user/projects/api, another in /home/user/projects/web
+
+=== 10:03 — Another task for api (queued) ===
+
+You: @api add tests for /users
+Bot: 📋 [@api] Queued (position 1).
+     Currently running: add endpoint GET /users with pagination
+
+=== 10:04 — Task in a worktree (in parallel with api/main!) ===
+
+You: @api/feature/auth add JWT authorization middleware
+Bot: 🌿 Created worktree feature/auth for project "api"
+     ⏳ [@api/feature/auth] Running: add JWT authorization middleware
+
+    Three claude processes running in parallel:
+    1. api/main     → GET /users
+    2. api/auth     → JWT middleware
+    3. web/main     → /users page
+
+=== 10:05 — Check status ===
+
+You: /status
+Bot: 📊 Status:
+     Uptime: 5m 12s
+
+     api:
+       main: ▶ add endpoint GET /users with pagination (4m 30s) +1 queued
+       feature/auth: ▶ add JWT authorization middleware (1m 05s)
+     web:
+       main: ▶ add a /users page... (3m 20s)
+
+=== 10:07 — web finished ===
+
+Bot: ✅ [@web] Done: add a /users page that calls GET /users
+
+     Created file src/pages/Users.vue with a user table.
+     Added route in src/router.js.
+     Uses fetch to /api/users with page and limit parameters.
+
+=== 10:09 — api/main finished, automatically starts the next task ===
+
+Bot: ✅ [@api] Done: add endpoint GET /users with pagination
+
+     Created controller src/controllers/users.js.
+     Added route GET /users in src/routes.js.
+     Supports query parameters: page, limit, sort.
+
+Bot: ⏳ [@api] Running: add tests for /users
+
+    Next task from the queue started automatically!
+
+=== 10:12 — Cancel a worktree task ===
+
+You: /cancel @api/feature/auth
+Bot: 🛑 [@api/feature/auth] Task cancelled
+
+=== 10:15 — api/main (tests) finished ===
+
+Bot: ✅ [@api] Done: add tests for /users
+
+     Created tests/users.test.js.
+     Covered cases: pagination, sorting, empty result, errors.
+
+=== 10:16 — Check history ===
+
+You: /history
+Bot: 📜 Recent tasks:
+
+     ✅ [@api] add tests for /users
+     🛑 [@api/feature/auth] add JWT authorization middleware
+     ✅ [@api] add endpoint GET /users with pagination
+     ✅ [@web] add a /users page...
+
+=== 10:17 — Remove unneeded worktree ===
+
+You: /rmworktree @api feature/auth
+Bot: 🗑 Worktree feature/auth removed from project "api"
+
+=== Evening — Shut down ===
+
+You: /stop
+Bot: 👋 Listener is shutting down...
+```

package/listener/listener.js

@@ -52,7 +52,8 @@ if (!config.listener?.projects || Object.keys(config.listener.projects).length =
 }
 
 const listenerConfig = config.listener;
-const taskTimeout = listenerConfig.taskTimeout || 600_000;
+const taskTimeoutMinutes = listenerConfig.taskTimeoutMinutes || 30;
+const taskTimeout = taskTimeoutMinutes * 60_000;
 
 const poller = new TelegramPoller(token, chatId, logger);
 const queue = new WorkQueue(
@@ -139,7 +140,7 @@ runner.on('timeout', async (workDir, task) => {
   const entry = queue.queues[workDir];
   const label = formatLabel(entry);
   await poller.sendMessage(
-    `⏰ [${label}] Timeout (${Math.round(taskTimeout / 60000)} min): ${escapeHtml(task.text)}`,
+    `⏰ [${label}] Task forcefully stopped — timeout exceeded (${Math.round(taskTimeout / 60000)} min): ${escapeHtml(task.text)}`,
     task.telegramMessageId,
   );
 

package/notifier/notifier.js

@@ -62,7 +62,7 @@ function loadConfig () {
     },
     webhookUrl: '',
     sendUserPromptToWebhook: false,
-    minSeconds: 15,
+    notifyAfterSeconds: 15,
     notifyOnWaiting: false,
     debug: false,
   };
@@ -83,8 +83,8 @@ function loadConfig () {
       if (user.voice) {
         config.voice = { ...config.voice, ...user.voice };
       }
-      if (typeof user.minSeconds === 'number') {
-        config.minSeconds = user.minSeconds;
+      if (typeof user.notifyAfterSeconds === 'number') {
+        config.notifyAfterSeconds = user.notifyAfterSeconds;
       }
       if (typeof user.notifyOnWaiting === 'boolean') {
         config.notifyOnWaiting = user.notifyOnWaiting;
@@ -138,6 +138,12 @@ function loadConfig () {
   if (process.env.CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK !== undefined) {
     config.sendUserPromptToWebhook = process.env.CLAUDE_NOTIFY_SEND_USER_PROMPT_TO_WEBHOOK === '1';
   }
+  if (process.env.CLAUDE_NOTIFY_AFTER_SECONDS !== undefined) {
+    const val = Number(process.env.CLAUDE_NOTIFY_AFTER_SECONDS);
+    if (!Number.isNaN(val)) {
+      config.notifyAfterSeconds = val;
+    }
+  }
 
   return config;
 }
@@ -666,7 +672,7 @@ process.stdin.on('end', async () => {
     duration = Math.round((Date.now() - session.start) / 1000);
   }
 
-  if (duration < config.minSeconds) {
+  if (duration < config.notifyAfterSeconds) {
     process.exit(0);
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-notification-plugin",
   "productName": "claude-notification-plugin",
-  "version": "1.0.66",
+  "version": "1.0.72",
   "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
   "type": "module",
   "engines": {