wait_for_text

TypeScript

Python
Ruby Unavailable
Lua Unavailable
TypeScript
Rust
Go
Java
.NET
C++
Swift

Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Wait until a pane prints something, streaming tmux’s notifications rather than polling. Use for output you did NOT author — another process, a person, a background job. For a command you wrote, use run_shell_command: it knows when the command ended and reports exit status, which no text match can. This discounts text this server itself typed into the pane, for as long as it is unsubmitted or was submitted within the last ten seconds, so a command you just sent cannot match its own echo — but a pane not yet reading input can still echo type-ahead back once it starts, so wait for a prompt before typing into a cold shell. Whatever happens you get back what the pane printed and why the wait ended — a timeout is never an empty answer.

All TypeScript tools · JSON · Source

Arguments

cursor optional · string: Start from a cursor an earlier capture_since or wait returned.
maxLines optional · integer: Keep at most this many lines, from the end. Defaults to the server limit.
paneId required · string: Stable pane id, e.g. %1.
patterns optional · array: Any one of these ends the wait. Omit to wait for any output at all.
regex optional · boolean: Interpret patterns using libtmux's bounded regular-expression grammar.
timeoutMs optional · integer: Clamped by the server ceiling; the result reports what was used.

Schemas

The schema defines required fields, nested values, defaults, and validation constraints.

Input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "cursor": {
      "description": "Start from a cursor an earlier capture_since or wait returned.",
      "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$",
      "type": "string"
    },
    "maxLines": {
      "description": "Keep at most this many lines, from the end. Defaults to the server limit.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "paneId": {
      "description": "Stable pane id, e.g. %1.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "patterns": {
      "description": "Any one of these ends the wait. Omit to wait for any output at all.",
      "items": {
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 64,
      "type": "array"
    },
    "regex": {
      "description": "Interpret patterns using libtmux's bounded regular-expression grammar.",
      "type": "boolean"
    },
    "timeoutMs": {
      "description": "Clamped by the server ceiling; the result reports what was used.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  "required": [
    "paneId"
  ],
  "type": "object"
}

Output schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "alreadyOnScreen": {
      "description": "The pattern is on the pane now but printed before this wait began, so the wait could not match it. Read it with capture_pane rather than waiting again.",
      "type": "boolean"
    },
    "cursor": {
      "anyOf": [
        {
          "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass to capture_since or another wait; null means the live stream cannot be resumed."
    },
    "droppedLines": {
      "description": "Output lines omitted by the result limit.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "effectiveTimeoutMs": {
      "description": "The timeout actually enforced, after clamping.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "matched": {
      "description": "The text that matched, or null.",
      "type": [
        "string",
        "null"
      ]
    },
    "missedBytes": {
      "description": "Retained output lost before this read; non-zero means the result is incomplete.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "omittedBytes": {
      "description": "Output bytes omitted by the result ceiling.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "outcome": {
      "description": "Why the wait ended. Read this rather than guessing from the output.",
      "enum": [
        "matched",
        "timed_out",
        "pane_died",
        "no_stream",
        "cancelled",
        "output_lost",
        "stream_lost"
      ],
      "type": "string"
    },
    "output": {
      "description": "The bounded tail of what the pane printed while waiting.",
      "type": "string"
    },
    "paneId": {
      "description": "Stable pane id, e.g. %1.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "returnedBytes": {
      "description": "UTF-8 bytes returned across output and screen.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "screen": {
      "description": "What the pane shows now after a miss, unless result limits omit it; see screenClamped.",
      "type": "string"
    },
    "screenClamped": {
      "description": "Whether result limits shortened the pane screen.",
      "type": "boolean"
    },
    "streamFailure": {
      "anyOf": [
        {
          "enum": [
            "connection_lost",
            "events_dropped",
            "expired",
            "hub_closed",
            "topology_changed"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Why the live stream ended, or null while it remained valid."
    }
  },
  "required": [
    "alreadyOnScreen",
    "cursor",
    "droppedLines",
    "effectiveTimeoutMs",
    "matched",
    "missedBytes",
    "omittedBytes",
    "outcome",
    "output",
    "paneId",
    "returnedBytes",
    "screen",
    "screenClamped",
    "streamFailure"
  ],
  "type": "object"
}

Tool annotations

{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": true,
  "readOnlyHint": false
}