tmux-watch 2026.2.4 → 2026.2.6

package/README.md

@@ -123,9 +123,49 @@ echo $TMUX
 }
 ```
 
+### 发送输入到 pane
+
+```bash
+openclaw tmux-watch send test-dir:0.0 "your text"
+```
+
+默认行为等同于两步：先 `send-keys -l` 输入文本，再单独 `send-keys C-m` 提交。两步之间默认延迟 `20ms`。
+
+常用选项：
+
+- `--no-enter`：只输入，不回车。
+- `--delay-ms 50`：调整输入与回车之间的延迟。
+- `--socket /path/to/socket`：指定 tmux socket。
+- `--target ... --text ...`：用参数替代位置参数。
+
+### 捕获输出 / 截图
+
+```bash
+# 文本（默认）
+openclaw tmux-watch capture session:0.0
+
+# 图片（临时文件，默认 10 分钟 TTL）
+openclaw tmux-watch capture session:0.0 --format image
+
+# 文本 + 图片（可选 base64）
+openclaw tmux-watch capture session:0.0 --format both --base64
+
+# 指定输出路径（不会自动清理）
+openclaw tmux-watch capture session:0.0 --format image --output /tmp/pane.png
+```
+
+说明：
+
+- 图片优先使用 `cryosnap`，其次使用 `freeze`。若均未安装，请手动安装：
+  - `openclaw tmux-watch install cryosnap`
+  - `openclaw tmux-watch install freeze`
+- 临时图片默认 TTL 为 10 分钟，可用 `--ttl-seconds` 覆盖。
+- 可用 `--image-format png|svg|webp` 指定格式。
+
 ### 依赖
 
 - 系统依赖：`tmux`
+- 可选截图依赖：`cryosnap`（优先）或 `freeze`
 - peer 依赖：`openclaw >= 2026.1.29`
 
 <a id="en"></a>
@@ -250,7 +290,48 @@ openclaw tmux-watch setup --socket "/private/tmp/tmux-501/default"
 }
 ```
 
+### Send input to a pane
+
+```bash
+openclaw tmux-watch send test-dir:0.0 "your text"
+```
+
+Default behavior is two-step: send text with `send-keys -l`, then send `C-m` (Enter) separately.
+The default delay between the two steps is `20ms`.
+
+Common options:
+
+- `--no-enter`: type only, do not press Enter.
+- `--delay-ms 50`: adjust the delay between text and Enter.
+- `--socket /path/to/socket`: specify tmux socket.
+- `--target ... --text ...`: use flags instead of positional args.
+
+### Capture output / snapshot
+
+```bash
+# Text only (default)
+openclaw tmux-watch capture session:0.0
+
+# Image only (temporary file, 10-min TTL)
+openclaw tmux-watch capture session:0.0 --format image
+
+# Both text + image (optional base64)
+openclaw tmux-watch capture session:0.0 --format both --base64
+
+# Persist image to a path (no TTL cleanup)
+openclaw tmux-watch capture session:0.0 --format image --output /tmp/pane.png
+```
+
+Notes:
+
+- Image capture prefers `cryosnap`, then falls back to `freeze`. If neither exists, install one:
+  - `openclaw tmux-watch install cryosnap`
+  - `openclaw tmux-watch install freeze`
+- Temporary images default to a 10-minute TTL; override with `--ttl-seconds`.
+- Use `--image-format png|svg|webp` to select the output format.
+
 ### Requirements
 
 - System dependency: `tmux`
+- Optional image tools: `cryosnap` (preferred) or `freeze`
 - Peer dependency: `openclaw >= 2026.1.29`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-watch",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "type": "module",
   "description": "OpenClaw tmux output watchdog plugin",
   "license": "MIT",

package/skills/SKILL.md

@@ -37,9 +37,7 @@ 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.
+- Prefer `openclaw tmux-watch send` for reliable input (two-step, default 20ms delay).
 - 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.
@@ -48,9 +46,8 @@ tmux -S /path/to/socket capture-pane -p -J -t <session:window.pane> -S -200
 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
+# Send a command via tmux-watch (default delay 20ms + Enter)
+openclaw tmux-watch send <session:window.pane> "status"
 
 # Interrupt a stuck process
 tmux send-keys -t <session:window.pane> C-c
@@ -63,46 +60,45 @@ tmux send-keys -t <session:window.pane> C-l
 tmux capture-pane -p -J -t <session:window.pane> -S -200
 ```
 
-## Screenshot tools (priority + install)
+## Screenshot capture (preferred)
+
+Use `openclaw tmux-watch capture` to capture text/images from a tmux target. The plugin selects
+`cryosnap` first, then falls back to `freeze`.
 
 Priority detection order:
 
-1. System-level PATH (`command -v cryosnap` / `command -v freeze`)
+1. System-level PATH (`cryosnap` / `freeze`)
 2. User-level bins (`~/.local/bin`, `~/bin`)
 3. OpenClaw tools dir (`$OPENCLAW_STATE_DIR/tools`, default `~/.openclaw/tools`)
 
-If cryosnap exists, use it. If not, use freeze. If neither exists, **auto-install cryosnap**.
-
-Install commands (downloads the latest GitHub release into the OpenClaw tools dir):
+If neither tool exists, return an error and ask the user to install one:
 
 ```bash
 openclaw tmux-watch install cryosnap
 openclaw tmux-watch install freeze
