claude-notification-plugin 1.1.52 → 1.1.55

package/listener/LISTENER-DETAILED.md

@@ -61,7 +61,7 @@ GET /getUpdates?timeout=30  ────►     "Let's wait up to 30 seconds,
      connection is open)
 
                                       After 15 sec a user
-                                      wrote "/proj1 fix bug"
+                                      wrote "&proj1 fix bug"
 
 ◄──── {"result": [{"message":...}]}   "There's a message, here it is!"
 
@@ -181,7 +181,7 @@ Running two listeners is impossible — the PID file prevents it. And this is im
 │  ┌───────┴────────┐    ┌───────┴───────┐   │
 │  │ MessageParser  │    │  PtyRunner    │   │
 │  │                │    │               │   │
-│  │ /proj/branch   │    │ PTY session   │   │
+│  │ &proj/branch   │    │ PTY session   │   │
 │  │ /commands      │    │ timeouts      │   │
 │  └────────────────┘    │ signal files  │   │
 │                        └───────────────┘   │
@@ -198,10 +198,10 @@ Running two listeners is impossible — the PID file prevents it. And this is im
 | 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 |
+| **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 |
 | **PtyRunner** | `pty-runner.js` | Runs Claude in an interactive PTY session (via `node-pty`). Reuses sessions across tasks. Receives results via hook signal files. Monitors timeouts. 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 |
+| **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 operational log to `~/.claude/.cc-n-listener.log`. Rotation when exceeding 5 MB (old file → `.log.old`) |
 | **TaskLogger** | `task-logger.js` | Writes task Q&A logs (questions to Claude and answers). Separate file per project/branch. Rotation at 5 MB |
 
@@ -223,20 +223,23 @@ MessageParser.parse(text)
        ├─ Starts with "/"? ──► Command
        │    ├─ /status, /queue, /cancel, /drop, /clear, /newsession
        │    ├─ /projects, /worktrees, /worktree, /rmworktree
-       │    ├─ /history, /help, /stop
+       │    ├─ /history, /help, /menu, /start, /stop, /pty
        │    └─ Execute → reply in Telegram
+       │    └─ Unknown /command → reply "Unknown command"
        │
-       └─ 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"
+       ├─ Starts with "&"? ──► Task (project-targeted)
+       │    │
+       │    ├─ "&proj1/feature/auth fix bug"
+       │    │    → project = "proj1"
+       │    │    → branch = "feature/auth"
+       │    │    → text = "fix bug"
+       │    │
+       │    └─ "&proj1 fix bug"
+       │         → project = "proj1"
+       │         → branch = null (main)
+       │         → text = "fix bug"
+       │
+       └─ Otherwise ──► Task (default project)
             │
             └─ "fix bug"
                  → project = "default"
@@ -363,9 +366,9 @@ Each project is an alias (short name) + path to a directory on disk:
 }
 ```
 
-Now in Telegram you can write `/api refactor the code`, and Claude will run in the `/home/user/projects/api-server` directory.
+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` prefix go to it:
+The **`default`** alias is special. Messages without `&project` prefix go to it:
 
 ```json
 {
@@ -384,9 +387,9 @@ The **`default`** alias is special. Messages without `/project` prefix go to it:
 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 /project prefix       ← task in the "default" project
+&project task                      ← task in the main worktree of the project
+&project/branch task               ← task in the worktree of a specific branch
+task without &project prefix       ← task in the "default" project
 ```
 
 ### Examples
@@ -397,25 +400,25 @@ add a README to the project
 → runs in the `default` project (if configured)
 
 ```
-/api fix the authentication bug
+&api fix the authentication bug
 ```
 → runs in `/home/user/projects/api-server`
 
 ```
-/api/feature/payments add Stripe integration
+&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
+&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
+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** → sends task to the PTY session immediately, replies with `⏳ Running...`
@@ -451,8 +454,8 @@ api-server/                        ← main worktree, branch main
 **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.
+- `&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"
@@ -472,7 +475,7 @@ 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:
+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`
@@ -490,9 +493,9 @@ On startup, the listener scans each project with `git worktree list` and picks u
 ### 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
+/worktree &api/feature/payments     ← create a worktree
+/worktrees &api                     ← list all worktrees for a project
+/rmworktree &api/feature/payments   ← remove a worktree
 ```
 
 ---
