{"id":47055249,"url":"https://github.com/wangnov/tmux-watch","last_synced_at":"2026-03-12T03:05:30.031Z","repository":{"id":335889981,"uuid":"1147355651","full_name":"Wangnov/tmux-watch","owner":"Wangnov","description":"基于 tmux 输出的稳定性监测插件，可有效检测到tmux中的TUI（如Codex）是否完成了任务等待你的回应","archived":false,"fork":false,"pushed_at":"2026-02-01T18:04:11.000Z","size":232,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T01:55:53.299Z","etag":null,"topics":["claude-code","codex","openclaw","tmux"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wangnov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T16:11:46.000Z","updated_at":"2026-02-01T18:32:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Wangnov/tmux-watch","commit_stats":null,"previous_names":["wangnov/tmux-watch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Wangnov/tmux-watch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Ftmux-watch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Ftmux-watch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Ftmux-watch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Ftmux-watch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wangnov","download_url":"https://codeload.github.com/Wangnov/tmux-watch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wangnov%2Ftmux-watch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30413634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","openclaw","tmux"],"created_at":"2026-03-12T03:05:29.045Z","updated_at":"2026-03-12T03:05:30.014Z","avatar_url":"https://github.com/Wangnov.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-watch\n\n[中文](#zh) | [English](#en)\n\n\u003ca id=\"zh\"\u003e\u003c/a\u003e\n## 中文\n\n这是一个 [OpenClaw](https://github.com/OpenClaw/OpenClaw) 插件，用于基于 tmux 输出的稳定性监测：当某个 pane 的输出在连续 N 次捕获中保持不变时，触发告警并唤醒 Agent，总结并通知你。\n\n### 安装\n\n#### 从 npm 安装\n\n```bash\nopenclaw plugins install tmux-watch\n```\n\n#### 从本地目录安装\n\n```bash\nopenclaw plugins install /path/to/tmux-watch\n```\n\n或使用软链接（便于开发调试）：\n\n```bash\nopenclaw plugins install --link /path/to/tmux-watch\n```\n\n#### 从归档安装\n\n```bash\nopenclaw plugins install ./tmux-watch.tgz\n```\n\n\u003e 安装或启用插件后需要重启 Gateway。\n\n### 配置\n\n在 `~/.openclaw/openclaw.json` 中启用并配置：\n\n```json5\n{\n  \"plugins\": {\n    \"entries\": {\n      \"tmux-watch\": {\n        \"enabled\": true,\n        \"config\": {\n          \"socket\": \"/private/tmp/tmux-501/default\",\n          \"captureIntervalSeconds\": 10,\n          \"stableCount\": 6,\n          \"captureLines\": 50,\n          \"stripAnsi\": true,\n          \"maxOutputChars\": 4000,\n          \"notify\": {\n            \"mode\": \"targets\",\n            \"targets\": [\n              { \"channel\": \"gewe-openclaw\", \"target\": \"wxid_xxx\", \"label\": \"gewe\" }\n            ]\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n#### 配置项说明\n\n- `enabled`：是否启用插件（默认 `true`）。\n- `socket`：tmux socket 路径（必填）。\n- `captureIntervalSeconds`：每次捕获间隔（秒），默认 `10`。\n- `stableCount`：连续多少次捕获内容一致才触发告警，默认 `6`。总时长 = `captureIntervalSeconds × stableCount`（例如 `3 × 5 = 15s`）。\n- `pollIntervalMs`：**兼容字段**，捕获间隔（毫秒）。仅在需要与旧配置兼容时使用。\n- `stableSeconds`：**兼容字段**，稳定时长（秒）。会按当前捕获间隔换算成次数。\n- `captureLines`：从 pane 末尾向上截取的行数（默认 `50`）。\n- `stripAnsi`：是否剥离 ANSI 转义码（默认 `true`）。\n- `maxOutputChars`：通知中最多包含的输出字符数（默认 `4000`，超出将从末尾截断）。\n- `sessionKey`：覆盖默认 Agent 会话（通常不需要改）。\n- `notify.mode`：通知方式（`last` / `targets` / `targets+last`）。\n- `notify.targets`：通知目标数组（支持多个 channel，按数组顺序发送）。\n\n### 快速配置（onboarding）\n\n插件提供一个最小化向导，仅要求设置 `socket`：\n\n```bash\nopenclaw tmux-watch setup\n```\n\n你也可以手动指定：\n\n```bash\nopenclaw tmux-watch setup --socket \"/private/tmp/tmux-501/default\"\n```\n\n#### socket 如何获取\n\n进入目标 tmux 会话后执行：\n\n```bash\necho $TMUX\n```\n\n输出形如：\n\n```\n/private/tmp/tmux-501/default,3191,4\n```\n\n逗号前的路径就是 socket，配置到 `socket` 字段即可。\n\n### 订阅（通过 Agent 工具）\n\n```json\n{\n  \"action\": \"add\",\n  \"target\": \"session:0.0\",\n  \"label\": \"codex-tui\",\n  \"note\": \"本会话是AI编程TUI助手，卡住时总结最后输出并通知我\",\n  \"captureIntervalSeconds\": 3,\n  \"stableCount\": 5\n}\n```\n\n### 发送输入到 pane\n\n```bash\nopenclaw tmux-watch send test-dir:0.0 \"your text\"\n```\n\n默认行为等同于两步：先 `send-keys -l` 输入文本，再单独 `send-keys C-m` 提交。两步之间默认延迟 `20ms`。\n\n常用选项：\n\n- `--no-enter`：只输入，不回车。\n- `--delay-ms 50`：调整输入与回车之间的延迟。\n- `--socket /path/to/socket`：指定 tmux socket。\n- `--target ... --text ...`：用参数替代位置参数。\n\n### 捕获输出 / 截图\n\n```bash\n# 文本（默认）\nopenclaw tmux-watch capture session:0.0\n\n# 图片（临时文件，默认 10 分钟 TTL）\nopenclaw tmux-watch capture session:0.0 --format image\n\n# 文本 + 图片（可选 base64）\nopenclaw tmux-watch capture session:0.0 --format both --base64\n\n# 指定输出路径（不会自动清理）\nopenclaw tmux-watch capture session:0.0 --format image --output /tmp/pane.png\n```\n\n说明：\n\n- 图片优先使用 `cryosnap`，其次使用 `freeze`。若均未安装，请手动安装：\n  - `openclaw tmux-watch install cryosnap`\n  - `openclaw tmux-watch install freeze`\n- 临时图片默认 TTL 为 10 分钟，可用 `--ttl-seconds` 覆盖。\n- 可用 `--image-format png|svg|webp` 指定格式。\n\n### 依赖\n\n- 系统依赖：`tmux`\n- 可选截图依赖：`cryosnap`（优先）或 `freeze`\n- peer 依赖：`openclaw \u003e= 2026.1.29`\n\n\u003ca id=\"en\"\u003e\u003c/a\u003e\n## English\n\nThis is an [OpenClaw](https://github.com/OpenClaw/OpenClaw) plugin. tmux-watch monitors a tmux pane and triggers an alert when the output stays unchanged for N consecutive captures.\nThe agent is woken up to summarize the last output and notify you.\n\n### Install\n\n#### From npm\n\n```bash\nopenclaw plugins install tmux-watch\n```\n\n#### From a local directory\n\n```bash\nopenclaw plugins install /path/to/tmux-watch\n```\n\nOr use a symlink (for local development):\n\n```bash\nopenclaw plugins install --link /path/to/tmux-watch\n```\n\n#### From an archive\n\n```bash\nopenclaw plugins install ./tmux-watch.tgz\n```\n\n\u003e Restart the Gateway after installing or enabling the plugin.\n\n### Configuration\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json5\n{\n  \"plugins\": {\n    \"entries\": {\n      \"tmux-watch\": {\n        \"enabled\": true,\n        \"config\": {\n          \"socket\": \"/private/tmp/tmux-501/default\",\n          \"captureIntervalSeconds\": 10,\n          \"stableCount\": 6,\n          \"captureLines\": 50,\n          \"stripAnsi\": true,\n          \"maxOutputChars\": 4000,\n          \"notify\": {\n            \"mode\": \"targets\",\n            \"targets\": [\n              { \"channel\": \"gewe-openclaw\", \"target\": \"wxid_xxx\", \"label\": \"gewe\" }\n            ]\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n#### Configuration reference\n\n- `enabled`: Enable/disable the plugin (default `true`).\n- `socket`: tmux socket path (required).\n- `captureIntervalSeconds`: Capture interval in seconds (default `10`).\n- `stableCount`: Number of consecutive identical captures before alert (default `6`). Total duration = `captureIntervalSeconds × stableCount` (for example `3 × 5 = 15s`).\n- `pollIntervalMs`: **Legacy** capture interval in milliseconds. Use only for backward compatibility.\n- `stableSeconds`: **Legacy** stable duration in seconds. Converted into counts using the current interval.\n- `captureLines`: Lines captured from the bottom of the pane (default `50`).\n- `stripAnsi`: Strip ANSI escape codes (default `true`).\n- `maxOutputChars`: Max output chars in the notification (default `4000`, tail-truncated).\n- `sessionKey`: Override the default agent session (rare).\n- `notify.mode`: Notification mode (`last` / `targets` / `targets+last`).\n- `notify.targets`: Notification targets (multiple channels supported, sent in order).\n\n#### Find the socket\n\nInside the target tmux session:\n\n```bash\necho $TMUX\n```\n\nOutput looks like:\n\n```\n/private/tmp/tmux-501/default,3191,4\n```\n\nUse the path before the first comma as `socket`.\n\n### Quick setup (onboarding)\n\nThe plugin ships a minimal setup wizard that only requires the `socket`:\n\n```bash\nopenclaw tmux-watch setup\n```\n\nOr pass it explicitly:\n\n```bash\nopenclaw tmux-watch setup --socket \"/private/tmp/tmux-501/default\"\n```\n\n### Add a subscription (via agent tool)\n\n```json\n{\n  \"action\": \"add\",\n  \"target\": \"session:0.0\",\n  \"label\": \"codex-tui\",\n  \"note\": \"This is an AI coding TUI; summarize the last output and notify me if it stalls.\",\n  \"captureIntervalSeconds\": 3,\n  \"stableCount\": 5\n}\n```\n\n### Send input to a pane\n\n```bash\nopenclaw tmux-watch send test-dir:0.0 \"your text\"\n```\n\nDefault behavior is two-step: send text with `send-keys -l`, then send `C-m` (Enter) separately.\nThe default delay between the two steps is `20ms`.\n\nCommon options:\n\n- `--no-enter`: type only, do not press Enter.\n- `--delay-ms 50`: adjust the delay between text and Enter.\n- `--socket /path/to/socket`: specify tmux socket.\n- `--target ... --text ...`: use flags instead of positional args.\n\n### Capture output / snapshot\n\n```bash\n# Text only (default)\nopenclaw tmux-watch capture session:0.0\n\n# Image only (temporary file, 10-min TTL)\nopenclaw tmux-watch capture session:0.0 --format image\n\n# Both text + image (optional base64)\nopenclaw tmux-watch capture session:0.0 --format both --base64\n\n# Persist image to a path (no TTL cleanup)\nopenclaw tmux-watch capture session:0.0 --format image --output /tmp/pane.png\n```\n\nNotes:\n\n- Image capture prefers `cryosnap`, then falls back to `freeze`. If neither exists, install one:\n  - `openclaw tmux-watch install cryosnap`\n  - `openclaw tmux-watch install freeze`\n- Temporary images default to a 10-minute TTL; override with `--ttl-seconds`.\n- Use `--image-format png|svg|webp` to select the output format.\n\n### Requirements\n\n- System dependency: `tmux`\n- Optional image tools: `cryosnap` (preferred) or `freeze`\n- Peer dependency: `openclaw \u003e= 2026.1.29`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangnov%2Ftmux-watch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwangnov%2Ftmux-watch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangnov%2Ftmux-watch/lists"}