-openclaw tmux-watch update cryosnap
-openclaw tmux-watch update freeze
-openclaw tmux-watch remove cryosnap
-openclaw tmux-watch remove freeze
 ```
 
-### cryosnap (preferred)
+Examples:
 
 ```bash
-# tmux pane -> PNG
-cryosnap --tmux --tmux-args "-t %3 -S -200 -J" --config full -o out.png
-```
+# Text only (uses plugin defaults for lines/strip)
+openclaw tmux-watch capture <session:window.pane>
 
-Notes:
+# Image only (temporary file, auto-cleaned after 10 minutes)
+openclaw tmux-watch capture <session:window.pane> --format image
 
-- For zsh, wrap `%3` in quotes or escape `%` (e.g., `"-t %3 -S -200 -J"`).
-- You can pass `-t session:window.pane` instead of `%pane_id`.
+# Both text + image, include base64 (optional)
+openclaw tmux-watch capture <session:window.pane> --format both --base64
 
-### freeze (fallback)
-
-```bash
-# Capture ANSI text first, then render with freeze
-tmux capture-pane -p -J -e -t <session:window.pane> -S -200 | freeze -o out.png
+# Persist image to a path (no TTL cleanup)
+openclaw tmux-watch capture <session:window.pane> --format image --output /tmp/pane.png
 ```
 
+Notes:
+
+- Temporary images default to a 10-minute TTL. Override with `--ttl-seconds`.
+- Use `--image-format png|svg|webp` to select output format.
+
 ## Tool: tmux-watch
 
 ### Add subscription
@@ -147,6 +143,20 @@ Optional routing overrides:
 { "action": "list", "includeOutput": true }
 ```
 
+### Capture once
+
+```json
+{
+  "action": "capture",
+  "target": "session:0.0",
+  "format": "both",
+  "captureLines": 200,
+  "stripAnsi": true,
+  "imageFormat": "png",
+  "base64": false
+}
+```
+
 ## Handling tmux-watch events
 
 When tmux-watch detects stable output, it sends a message containing:

package/src/capture.ts