@@ -510,41 +513,41 @@ 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
+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
+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).
+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).
+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
+10:05  Bot: ✅ [&web] Done: update dependencies
             <result>
        (web/main: active = null, queue = [])
 
-10:08  Bot: ✅ [/api] Done: fix the router bug
+10:08  Bot: ✅ [&api] Done: fix the router bug
             <result>
-       Bot: ⏳ [/api] Running: add tests
+       Bot: ⏳ [&api] Running: add tests
        (api/main: active = "add tests", queue = ["refactor"])
        (next task started automatically!)
 
-10:15  Bot: ✅ [/api] Done: add tests
+10:15  Bot: ✅ [&api] Done: add tests
             <result>
-       Bot: ⏳ [/api] Running: refactor the code
+       Bot: ⏳ [&api] Running: refactor the code
        (api/main: active = "refactor", queue = [])
 
-10:25  Bot: ✅ [/api] Done: refactor the code
+10:25  Bot: ✅ [&api] Done: refactor the code
             <result>
        (api/main: active = null, queue = [])
        (all tasks completed)
@@ -561,7 +564,7 @@ While `active !== null`, all new tasks for this workDir go into the `queue`.
 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
+Bot: ⏰ [&api] Task forcefully stopped — timeout exceeded (30 min): refactor the code
 ```
 
 After a timeout, the next task from the queue starts automatically.
@@ -571,6 +574,7 @@ After a timeout, the next task from the queue starts automatically.
 ## Bot commands
 
 All commands start with `/` and execute instantly (they are not queued).
+Projects are referenced with the `&` prefix (e.g. `&api`, `&api/branch`).
 
 ### /status — project status
 
@@ -587,7 +591,7 @@ Bot: 📊 Status:
 ```
 
 ```
-You: /status /api
+You: /status &api
 Bot: 📊 Project "api":
 
      main:
@@ -604,7 +608,7 @@ Bot: 📊 Project "api":
 You: /queue
 Bot: 📋 Queues:
 
-     /api:
+     &api:
        ▶ fix the router bug
        1. add tests
        2. refactor the code
@@ -613,16 +617,16 @@ Bot: 📋 Queues:
 ### /cancel — stop a running task
 
 ```
-You: /cancel /api
-Bot: 🛑 [/api] Task cancelled. Starting next.
-     ⏳ [/api] Running: add tests
+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
+You: /cancel &api/feature/auth
+Bot: 🛑 [&api/feature/auth] Task cancelled
 ```
 
 ### /drop — remove from queue
@@ -630,7 +634,7 @@ Bot: 🛑 [/api/feature/auth] Task cancelled
 Removes a task that **hasn't started executing yet** (waiting in the queue):
 
 ```
-You: /drop /api 2
+You: /drop &api 2
 Bot: 🗑 Removed from queue: refactor the code
 ```
 
@@ -642,8 +646,8 @@ Removes all tasks from the queue (the active task continues running) and resets
 The next task will start a fresh Claude session:
 
 ```
-You: /clear /api
-Bot: 🧹 [/api] Queue cleared (3 tasks), session reset
+You: /clear &api
+Bot: 🧹 [&api] Queue cleared (3 tasks), session reset
 ```
 
 ### /newsession — reset session context
@@ -651,8 +655,8 @@ Bot: 🧹 [/api] Queue cleared (3 tasks), session reset
 Resets the session without touching the queue. The next task starts a fresh session:
 
 ```
