tool MCPlatest

`wait_for_text`

wait_for_text( cursor?: string, maxLines?: integer, paneId: string, patterns?: Array<string>, regex?: boolean, timeoutMs?: integer, )

tool [source]¶

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.

MCP request method: tools/call Send wait_for_text as the tool name, with the arguments below.

Arguments#

cursor? (string) #

Start from a cursor an earlier capture_since or wait returned.

pattern
"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"
maxLines? (integer) #

Keep at most this many lines, from the end. Defaults to the server limit.

maximum
9007199254740991
exclusiveMinimum
0
paneId (string) #

Stable pane id, e.g. %1.

pattern
"^%\\d+$"
patterns? (Array<string>) #

Any one of these ends the wait. Omit to wait for any output at all.

maxItems
64
- Items (string) #
  
  minLength
  1
regex? (boolean) #

Interpret patterns using libtmux’s bounded regular-expression grammar.
timeoutMs? (integer) #

Clamped by the server ceiling; the result reports what was used.

maximum
9007199254740991
exclusiveMinimum
0

Result#

Returns object

alreadyOnScreen (boolean) #

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.
cursor (string | null) #

Pass to capture_since or another wait; null means the live stream cannot be resumed.

Matches one or more variants.
- Variant 1 (string) #
  
  pattern
  "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"
droppedLines (integer) #

Output lines omitted by the result limit.

minimum
-9007199254740991
maximum
9007199254740991
effectiveTimeoutMs (integer) #

The timeout actually enforced, after clamping.

minimum
-9007199254740991
maximum
9007199254740991
matched (string | null) #

The text that matched, or null.
missedBytes (integer) #

Retained output lost before this read; non-zero means the result is incomplete.

minimum
-9007199254740991
maximum
9007199254740991
omittedBytes (integer) #

Output bytes omitted by the result ceiling.

minimum
-9007199254740991
maximum
9007199254740991
outcome ("matched" | "timed_out" | "pane_died" | "no_stream" | "cancelled" | "output_lost" | "stream_lost") #

Why the wait ended. Read this rather than guessing from the output.
output (string) #

The bounded tail of what the pane printed while waiting.
paneId (string) #

Stable pane id, e.g. %1.

pattern
"^%\\d+$"
returnedBytes (integer) #

UTF-8 bytes returned across output and screen.

minimum
-9007199254740991
maximum
9007199254740991
screen (string) #

What the pane shows now after a miss, unless result limits omit it; see screenClamped.
screenClamped (boolean) #

Whether result limits shortened the pane screen.
streamFailure ("connection_lost" | "events_dropped" | "expired" | "hub_closed" | "topology_changed" | null) #

Why the live stream ended, or null while it remained valid.

No other properties are accepted.

Annotations#

destructiveHint: true
idempotentHint: false
openWorldHint: true
readOnlyHint: false

Protocol data#

Use the complete advertised contract for validation and client integration.

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"
}

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

`wait_for_text`

Arguments#

Result#

Annotations#

Protocol data#