@@ -0,0 +1,445 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { TmuxWatchConfig } from "./config.js";
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { stripAnsi, truncateOutput } from "./text-utils.js";
+import { resolveBinaryName, resolveToolsDir, type ToolId } from "./tool-install.js";
+
+export type CaptureFormat = "text" | "image" | "both";
+export type ImageFormat = "png" | "svg" | "webp";
+
+export type CaptureParams = {
+  target: string;
+  socket?: string;
+  captureLines?: number;
+  stripAnsi?: boolean;
+  format?: string;
+  imageFormat?: string;
+  outputPath?: string;
+  base64?: boolean;
+  ttlSeconds?: number;
+  maxChars?: number;
+};
+
+export type CaptureResult = {
+  target: string;
+  format: CaptureFormat;
+  capturedAt: string;
+  text?: string;
+  textTruncated?: boolean;
+  imagePath?: string;
+  imageTool?: ToolId;
+  imageFormat?: ImageFormat;
+  imageBase64?: string;
+  temporary?: boolean;
+  ttlSeconds?: number;
+};
+
+type ToolLocation = {
+  id: ToolId;
+  path: string;
+  source: "path" | "user-bin" | "openclaw";
+};
+
+const DEFAULT_TTL_SECONDS = 600;
+const TEMP_DIR_NAME = "openclaw-tmux-watch";
+
+export function resolveCaptureFormat(raw?: string, outputPath?: string): CaptureFormat {
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (value === "text" || value === "image" || value === "both") {
+    return value;
+  }
+  if (outputPath && outputPath.trim()) {
+    return "image";
+  }
+  return "text";
+}
+
+export function resolveImageFormat(raw?: string, outputPath?: string): ImageFormat {
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (value === "png" || value === "svg" || value === "webp") {
+    return value;
+  }
+  const ext = outputPath ? path.extname(outputPath).slice(1).toLowerCase() : "";
+  if (ext === "png" || ext === "svg" || ext === "webp") {
+    return ext as ImageFormat;
+  }
+  return "png";
+}
+
+export function pickTool(candidates: ToolLocation[]): ToolLocation | null {
+  const cryosnap = candidates.find((tool) => tool.id === "cryosnap");
+  if (cryosnap) {
+    return cryosnap;
+  }
+  const freeze = candidates.find((tool) => tool.id === "freeze");
+  return freeze ?? null;
+}
+
+export async function captureTmux(params: {
+  api: OpenClawPluginApi;
+  config: TmuxWatchConfig;
+} & CaptureParams): Promise<CaptureResult> {
+  const target = params.target.trim();
+  if (!target) {
+    throw new Error("target required for capture");
+  }
+  const socket = normalizeSocket(params.socket ?? params.config.socket);
+  const format = resolveCaptureFormat(params.format, params.outputPath);
+  const captureLines = resolveCaptureLines(params.captureLines, params.config);
+  const stripOutput = resolveStripAnsi(params.stripAnsi, params.config);
+  const includeAnsi = format !== "text" || !stripOutput;
+
+  const rawOutput = await capturePaneOutput({
+    api: params.api,
+    target,
+    socket,
+    captureLines,
+    includeAnsi,
+  });
+
+  const capturedAt = new Date().toISOString();
+  const result: CaptureResult = {
+    target,
+    format,
+    capturedAt,
+  };
+
+  if (format !== "image") {
+    let text = rawOutput;
+    if (stripOutput) {
+      text = stripAnsi(text);
+    }
+    const maxChars = resolveMaxChars(params.maxChars, params.config);
+    if (maxChars > 0) {
+      const outputInfo = truncateOutput(text, maxChars);
+      result.text = outputInfo.text;
+      result.textTruncated = outputInfo.truncated;
+    } else {
+      result.text = text;
+      result.textTruncated = false;
+    }
+  }
+
+  if (format !== "text") {
+    const imageFormat = resolveImageFormat(params.imageFormat, params.outputPath);
+    const ttlSeconds = resolveTtlSeconds(params.ttlSeconds);
+    const image = await renderImage({
+      api: params.api,
+      output: rawOutput,
+      imageFormat,
+      outputPath: params.outputPath,
+      ttlSeconds,
+    });
+    result.imagePath = image.path;
+    result.imageTool = image.tool;
+    result.imageFormat = imageFormat;
+    result.temporary = image.temporary;
+    result.ttlSeconds = image.temporary ? ttlSeconds : undefined;
+    if (params.base64) {
+      const bytes = await fs.readFile(image.path);
+      result.imageBase64 = bytes.toString("base64");
+    }
+  }
+
+  return result;
+}
+
+type CapturePaneParams = {
+  api: OpenClawPluginApi;
+  target: string;
+  socket?: string;
+  captureLines: number;
+  includeAnsi: boolean;
+};
+
+async function capturePaneOutput(params: CapturePaneParams): Promise<string> {
+  const argv = params.socket
+    ? ["tmux", "-S", params.socket, "capture-pane", "-p", "-J", "-t", params.target]
+    : ["tmux", "capture-pane", "-p", "-J", "-t", params.target];
+  if (params.includeAnsi) {
+    argv.push("-e");
+  }
+  if (params.captureLines > 0) {
+    argv.push("-S", `-${params.captureLines}`);
+  }
+
+  try {
+    const result = await params.api.runtime.system.runCommandWithTimeout(argv, {
+      timeoutMs: 5000,
+    });
+    if (result.code !== 0) {
+      const err = (result.stderr ?? result.stdout ?? "").trim();
+      throw new Error(err ? `tmux capture failed: ${err}` : "tmux capture failed");
+    }
+    let output = result.stdout ?? "";
+    output = output.replace(/\r\n/g, "\n").trimEnd();
+    return output;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`tmux capture failed: ${message}`);
+  }
+}
+
+type RenderImageParams = {
+  api: OpenClawPluginApi;
+  output: string;
+  imageFormat: ImageFormat;
+  outputPath?: string;
+  ttlSeconds: number;
+};
+
+type RenderImageResult = {
+  path: string;
+  tool: ToolId;
+  temporary: boolean;
+};
+
+async function renderImage(params: RenderImageParams): Promise<RenderImageResult> {
+  const tool = await resolveRenderTool(params.api);
+  const outputPath = await resolveOutputPath(params.outputPath, params.imageFormat);
+  const tempDir = await ensureTempDir();
+  await cleanupTempDir(tempDir, params.ttlSeconds * 1000);
+
+  const inputPath = await writeTempInput(params.output, tempDir);
+  try {
+    if (tool.id === "cryosnap") {
+      await runCryosnap(params.api, tool.path, inputPath, outputPath);
+    } else {
+      await runFreeze(params.api, tool.path, inputPath, outputPath);
+    }
+  } finally {
+    await fs.rm(inputPath, { force: true });
+  }
+
+  if (!params.outputPath && params.ttlSeconds > 0) {
+    scheduleCleanup(outputPath, params.ttlSeconds * 1000);
+  }
+
+  return { path: outputPath, tool: tool.id, temporary: !params.outputPath };
+}
+
+async function runCryosnap(
+  api: OpenClawPluginApi,
+  toolPath: string,
+  inputPath: string,
+  outputPath: string,
+): Promise<void> {
+  const argv = [toolPath, "--language", "ansi", "-o", outputPath, inputPath];
+  const result = await api.runtime.system.runCommandWithTimeout(argv, {
+    timeoutMs: 120_000,
+  });
+  if (result.code !== 0) {
+    const err = (result.stderr ?? result.stdout ?? "").trim();
+    throw new Error(err ? `cryosnap failed: ${err}` : "cryosnap failed");
+  }
+}
+
+async function runFreeze(
+  api: OpenClawPluginApi,
+  toolPath: string,
+  inputPath: string,
+  outputPath: string,
+): Promise<void> {
+  const cmd = `cat -- ${shellQuote(inputPath)} | ${shellQuote(toolPath)} -o ${shellQuote(outputPath)}`;
+  const result = await api.runtime.system.runCommandWithTimeout(["bash", "-lc", cmd], {
+    timeoutMs: 120_000,
+  });
+  if (result.code !== 0) {
+    const err = (result.stderr ?? result.stdout ?? "").trim();
+    throw new Error(err ? `freeze failed: ${err}` : "freeze failed");
+  }
+}
+
+async function resolveRenderTool(api: OpenClawPluginApi): Promise<ToolLocation> {
+  const cryosnap = await resolveToolBinary(api, "cryosnap");
+  if (cryosnap) {
+    return cryosnap;
+  }
+  const freeze = await resolveToolBinary(api, "freeze");
+  if (freeze) {
+    return freeze;
+  }
+  throw new Error(
+    "No screenshot tool found. Install with `openclaw tmux-watch install cryosnap` or `openclaw tmux-watch install freeze`.",
+  );
+}
+
+async function resolveToolBinary(api: OpenClawPluginApi, id: ToolId): Promise<ToolLocation | null> {
+  const binaryName = resolveBinaryName(id);
+  const fromPath = await findInPath(binaryName);
+  if (fromPath) {
+    return { id, path: fromPath, source: "path" };
+  }
+
+  const home = os.homedir();
+  const userBins = [path.join(home, ".local", "bin"), path.join(home, "bin")];
+  for (const dir of userBins) {
+    const found = await findInDir(dir, binaryName);
+    if (found) {
+      return { id, path: found, source: "user-bin" };
+    }
+  }
+
+  const toolsDir = resolveToolsDir(api);
+  const openclawPath = await findInDir(toolsDir, binaryName);
+  if (openclawPath) {
+    return { id, path: openclawPath, source: "openclaw" };
+  }
+
+  return null;
+}
+
+async function findInPath(binaryName: string): Promise<string | null> {
+  const raw = process.env.PATH ?? "";
+  const paths = raw.split(path.delimiter).filter(Boolean);
+  for (const dir of paths) {
+    const found = await findInDir(dir, binaryName);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+async function findInDir(dir: string, binaryName: string): Promise<string | null> {
+  if (!dir) {
+    return null;
+  }
+  const candidate = path.join(dir, binaryName);
+  if (await isExecutable(candidate)) {
+    return candidate;
+  }
+  return null;
+}
+
+async function isExecutable(candidate: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(candidate);
+    if (!stat.isFile()) {
+      return false;
+    }
+    if (process.platform === "win32") {
+      return true;
+    }
+    await fs.access(candidate, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveCaptureLines(raw: unknown, config: TmuxWatchConfig): number {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return Math.max(10, Math.trunc(raw));
+  }
+  return Math.max(10, Math.trunc(config.captureLines));
+}
+
+function resolveStripAnsi(raw: unknown, config: TmuxWatchConfig): boolean {
+  return typeof raw === "boolean" ? raw : config.stripAnsi;
+}
+
+function resolveMaxChars(raw: unknown, config: TmuxWatchConfig): number {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return Math.max(0, Math.trunc(raw));
+  }
+  return Math.max(0, Math.trunc(config.maxOutputChars));
+}
+
+function resolveTtlSeconds(raw: unknown): number {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return Math.max(1, Math.trunc(raw));
+  }
+  if (typeof raw === "string" && raw.trim()) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) {
+      return Math.max(1, Math.trunc(parsed));
+    }
+  }
+  return DEFAULT_TTL_SECONDS;
+}
+
+function normalizeSocket(raw: string | undefined): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const comma = trimmed.indexOf(",");
+  if (comma > 0) {
+    return trimmed.slice(0, comma);
+  }
+  return trimmed;
+}
+
+async function ensureTempDir(): Promise<string> {
+  const dir = path.join(os.tmpdir(), TEMP_DIR_NAME);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+async function resolveOutputPath(outputPath: string | undefined, format: ImageFormat): Promise<string> {
+  const trimmed = outputPath?.trim();
+  if (!trimmed) {
+    const dir = await ensureTempDir();
+    return path.join(dir, `tmux-watch-${Date.now()}-${randomUUID()}.${format}`);
+  }
+  const ext = path.extname(trimmed);
+  const finalPath = ext ? trimmed : `${trimmed}.${format}`;
+  await fs.mkdir(path.dirname(finalPath), { recursive: true });
+  return finalPath;
+}
+
+async function writeTempInput(content: string, dir: string): Promise<string> {
+  const filePath = path.join(dir, `tmux-watch-input-${Date.now()}-${randomUUID()}.ansi`);
+  await fs.writeFile(filePath, content);
+  return filePath;
+}
+
+async function cleanupTempDir(dir: string, ttlMs: number): Promise<void> {
+  if (ttlMs <= 0) {
+    return;
+  }
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const now = Date.now();
+    await Promise.all(
+      entries.map(async (entry) => {
+        if (!entry.isFile()) {
+          return;
+        }
+        const fullPath = path.join(dir, entry.name);
+        try {
+          const stat = await fs.stat(fullPath);
+          if (now - stat.mtimeMs > ttlMs) {
+            await fs.rm(fullPath, { force: true });
+          }
+        } catch {
+          // ignore
+        }
+      }),
+    );
+  } catch {
+    // ignore
+  }
+}
+
+function scheduleCleanup(filePath: string, ttlMs: number): void {
+  if (ttlMs <= 0) {
+    return;
+  }
+  const timer = setTimeout(() => {
+    void fs.rm(filePath, { force: true });
+  }, ttlMs);
+  timer.unref?.();
+}
+
+function shellQuote(input: string): string {
+  return `'${input.replace(/'/g, `'"'"'`)}'`;
+}

