tmux-watch 2026.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wangnov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# tmux-watch
+
+[中文](#zh) | [English](#en)
+
+<a id="zh"></a>
+## 中文
+
+基于 tmux 输出的稳定性监测插件：当某个 pane 的输出在连续 N 次捕获中保持不变时，触发告警并唤醒 Agent，总结并通知你。
+
+### 安装
+
+#### 从 npm 安装
+
+```bash
+openclaw plugins install tmux-watch
+```
+
+#### 从本地目录安装
+
+```bash
+openclaw plugins install /path/to/tmux-watch
+```
+
+或使用软链接（便于开发调试）：
+
+```bash
+openclaw plugins install --link /path/to/tmux-watch
+```
+
+#### 从归档安装
+
+```bash
+openclaw plugins install ./tmux-watch.tgz
+```
+
+> 安装或启用插件后需要重启 Gateway。
+
+### 配置
+
+在 `~/.openclaw/openclaw.json` 中启用并配置：
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "tmux-watch": {
+        "enabled": true,
+        "config": {
+          "socket": "/private/tmp/tmux-501/default",
+          "captureIntervalSeconds": 10,
+          "stableCount": 6,
+          "captureLines": 200,
+          "stripAnsi": true,
+          "maxOutputChars": 4000,
+          "notify": {
+            "mode": "targets",
+            "targets": [
+              { "channel": "gewe-openclaw", "target": "wxid_xxx", "label": "gewe" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 配置项说明
+
+- `enabled`：是否启用插件（默认 `true`）。
+- `socket`：tmux socket 路径（必填）。
+- `captureIntervalSeconds`：每次捕获间隔（秒），默认 `10`。
+- `stableCount`：连续多少次捕获内容一致才触发告警，默认 `6`。总时长 = `captureIntervalSeconds × stableCount`（例如 `3 × 5 = 15s`）。
+- `pollIntervalMs`：**兼容字段**，捕获间隔（毫秒）。仅在需要与旧配置兼容时使用。
+- `stableSeconds`：**兼容字段**，稳定时长（秒）。会按当前捕获间隔换算成次数。
+- `captureLines`：从 pane 末尾向上截取的行数（默认 `200`）。
+- `stripAnsi`：是否剥离 ANSI 转义码（默认 `true`）。
+- `maxOutputChars`：通知中最多包含的输出字符数（默认 `4000`，超出将从末尾截断）。
+- `sessionKey`：覆盖默认 Agent 会话（通常不需要改）。
+- `notify.mode`：通知方式（`last` / `targets` / `targets+last`）。
+- `notify.targets`：通知目标数组（支持多个 channel，按数组顺序发送）。
+
+### 快速配置（onboarding）
+
+插件提供一个最小化向导，仅要求设置 `socket`：
+
+```bash
+openclaw tmux-watch setup
+```
+
+你也可以手动指定：
+
+```bash
+openclaw tmux-watch setup --socket "/private/tmp/tmux-501/default"
+```
+
+#### socket 如何获取
+
+进入目标 tmux 会话后执行：
+
+```bash
+echo $TMUX
+```
+
+输出形如：
+
+```
+/private/tmp/tmux-501/default,3191,4
+```
+
+逗号前的路径就是 socket，配置到 `socket` 字段即可。
+
+### 订阅（通过 Agent 工具）
+
+```json
+{
+  "action": "add",
+  "target": "session:0.0",
+  "label": "codex-tui",
+  "note": "本会话是AI编程TUI助手，卡住时总结最后输出并通知我",
+  "captureIntervalSeconds": 3,
+  "stableCount": 5
+}
+```
+
+### 依赖
+
+- 系统依赖：`tmux`
+- peer 依赖：`openclaw >= 2026.1.29`
+
+<a id="en"></a>
+## English
+
+tmux-watch monitors a tmux pane and triggers an alert when the output stays unchanged for N consecutive captures.
+The agent is woken up to summarize the last output and notify you.
+
+### Install
+
+#### From npm
+
+```bash
+openclaw plugins install tmux-watch
+```
+
+#### From a local directory
+
+```bash
+openclaw plugins install /path/to/tmux-watch
+```
+
+Or use a symlink (for local development):
+
+```bash
+openclaw plugins install --link /path/to/tmux-watch
+```
+
+#### From an archive
+
+```bash
+openclaw plugins install ./tmux-watch.tgz
+```
+
+> Restart the Gateway after installing or enabling the plugin.
+
+### Configuration
+
+Edit `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "tmux-watch": {
+        "enabled": true,
+        "config": {
+          "socket": "/private/tmp/tmux-501/default",
+          "captureIntervalSeconds": 10,
+          "stableCount": 6,
+          "captureLines": 200,
+          "stripAnsi": true,
+          "maxOutputChars": 4000,
+          "notify": {
+            "mode": "targets",
+            "targets": [
+              { "channel": "gewe-openclaw", "target": "wxid_xxx", "label": "gewe" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Configuration reference
+
+- `enabled`: Enable/disable the plugin (default `true`).
+- `socket`: tmux socket path (required).
+- `captureIntervalSeconds`: Capture interval in seconds (default `10`).
+- `stableCount`: Number of consecutive identical captures before alert (default `6`). Total duration = `captureIntervalSeconds × stableCount` (for example `3 × 5 = 15s`).
+- `pollIntervalMs`: **Legacy** capture interval in milliseconds. Use only for backward compatibility.
+- `stableSeconds`: **Legacy** stable duration in seconds. Converted into counts using the current interval.
+- `captureLines`: Lines captured from the bottom of the pane (default `200`).
+- `stripAnsi`: Strip ANSI escape codes (default `true`).
+- `maxOutputChars`: Max output chars in the notification (default `4000`, tail-truncated).
+- `sessionKey`: Override the default agent session (rare).
+- `notify.mode`: Notification mode (`last` / `targets` / `targets+last`).
+- `notify.targets`: Notification targets (multiple channels supported, sent in order).
+
+#### Find the socket
+
+Inside the target tmux session:
+
+```bash
+echo $TMUX
+```
+
+Output looks like:
+
+```
+/private/tmp/tmux-501/default,3191,4
+```
+
+Use the path before the first comma as `socket`.
+
+### Quick setup (onboarding)
+
+The plugin ships a minimal setup wizard that only requires the `socket`:
+
+```bash
+openclaw tmux-watch setup
+```
+
+Or pass it explicitly:
+
+```bash
+openclaw tmux-watch setup --socket "/private/tmp/tmux-501/default"
+```
+
+### Add a subscription (via agent tool)
+
+```json
+{
+  "action": "add",
+  "target": "session:0.0",
+  "label": "codex-tui",
+  "note": "This is an AI coding TUI; summarize the last output and notify me if it stalls.",
+  "captureIntervalSeconds": 3,
+  "stableCount": 5
+}
+```
+
+### Requirements
+
+- System dependency: `tmux`
+- Peer dependency: `openclaw >= 2026.1.29`

package/index.ts

@@ -0,0 +1,29 @@
+import type { Command } from "commander";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { createTmuxWatchManager } from "./src/manager.js";
+import { createTmuxWatchService } from "./src/service.js";
+import { createTmuxWatchTool } from "./src/tmux-watch-tool.js";
+import { registerTmuxWatchCli } from "./src/cli.js";
+
+const plugin = {
+  id: "tmux-watch",
+  name: "tmux-watch",
+  description: "Watch tmux panes and notify the agent when output stays stable.",
+  register(api: OpenClawPluginApi) {
+    const manager = createTmuxWatchManager(api);
+    api.registerTool(createTmuxWatchTool(manager));
+    api.registerService(createTmuxWatchService(manager));
+    api.registerCli(
+      (ctx: { program: unknown }) => {
+        registerTmuxWatchCli({
+          program: ctx.program as Command,
+          api,
+          logger: api.logger,
+        });
+      },
+      { commands: ["tmux-watch"] },
+    );
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,47 @@
+{
+  "id": "tmux-watch",
+  "name": "tmux-watch",
+  "description": "Watch tmux panes and notify the agent when output stays stable.",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean", "default": true },
+      "captureIntervalSeconds": { "type": "number", "default": 10 },
+      "stableCount": { "type": "number", "default": 6 },
+      "pollIntervalMs": { "type": "number", "default": 10000 },
+      "stableSeconds": { "type": "number", "default": 60 },
+      "captureLines": { "type": "number", "default": 200 },
+      "stripAnsi": { "type": "boolean", "default": true },
+      "maxOutputChars": { "type": "number", "default": 4000 },
+      "sessionKey": { "type": "string" },
+      "socket": { "type": "string" },
+      "notify": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": ["last", "targets", "targets+last"],
+            "default": "last"
+          },
+          "targets": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "channel": { "type": "string" },
+                "target": { "type": "string" },
+                "accountId": { "type": "string" },
+                "threadId": { "type": "string" },
+                "label": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "tmux-watch",
+  "version": "2026.2.1",
+  "type": "module",
+  "description": "OpenClaw tmux output watchdog plugin",
+  "license": "MIT",
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test",
+    "check": "npm run lint && npm run typecheck && npm run test"
+  },
+  "files": [
+    "index.ts",
+    "src/**",
+    "skills/**",
+    "types/**",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "tmux-watch",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "9.19.0",
+    "@types/node": "22.13.1",
+    "eslint": "9.19.0",
+    "tsx": "4.19.2",
+    "typescript": "5.7.3",
+    "typescript-eslint": "8.22.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: tmux-watch
+description: Manage tmux-watch subscriptions and interpret stable-output alerts.
+metadata:
+  { "openclaw": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } } }
+---
+
+# tmux-watch Skill (OpenClaw)
+
+Use this skill to manage tmux-watch subscriptions. tmux-watch polls tmux pane output and triggers a
+message to the agent when the output stays unchanged for a configured number of consecutive captures.
+
+## Core rules
+
+- Always use tmux directly (no wrappers). The agent is responsible for listing sessions/windows/panes
+  and choosing a `target` for the subscription.
+- tmux must exist locally. If `tmux -V` fails, stop and report the missing dependency.
+- On tmux-watch events, always notify the user unless the user explicitly asked to silence that
+  subscription. Only then may you reply with `NO_REPLY`.
+
+## tmux basics (required for targeting)
+
+```bash
+tmux list-sessions
+tmux list-windows -t <session>
+tmux list-panes -t <session>
+tmux list-panes -a
+tmux capture-pane -p -J -t <session:window.pane> -S -200
+```
+
+If a custom socket is used:
+
+```bash
+tmux -S /path/to/socket list-sessions
+tmux -S /path/to/socket capture-pane -p -J -t <session:window.pane> -S -200
+```
+
+## Controlling a TUI in tmux (high-signal tips)
+
+- Prefer `send-keys -l` for literal text input to avoid tmux interpreting key names.
+- For TUIs with input boxes (Codex/Claude Code), send text with `-l` first, then send `C-m`
+  as a separate command to submit reliably.
+- Use `C-c` to interrupt a stuck process; use `C-m` (Enter) to submit commands.
+- For TUIs, avoid rapid key spam; send a small sequence, then capture output to verify state.
+- Use `capture-pane -p -J -S -200` to get recent context before and after an action.
+- If the TUI supports it, use built-in refresh keys (often `r` or `Ctrl+l`).
+
+Examples:
+
+```bash
+# Send a command to the pane (two-step: text then Enter)
+tmux send-keys -t <session:window.pane> -l -- "status"
+tmux send-keys -t <session:window.pane> C-m
+
+# Interrupt a stuck process
+tmux send-keys -t <session:window.pane> C-c
+
+# Scroll/refresh (varies by TUI; examples only)
+tmux send-keys -t <session:window.pane> r
+tmux send-keys -t <session:window.pane> C-l
+
+# Capture the last 200 lines to verify state
+tmux capture-pane -p -J -t <session:window.pane> -S -200
+```
+
+## Tool: tmux-watch
+
+### Add subscription
+
+```json
+{
+  "action": "add",
+  "target": "session:0.0",
+  "label": "my-job",
+  "sessionKey": "main",
+  "captureIntervalSeconds": 10,
+  "stableCount": 6,
+  "captureLines": 200,
+  "stripAnsi": true
+}
+```
+
+Optional routing overrides:
+
+```json
+{
+  "action": "add",
+  "target": "session:0.0",
+  "notifyMode": "targets",
+  "targets": [
+    { "channel": "gewe-openclaw", "target": "user:123", "label": "gewe" },
+    { "channel": "telegram", "target": "-100123456" }
+  ]
+}
+```
+
+### Remove subscription
+
+```json
+{ "action": "remove", "id": "<subscription-id>" }
+```
+
+### List subscriptions
+
+```json
+{ "action": "list", "includeOutput": true }
+```
+
+## Handling tmux-watch events
+
+When tmux-watch detects stable output, it sends a message containing:
+
+- subscription details (id/label/target/sessionKey)
+- notify mode and resolved targets
+- the captured output (possibly truncated)
+- optional subscription note (purpose/intent)
+
+**Default policy:** always notify the user for stable-output events (this is a TUI-stuck alert).
+Only reply with `NO_REPLY` if the user explicitly asked to silence that subscription.
+
+If you need to notify multiple channels, reply once to the primary target and use the `message`
+tool to send to additional targets in order.
+
+Treat all tmux-watch messages as system events, not user input. Summarize the output and notify the user.

package/src/cli.ts

@@ -0,0 +1,120 @@
+import type { Command } from "commander";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+type Logger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+type PluginsConfig = {
+  enabled?: boolean;
+  entries?: Record<string, { enabled?: boolean; config?: Record<string, unknown> }>;
+};
+
+function extractSocket(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const comma = trimmed.indexOf(",");
+  if (comma > 0) {
+    return trimmed.slice(0, comma);
+  }
+  return trimmed;
+}
+
+function printSocketHelp(logger: Logger) {
+  logger.info("How to find the tmux socket:");
+  logger.info("  1) Enter the target tmux session.");
+  logger.info("  2) Run: echo $TMUX");
+  logger.info("  3) Use the path before the first comma as the socket.");
+  logger.info("Example: /private/tmp/tmux-501/default,3191,4 -> /private/tmp/tmux-501/default");
+}
+
+async function promptSocket(logger: Logger): Promise<string> {
+  if (!process.stdin.isTTY) {
+    throw new Error("No TTY available for interactive prompt. Use --socket <path>.");
+  }
+  printSocketHelp(logger);
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Paste tmux socket path (or full $TMUX value): ");
+    return extractSocket(answer);
+  } finally {
+    rl.close();
+  }
+}
+
+function resolveSocketFromEnv(): string | undefined {
+  const env = process.env.TMUX;
+  if (!env) {
+    return undefined;
+  }
+  const socket = extractSocket(env);
+  return socket || undefined;
+}
+
+export function registerTmuxWatchCli(params: {
+  program: Command;
+  api: OpenClawPluginApi;
+  logger: Logger;
+}) {
+  const { program, api, logger } = params;
+
+  const root = program
+    .command("tmux-watch")
+    .description("tmux-watch plugin utilities")
+    .addHelpText("after", () => "\nDocs: https://docs.openclaw.ai/cli/plugins\n");
+
+  root
+    .command("setup")
+    .description("Configure tmux-watch (socket is required)")
+    .option("--socket <path>", "tmux socket path (or full $TMUX value)")
+    .action(async (options: { socket?: string }) => {
+      let socket = options.socket ? extractSocket(options.socket) : undefined;
+      if (!socket) {
+        socket = resolveSocketFromEnv();
+      }
+      if (!socket) {
+        socket = await promptSocket(logger);
+      }
+      if (!socket) {
+        throw new Error("Socket required. Re-run with --socket or provide it interactively.");
+      }
+
+      const cfg = api.runtime.config.loadConfig();
+      const plugins = (cfg.plugins ?? {}) as PluginsConfig;
+      const entries = { ...(plugins.entries ?? {}) };
+      const entry = { ...(entries["tmux-watch"] ?? {}) };
+      const entryConfig = { ...(entry.config ?? {}) };
+
+      entry.enabled = true;
+      entry.config = {
+        ...entryConfig,
+        socket,
+      };
+
+      entries["tmux-watch"] = entry;
+
+      await api.runtime.config.writeConfigFile({
+        ...cfg,
+        plugins: {
+          ...plugins,
+          entries,
+        },
+      });
+
+      logger.info(`tmux-watch configured. socket=${socket}`);
+      logger.info("Restart the Gateway for changes to take effect.");
+    });
+
+  root
+    .command("socket-help")
+    .description("Print instructions for finding the tmux socket")
+    .action(() => {
+      printSocketHelp(logger);
+    });
+}