-You: /newsession /api
-Bot: 🆕 [/api] Session reset (was #5 tasks, ctx 42%). Next task starts fresh.
+You: /newsession &api
+Bot: 🆕 [&api] Session reset (was #5 tasks, ctx 42%). Next task starts fresh.
 ```
 
 Use this when the context window is getting full or when you want Claude to "forget" previous work and start clean.
@@ -664,15 +668,15 @@ You: /projects
 Bot: 📂 Projects:
 
      @default → /home/user/main-project
-     /api → /home/user/projects/api-server
+     &api → /home/user/projects/api-server
        /feature/auth → ~/.claude/worktrees/api/feature-auth
-     /web → /home/user/projects/web-app
+     &web → /home/user/projects/web-app
 ```
 
 ### /worktrees — project worktrees
 
 ```
-You: /worktrees /api
+You: /worktrees &api
 Bot: 🌳 Worktrees for project "api":
      • main → /home/user/projects/api-server
      • feature/auth → ~/.claude/worktrees/api/feature-auth
@@ -682,7 +686,7 @@ Bot: 🌳 Worktrees for project "api":
 ### /worktree — create a worktree
 
 ```
-You: /worktree /api/feature/payments
+You: /worktree &api/feature/payments
 Bot: 🌿 Created worktree for project "api":
      Branch: feature/payments
      Path: ~/.claude/worktrees/api/feature-payments
@@ -691,7 +695,7 @@ Bot: 🌿 Created worktree for project "api":
 ### /rmworktree — remove a worktree
 
 ```
-You: /rmworktree /api/feature/payments
+You: /rmworktree &api/feature/payments
 Bot: 🗑 Worktree feature/payments removed from project "api"
 ```
 
@@ -699,7 +703,7 @@ 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
+     First /cancel &api/feature/payments
 ```
 
 ### /history — history
@@ -708,10 +712,10 @@ Bot: ❌ Cannot remove worktree: a task is running in it.
 You: /history
 Bot: 📜 Recent tasks:
 
-     ✅ [/api] fix the router bug
-     ✅ [/web] update dependencies
-     🛑 [/api/feature/auth] implement OAuth2
-     ✅ [/api] add tests
+     ✅ [&api] fix the router bug
+     ✅ [&web] update dependencies
+     🛑 [&api/feature/auth] implement OAuth2
+     ✅ [&api] add tests
 ```
 
 ### /stop — stop the listener
@@ -731,7 +735,7 @@ Shows real-time information about PTY sessions: state, buffer size, live console
 You: /pty
 Bot: 🖥 PTY Sessions:
 
-     /api
+     &api
      State: busy
      Buffer: 12480 bytes
      Elapsed: 2m 35s
@@ -744,7 +748,7 @@ Bot: 🖥 PTY Sessions:
 ```
 
 ```
-You: /pty /api
+You: /pty &api
 Bot: (same, but for a specific project)
 ```
 
@@ -782,7 +786,7 @@ Get-Content ~/.claude/myproject_main_pty.log -Wait -Tail 50
 
 ### /pty command
 
-Send `/pty` or `/pty /project` in Telegram to get instant diagnostics:
+Send `/pty` or `/pty &project` in Telegram to get instant diagnostics:
 - Session state (`busy` / `idle` / `starting`)
 - Buffer size in bytes
 - Elapsed time since task start
@@ -801,7 +805,7 @@ Send `/pty` or `/pty /project` in Telegram to get instant diagnostics:
    Telegram message → getUpdates() → parsing
 
 2. ROUTING
-   "/api/feature/auth task"
+   "&api/feature/auth task"
      → project = "api"
      → branch = "feature/auth"
      → workDir = ~/.claude/worktrees/api/feature-auth
@@ -847,6 +851,24 @@ Claude sees the project files, CLAUDE.md, .claude/settings.json, and everything
 
 Task results are received via Claude's `Stop` hook, which writes a signal file containing `last_assistant_message` — the clean final response (not the raw PTY output with spinners and tool calls).
 
+### Hook-based communication
+
+In listener mode (`CLAUDE_NOTIFY_FROM_LISTENER=1`), the plugin communicates with the PTY runner via signal files in `~/.claude/pty-signals/` instead of parsing PTY output. This provides structured, reliable data: error types, tool activity, compaction status, and permission auto-approval without fragile buffer pattern matching.
+
+Signal files by hook event:
+
+| Signal file | Hook event | Contents |
+|---|---|---|
+| `{sessionId}.json` | `Stop` | Completion: `lastAssistantMessage`, `cost`, `numTurns`, `durationMs` |
+| `err_{sessionId}.json` | `StopFailure` | API error: `error` type (`rate_limit`, `authentication_failed`, etc.), `errorDetails` |
+| `rdy_{sessionId}.json` | `SessionStart` | Session ready: `model`, `source` (`startup`/`resume`) |
+| `act_{sessionId}.json` | `PostToolUse` | Tool activity: `toolName`, `toolInput` (overwritten per tool call) |
+| `cmp_{sessionId}.json` | `PostCompact` | Context compaction: `summary`, `trigger` (`auto`/`manual`) |
+
+The `PermissionRequest` hook auto-approves permissions by returning JSON to stdout (no signal file needed).
+
+The PTY runner polls `~/.claude/pty-signals/` every 500ms and processes each signal by matching the `cwd` field to a known working directory.
+
 ### Session continuity
 
 When `continueSession` is enabled (default), the listener reuses the same PTY session for subsequent tasks in the same workDir. The Claude process stays alive between tasks, preserving full context — exactly like working in an interactive terminal.
@@ -992,7 +1014,7 @@ Check:
 ### Task is stuck
 
 ```
-/cancel /project
+/cancel &project
 ```
 
 Or restart the listener:
@@ -1029,7 +1051,7 @@ After many tasks in the same session, the context window fills up and responses
 The completion message shows `ctx N%` — when it's above ~80%, consider resetting:
 
 ```
-/newsession /project
+/newsession &project
 ```
 
 This starts a fresh session without clearing the task queue. You can also use `/clear` to reset both.
@@ -1079,8 +1101,8 @@ You (terminal): claude-notify listener start
 
 === 10:01 — First task ===
 
-You: /api add endpoint GET /users with pagination
-Bot: ⏳ [/api] Running: add endpoint GET /users with pagination
+You: &api add endpoint GET /users with pagination
+Bot: ⏳ [&api] Running: add endpoint GET /users with pagination
 
     Behind the scenes: PTY session created
     claude (interactive PTY) → task sent
@@ -1088,23 +1110,23 @@ Bot: ⏳ [/api] Running: add endpoint GET /users with pagination
 
 === 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
+You: &web add a /users page that calls GET /users
+Bot: ⏳ [&web] Running: add a /users page that calls GET /users
 
     Now two PTY sessions 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).
+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
+You: &api/feature/auth add JWT authorization middleware
 Bot: 🌿 Created worktree feature/auth for project "api"
-     ⏳ [/api/feature/auth] Running: add JWT authorization middleware
+     ⏳ [&api/feature/auth] Running: add JWT authorization middleware
 
     Three PTY sessions running in parallel:
     1. api/main     → GET /users
@@ -1125,7 +1147,7 @@ Bot: 📊 Status:
 
 === 10:07 — web finished ===
 
-Bot: ✅ [/web] Done: add a /users page that calls GET /users
+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.
@@ -1133,24 +1155,24 @@ Bot: ✅ [/web] Done: add a /users page that calls GET /users
 
 === 10:09 — api/main finished, automatically starts the next task ===
 
-Bot: ✅ [/api] Done: add endpoint GET /users with pagination
+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
+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
+You: /cancel &api/feature/auth
+Bot: 🛑 [&api/feature/auth] Task cancelled
 
 === 10:15 — api/main (tests) finished ===
 
-Bot: ✅ [/api] Done: add tests for /users
+Bot: ✅ [&api] Done: add tests for /users
 
      Created tests/users.test.js.
      Covered cases: pagination, sorting, empty result, errors.
@@ -1160,14 +1182,14 @@ Bot: ✅ [/api] Done: add tests for /users
 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...
+     ✅ [&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
+You: /rmworktree &api/feature/auth
 Bot: 🗑 Worktree feature/auth removed from project "api"
 
 === Evening — Shut down ===