package/src/cli.ts

@@ -2,6 +2,7 @@ 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";
+import { createTmuxWatchManager } from "./manager.js";
 import { installTool, removeTool, type ToolId } from "./tool-install.js";
 
 type Logger = {
@@ -66,6 +67,32 @@ function normalizeToolId(raw: string): ToolId {
   return normalized as ToolId;
 }
 
+function normalizeDelayMs(raw: unknown, fallback: number): number {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return Math.max(0, Math.trunc(raw));
+  }
+  if (typeof raw === "string" && raw.trim()) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) {
+      return Math.max(0, Math.trunc(parsed));
+    }
+  }
+  return fallback;
+}
+
+function normalizeNumber(raw: unknown): number | undefined {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return Math.trunc(raw);
+  }
+  if (typeof raw === "string" && raw.trim()) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) {
+      return Math.trunc(parsed);
+    }
+  }
+  return undefined;
+}
+
 export function registerTmuxWatchCli(params: {
   program: Command;
   api: OpenClawPluginApi;
@@ -127,6 +154,144 @@ export function registerTmuxWatchCli(params: {
       printSocketHelp(logger);
     });
 
+  root
+    .command("send")
+    .description("Send text to a tmux target (text then Enter)")
+    .argument("[target]", "tmux target (session:window.pane or %pane_id)")
+    .argument("[text...]", "text to send (can be multiple words)")
+    .option("--target <target>", "tmux target (overrides positional)")
+    .option("--text <text>", "text to send (overrides positional)")
+    .option("--socket <path>", "tmux socket path (or full $TMUX value)")
+    .option("--delay-ms <ms>", "delay between text and Enter (default: 20)", "20")
+    .option("--no-enter", "do not send Enter after text")
+    .action(
+      async (
+        targetArg: string | undefined,
+        textArgs: string[] | undefined,
+        options: {
+          target?: string;
+          text?: string;
+          socket?: string;
+          delayMs?: string;
+          enter?: boolean;
+        },
+      ) => {
+        const target = (options.target ?? targetArg ?? "").trim();
+        const textFromArgs =
+          Array.isArray(textArgs) && textArgs.length > 0 ? textArgs.join(" ") : "";
+        const text = (options.text ?? textFromArgs ?? "").trim();
+        if (!target || !text) {
+          logger.error("Usage: openclaw tmux-watch send <target> <text> [--no-enter]");
+          process.exitCode = 1;
+          return;
+        }
+
+        const socket = options.socket
+          ? extractSocket(options.socket)
+          : resolveSocketFromEnv();
+        const delayMs = normalizeDelayMs(options.delayMs, 20);
+        const enter = options.enter !== false;
+
+        const argvBase = socket ? ["tmux", "-S", socket] : ["tmux"];
+        const sendText = [...argvBase, "send-keys", "-t", target, "-l", "--", text];
+        const res = await api.runtime.system.runCommandWithTimeout(sendText, {
+          timeoutMs: 5000,
+        });
+        if (res.code !== 0) {
+          const err = (res.stderr ?? res.stdout ?? "").trim();
+          logger.error(err ? `tmux send-keys failed: ${err}` : "tmux send-keys failed");
+          process.exitCode = 1;
+          return;
+        }
+
+        if (enter) {
+          if (delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+          }
+          const sendEnter = [...argvBase, "send-keys", "-t", target, "C-m"];
+          const resEnter = await api.runtime.system.runCommandWithTimeout(sendEnter, {
+            timeoutMs: 2000,
+          });
+          if (resEnter.code !== 0) {
+            const err = (resEnter.stderr ?? resEnter.stdout ?? "").trim();
+            logger.error(err ? `tmux send-keys Enter failed: ${err}` : "tmux send-keys Enter failed");
+            process.exitCode = 1;
+            return;
+          }
+        }
+
+        logger.info(`Sent to ${target}${enter ? " (Enter)" : ""}.`);
+      },
+    );
+
+  root
+    .command("capture")
+    .description("Capture tmux output as text/image")
+    .argument("[target]", "tmux target (session:window.pane or %pane_id)")
+    .option("--target <target>", "tmux target (overrides positional)")
+    .option("--socket <path>", "tmux socket path (or full $TMUX value)")
+    .option("--lines <n>", "lines to capture (default: config)")
+    .option("--strip-ansi", "strip ANSI for text output")
+    .option("--keep-ansi", "keep ANSI in text output")
+    .option("--format <format>", "text | image | both")
+    .option("--image-format <format>", "png | svg | webp")
+    .option("--output <path>", "image output path (optional)")
+    .option("--base64", "include base64 for image output")
+    .option("--ttl-seconds <n>", "temporary image TTL in seconds (default: 600)")
+    .option("--max-chars <n>", "max characters for text output (default: config)")
+    .action(
+      async (
+        targetArg: string | undefined,
+        options: {
+          target?: string;
+          socket?: string;
+          lines?: string;
+          stripAnsi?: boolean;
+          keepAnsi?: boolean;
+          format?: string;
+          imageFormat?: string;
+          output?: string;
+          base64?: boolean;
+          ttlSeconds?: string;
+          maxChars?: string;
+        },
+      ) => {
+        const target = (options.target ?? targetArg ?? "").trim();
+        if (!target) {
+          logger.error("Usage: openclaw tmux-watch capture <target> [options]");
+          process.exitCode = 1;
+          return;
+        }
+
+        let stripAnsi: boolean | undefined;
+        if (options.stripAnsi) {
+          stripAnsi = true;
+        } else if (options.keepAnsi) {
+          stripAnsi = false;
+        }
+
+        try {
+          const manager = createTmuxWatchManager(api);
+          const result = await manager.capture({
+            target,
+            socket: options.socket ? extractSocket(options.socket) : undefined,
+            captureLines: normalizeNumber(options.lines),
+            stripAnsi,
+            format: options.format,
+            imageFormat: options.imageFormat,
+            outputPath: options.output,
+            base64: options.base64,
+            ttlSeconds: normalizeNumber(options.ttlSeconds),
+            maxChars: normalizeNumber(options.maxChars),
+          });
+          process.stdout.write(`${JSON.stringify({ ok: true, capture: result }, null, 2)}\n`);
+        } catch (err) {
+          logger.error(err instanceof Error ? err.message : String(err));
+          process.exitCode = 1;
+        }
+      },
+    );
+
   root
     .command("install")
     .description("Install cryosnap or freeze into the OpenClaw tools directory")

package/src/manager.ts

@@ -2,6 +2,8 @@ import type { OpenClawPluginApi, OpenClawPluginServiceContext } from "openclaw/p
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { captureTmux, type CaptureParams, type CaptureResult } from "./capture.js";
+import { stripAnsi, truncateOutput } from "./text-utils.js";
 import {
   DEFAULT_CAPTURE_INTERVAL_SECONDS,
   DEFAULT_STABLE_COUNT,
@@ -53,22 +55,23 @@ type WatchEntry = {
   runtime: WatchRuntime;
 };
 
-type ResolvedTarget = {
+export type ResolvedTarget = {
   channel: string;
   target: string;
   accountId?: string;
   threadId?: string | number;
   label?: string;
-  source: "targets" | "last";
+  source: "targets" | "last" | "last-fallback";
 };
 
-type SessionEntryLike = {
+export type SessionEntryLike = {
   deliveryContext?: {
     channel?: string;
     to?: string;
     accountId?: string;
     threadId?: string | number;
   };
+  updatedAt?: number;
   lastChannel?: string;
   lastTo?: string;
   lastAccountId?: string;
@@ -83,6 +86,7 @@ type MinimalConfig = {
 };
 
 const STATE_VERSION = 1;
+const INTERNAL_LAST_CHANNELS = new Set(["webchat", "tui"]);
 
 export class TmuxWatchManager {
   private readonly api: OpenClawPluginApi;
@@ -152,6 +156,14 @@ export class TmuxWatchManager {
     return items;
   }
 
+  async capture(params: CaptureParams): Promise<CaptureResult> {
+    await this.ensureTmuxAvailable();
+    if (!this.tmuxAvailable) {
+      throw new Error("tmux not available");
+    }
+    return captureTmux({ api: this.api, config: this.config, ...params });
+  }
+
   async addSubscription(input: Partial<TmuxWatchSubscription> & { target: string }) {
     await this.ensureLoaded();
     const id = input.id?.trim() || randomUUID();
@@ -455,60 +467,26 @@ export class TmuxWatchManager {
     }
 
     if (includeLast) {
-      const last = await this.resolveLastTarget(sessionKey);
-      if (last) {
-        targets.push({
-          ...last,
-          source: "last",
-        });
+      const lastTargets = await this.resolveLastTargets(sessionKey);
+      if (lastTargets.length > 0) {
+        targets.push(...lastTargets);
       }
     }
 
     return dedupeTargets(targets);
   }
 
-  private async resolveLastTarget(sessionKey: string): Promise<ResolvedTarget | null> {
-    const entry = await this.readSessionEntry(sessionKey);
-    if (!entry) {
-      return null;
-    }
-    const delivery = entry.deliveryContext ?? {};
-    const channel =
-      typeof delivery.channel === "string"
-        ? delivery.channel.trim()
-        : typeof entry.lastChannel === "string"
-          ? entry.lastChannel.trim()
-          : typeof entry.channel === "string"
-            ? entry.channel.trim()
-            : undefined;
-    const target =
-      typeof delivery.to === "string"
-        ? delivery.to.trim()
-        : typeof entry.lastTo === "string"
-          ? entry.lastTo.trim()
-          : undefined;
-    if (!channel || !target) {
-      return null;
+  private async resolveLastTargets(sessionKey: string): Promise<ResolvedTarget[]> {
+    const store = await this.readSessionStore(sessionKey);
+    if (!store) {
+      return [];
     }
-    const accountId =
-      typeof delivery.accountId === "string"
-        ? delivery.accountId.trim()
-        : typeof entry.lastAccountId === "string"
-          ? entry.lastAccountId.trim()
-          : undefined;
-    const threadId =
-      delivery.threadId ?? entry.lastThreadId ?? entry.origin?.threadId ?? undefined;
-    return {
-      channel,
-      target,
-      accountId: accountId || undefined,
-      threadId: parseThreadId(threadId),
-      label: undefined,
-      source: "last",
-    };
+    return resolveLastTargetsFromStore({ store, sessionKey });
   }
 
-  private async readSessionEntry(sessionKey: string): Promise<SessionEntryLike | null> {
+  private async readSessionStore(
+    sessionKey: string,
+  ): Promise<Record<string, SessionEntryLike> | null> {
     const agentId = resolveAgentIdFromSessionKey(sessionKey);
     const storePath = this.api.runtime.channel.session.resolveStorePath(
       this.api.config.session?.store,
@@ -520,8 +498,10 @@ export class TmuxWatchManager {
       if (!store || typeof store !== "object") {
         return null;
       }
-      return store[sessionKey] ?? store[sessionKey.toLowerCase()] ?? null;
-    } catch {
+      return store;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.api.logger.warn(`[tmux-watch] session store read failed: ${message}`);
       return null;
     }
   }
@@ -769,16 +749,127 @@ function normalizeSessionKey(input: string | undefined, cfg?: MinimalConfig) {
   return `agent:${normalizeAgentId(agentId)}:${lowered}`;
 }
 
-function hashOutput(output: string): string {
-  return createHash("sha256").update(output).digest("hex");
+type TargetSnapshot = {
+  channel: string;
+  target: string;
+  accountId?: string;
+  threadId?: string | number;
+};
+
+function isInternalLastChannel(channel: string | undefined): boolean {
+  if (!channel) {
+    return false;
+  }
+  return INTERNAL_LAST_CHANNELS.has(channel.trim().toLowerCase());
+}
+
+function extractTargetSnapshot(entry: SessionEntryLike): TargetSnapshot | null {
+  const delivery = entry.deliveryContext ?? {};
+  const channel =
+    typeof delivery.channel === "string"
+      ? delivery.channel.trim()
+      : typeof entry.lastChannel === "string"
+        ? entry.lastChannel.trim()
+        : typeof entry.channel === "string"
+          ? entry.channel.trim()
+          : undefined;
+  const target =
+    typeof delivery.to === "string"
+      ? delivery.to.trim()
+      : typeof entry.lastTo === "string"
+        ? entry.lastTo.trim()
+        : undefined;
+  if (!channel || !target) {
+    return null;
+  }
+  const accountId =
+    typeof delivery.accountId === "string"
+      ? delivery.accountId.trim()
+      : typeof entry.lastAccountId === "string"
+        ? entry.lastAccountId.trim()
+        : undefined;
+  const threadId =
+    delivery.threadId ?? entry.lastThreadId ?? entry.origin?.threadId ?? undefined;
+  return {
+    channel,
+    target,
+    accountId: accountId || undefined,
+    threadId,
+  };
+}
+
+function snapshotKey(snapshot: TargetSnapshot): string {
+  return [snapshot.channel, snapshot.target, snapshot.accountId ?? "", snapshot.threadId ?? ""].join(
+    "|",
+  );
+}
+
+function findLatestExternalTarget(
+  store: Record<string, SessionEntryLike>,
+  exclude: TargetSnapshot,
+): TargetSnapshot | null {
+  const excludeKey = snapshotKey(exclude);
+  let best: { updatedAt: number; target: TargetSnapshot } | null = null;
+  for (const entry of Object.values(store)) {
+    const snapshot = extractTargetSnapshot(entry);
+    if (!snapshot) {
+      continue;
+    }
+    if (isInternalLastChannel(snapshot.channel)) {
+      continue;
+    }
+    if (snapshotKey(snapshot) === excludeKey) {
+      continue;
+    }
+    const updatedAt = typeof entry.updatedAt === "number" ? entry.updatedAt : 0;
+    if (!best || updatedAt > best.updatedAt) {
+      best = { updatedAt, target: snapshot };
+    }
+  }
+  return best?.target ?? null;
+}
+
+function toResolvedTarget(
+  snapshot: TargetSnapshot,
+  source: ResolvedTarget["source"],
+): ResolvedTarget {
+  return {
+    channel: snapshot.channel,
+    target: snapshot.target,
+    accountId: snapshot.accountId,
+    threadId: parseThreadId(snapshot.threadId),
+    label: undefined,
+    source,
+  };
 }
 
-export function stripAnsi(input: string): string {
-  /* eslint-disable no-control-regex */
-  const sgr = new RegExp("\\u001b\\[[0-9;]*m", "g");
-  const osc8 = new RegExp("\\u001b]8;;.*?\\u001b\\\\|\\u001b]8;;\\u001b\\\\", "g");
-  /* eslint-enable no-control-regex */
-  return input.replace(osc8, "").replace(sgr, "");
+export function resolveLastTargetsFromStore(params: {
+  store: Record<string, SessionEntryLike>;
+  sessionKey: string;
+}): ResolvedTarget[] {
+  const entry =
+    params.store[params.sessionKey] ??
+    params.store[params.sessionKey.toLowerCase()] ??
+    null;
+  if (!entry) {
+    return [];
+  }
+  const primary = extractTargetSnapshot(entry);
+  if (!primary) {
+    return [];
+  }
+  if (!isInternalLastChannel(primary.channel)) {
+    return [toResolvedTarget(primary, "last")];
+  }
+  const fallback = findLatestExternalTarget(params.store, primary);
+  if (fallback) {
+    return [toResolvedTarget(fallback, "last-fallback")];
+  }
+  return [toResolvedTarget(primary, "last")];
+}
+
+function hashOutput(output: string): string {
+  return createHash("sha256").update(output).digest("hex");
 }
 
 function parseThreadId(value: unknown): string | number | undefined {
@@ -798,24 +889,7 @@ function parseThreadId(value: unknown): string | number | undefined {
   return trimmed;
 }
 
-export function truncateOutput(
-  text: string,
-  maxChars: number,
-): { text: string; truncated: boolean } {
-  if (!text) {
-    return { text: "", truncated: false };
-  }
-  if (text.length <= maxChars) {
-    return { text, truncated: false };
-  }
-  let tail = text.slice(-maxChars);
-  const firstNewline = tail.indexOf("\n");
-  if (firstNewline > 0 && firstNewline < tail.length - 1) {
-    tail = tail.slice(firstNewline + 1);
-  }
-  tail = tail.trimStart();
-  return { text: `...[truncated]\n${tail}`, truncated: true };
-}
+export { stripAnsi, truncateOutput };
 
 function dedupeTargets(targets: ResolvedTarget[]): ResolvedTarget[] {
   const seen = new Set<string>();

package/src/text-utils.ts

@@ -0,0 +1,26 @@
+export function stripAnsi(input: string): string {
+  /* eslint-disable no-control-regex */
+  const sgr = new RegExp("\\u001b\\[[0-9;]*m", "g");
+  const osc8 = new RegExp("\\u001b]8;;.*?\\u001b\\\\|\\u001b]8;;\\u001b\\\\", "g");
+  /* eslint-enable no-control-regex */
+  return input.replace(osc8, "").replace(sgr, "");
+}
+
+export function truncateOutput(
+  text: string,
+  maxChars: number,
+): { text: string; truncated: boolean } {
+  if (!text) {
+    return { text: "", truncated: false };
+  }
+  if (text.length <= maxChars) {
+    return { text, truncated: false };
+  }
+  let tail = text.slice(-maxChars);
+  const firstNewline = tail.indexOf("\n");
+  if (firstNewline > 0 && firstNewline < tail.length - 1) {
+    tail = tail.slice(firstNewline + 1);
+  }
+  tail = tail.trimStart();
+  return { text: `...[truncated]\n${tail}`, truncated: true };
+}

package/src/tmux-watch-tool.ts

@@ -1,7 +1,7 @@
 import type { NotifyMode, NotifyTarget } from "./config.js";
 import type { TmuxWatchManager, TmuxWatchSubscription } from "./manager.js";
 
-const ACTIONS = ["add", "remove", "list"] as const;
+const ACTIONS = ["add", "remove", "list", "capture"] as const;
 const NOTIFY_MODES = ["last", "targets", "targets+last"] as const;
 
 type ToolParams = {
@@ -18,6 +18,12 @@ type ToolParams = {
   stableSeconds?: number;
   captureLines?: number;
   stripAnsi?: boolean;
+  format?: string;
+  imageFormat?: string;
+  outputPath?: string;
+  base64?: boolean;
+  ttlSeconds?: number;
+  maxChars?: number;
   enabled?: boolean;
   notifyMode?: NotifyMode;
   targets?: NotifyTarget[];
@@ -70,7 +76,7 @@ export function createTmuxWatchTool(manager: TmuxWatchManager) {
   return {
     name: "tmux-watch",
     description:
-      "Manage tmux-watch subscriptions (add/remove/list) that monitor tmux pane output.",
+      "Manage tmux-watch subscriptions (add/remove/list) or capture tmux output.",
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -95,6 +101,15 @@ export function createTmuxWatchTool(manager: TmuxWatchManager) {
         stableSeconds: { type: "number", description: "Legacy: stable duration in seconds." },
         captureLines: { type: "number", description: "Lines to capture." },
         stripAnsi: { type: "boolean", description: "Strip ANSI escape codes." },
+        format: { type: "string", description: "Capture format: text, image, or both." },
+        imageFormat: { type: "string", description: "Image format: png, svg, webp." },
+        outputPath: { type: "string", description: "Image output path (optional)." },
+        base64: { type: "boolean", description: "Include base64 image output." },
+        ttlSeconds: {
+          type: "number",
+          description: "Temporary image TTL in seconds (default 600).",
+        },
+        maxChars: { type: "number", description: "Max characters for text output." },
         enabled: { type: "boolean", description: "Enable or disable subscription." },
         notifyMode: {
           type: "string",
@@ -173,6 +188,27 @@ export function createTmuxWatchTool(manager: TmuxWatchManager) {
             });
             return jsonResult({ ok: true, subscriptions: items });
           }
+          case "capture": {
+            const target = readString(params.target);
+            if (!target) {
+              throw new Error("target required for capture action");
+            }
+            const result = await manager.capture({
+              target,
+              socket: readString(params.socket),
+              captureLines:
+                typeof params.captureLines === "number" ? params.captureLines : undefined,
+              stripAnsi: typeof params.stripAnsi === "boolean" ? params.stripAnsi : undefined,
+              format: readString(params.format),
+              imageFormat: readString(params.imageFormat),
+              outputPath: readString(params.outputPath),
+              base64: typeof params.base64 === "boolean" ? params.base64 : undefined,
+              ttlSeconds:
+                typeof params.ttlSeconds === "number" ? params.ttlSeconds : undefined,
+              maxChars: typeof params.maxChars === "number" ? params.maxChars : undefined,
+            });
+            return jsonResult({ ok: true, capture: result });
+          }
           default: {
             params.action satisfies never;
             throw new Error(`Unknown action: ${String(params.action)}`);

package/src/tool-install.ts

@@ -151,7 +151,7 @@ export async function removeTool(params: {
   return { tool: spec.id, path: destPath, removed: true };
 }
 
-function resolveToolsDir(api: OpenClawPluginApi): string {
+export function resolveToolsDir(api: OpenClawPluginApi): string {
   const stateDir = resolveStateDir(api);
   return path.join(stateDir, "tools");
 }
@@ -164,7 +164,7 @@ function resolveStateDir(api: OpenClawPluginApi): string {
   return path.join(os.homedir(), ".openclaw");
 }
 
-function resolveBinaryName(base: string): string {
+export function resolveBinaryName(base: string): string {
   if (process.platform === "win32") {
     return `${base}.exe`;
   }