tool MCPlatest

`wait_for_text`

wait_for_text( match_case?: boolean, pane: string, patterns?: Array<string> | null, regex?: boolean, seconds?: integer | null, stop?: Array<string> | null, )

tool [source]¶

Wait until a pane writes matching text. On tmux 3.7 or newer it reads the pane’s live output stream, so text that scrolls past between checks is still seen, and the returned text is that raw stream, not the rendered screen: a line redrawn in place repeats. Below 3.7 it polls the visible screen about every 120 ms and misses text that appears and scrolls off between two reads. capture_pane shows the screen. Prefer run_shell_command for commands you are sending yourself: it reports an exit status instead of guessing from output. Use this for output you did not author, such as a server logging that it is ready. A line this server itself types and submits — with send_keys, paste_text, or run_shell_command’s own dispatch — is discounted from a match for a short time afterward, so waiting for text you just sent does not match its own echo; output that happens to repeat the same words still does. A submitted line that wrapped across terminal rows is discounted as one line. A pattern still on the row being typed into, not yet submitted, reports outcome pending instead of matched, and one already on a completed row before this call attached reports present_at_entry. A pane or server that ends reports pane_closed; an observer stream that drops while the pane lives reports stream_lost. On 3.7 or newer, waiting owns an observer client until the wait ends. Each list accepts at most 32 patterns, each at most 4,096 bytes, using Rust’s linear-time regex engine. Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted.

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

Arguments#

match_case? = false (boolean) #

Match case. Off by default.
pane (string) #

The %-prefixed pane to watch.
patterns? (Array<string> | null) #

Text that ends the wait successfully. Omit to wait for any output.

maxItems
32
regex? = false (boolean) #

Read both lists as regular expressions rather than literal text.
seconds? (integer | null) #

How long to wait, in seconds. Defaults to 30, capped at 600.

minimum
0
stop? (Array<string> | null) #

Text that ends the wait as a failure, reported as stopped. Omit for none.

Give the failure markers you already know — error:, Traceback — and a failed run returns at once instead of at the deadline.

maxItems
32

No other arguments are accepted.

Result#

Returns object

bytes (integer) #

How many bytes arrived, before filtering or truncation.

minimum
0
matched_index (integer | null) #

Which pattern matched, indexed into the list it came from.

minimum
0
matched_pattern (string | null) #

The pattern that matched, as it was given.
outcome (WaitOutcome) #

How the wait finished.
pane (string) #

The pane that was watched.
text (string) #

Retained stream text, or captured screen text on the polling path.

Streamed results are not the rendered screen: escape sequences are removed and a line redrawn in place repeats. capture_pane shows the screen. Below tmux 3.7 this is the last visible screen read instead; a present-at-entry match can also return captured screen text.

Types#

How a wait for text finished.

Matches exactly one variant.

Variant 1 ("present_at_entry") #

A wanted pattern was already in the pane’s output before this began watching, on a row above the one still being typed into, and is not a line this server itself submitted moments earlier.

A wait only sees what a pane writes after it starts, so this is never folded into [Self::Matched]: the same pattern printed moments earlier — an earlier command’s own output, say — can already be sitting there, and a caller that treated that as a fresh match would act on something that happened before this call, not because of it. A line this server typed and submitted with send_keys is discounted rather than reported here or as [Self::Matched], for a short time after it was submitted.
Variant 2 ("pending") #

A wanted pattern’s only occurrence is the row still being typed into: text this server (or a person sharing the pane) sent and has not submitted, not anything that has run.

Submit it, then wait again: the next wait sees the command’s own output on a row above a new one still being typed into, which is [Self::PresentAtEntry] or [Self::Matched] depending on when it arrived, never this — and never the submitted line’s own echo, which stays discounted for a short time after.
Variant 3 ("matched") #

A pattern matched, in output that arrived after the wait attached.
Variant 4 ("stopped") #

A stop pattern matched, so the wait ended early.
Variant 5 ("deadline") #

The time the caller allowed ran out.
Variant 6 ("pane_closed") #

The pane stopped writing for good: it closed, or the server holding it exited. text holds the output seen up to then.
Variant 7 ("stream_lost") #

The control stream ended while the pane was still alive, for example because its client was detached.

Nothing says the pane stopped, only that this wait can no longer see it. Wait again to watch it afresh; text holds the output seen up to the loss. The polling path, used below tmux 3.7, has no stream to lose.
Variant 8 ("cancelled") #

The client withdrew the request while the wait was still running.

Annotations#

destructiveHint: false
idempotentHint: true
openWorldHint: true
readOnlyHint: true
title: "Wait For Pane Text"

Protocol data#

Use the complete advertised contract for validation and client integration.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "match_case": {
      "default": false,
      "description": "Match case. Off by default.",
      "type": "boolean"
    },
    "pane": {
      "description": "The `%`-prefixed pane to watch.",
      "type": "string"
    },
    "patterns": {
      "description": "Text that ends the wait successfully. Omit to wait for any output.",
      "items": {
        "type": "string"
      },
      "maxItems": 32,
      "type": [
        "array",
        "null"
      ]
    },
    "regex": {
      "default": false,
      "description": "Read both lists as regular expressions rather than literal text.",
      "type": "boolean"
    },
    "seconds": {
      "description": "How long to wait, in seconds. Defaults to 30, capped at 600.",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "stop": {
      "description": "Text that ends the wait as a failure, reported as `stopped`. Omit for\nnone.\n\nGive the failure markers you already know — `error:`, `Traceback` — and\na failed run returns at once instead of at the deadline.",
      "items": {
        "type": "string"
      },
      "maxItems": 32,
      "type": [
        "array",
        "null"
      ]
    }
  },
  "required": [
    "pane"
  ],
  "type": "object"
}

Output schema

{
  "$defs": {
    "WaitOutcome": {
      "description": "How a wait for text finished.",
      "oneOf": [
        {
          "const": "present_at_entry",
          "description": "A wanted pattern was already in the pane's output before this began\nwatching, on a row above the one still being typed into, and is not\na line this server itself submitted moments earlier.\n\nA wait only sees what a pane writes after it starts, so this is never\nfolded into [`Self::Matched`]: the same pattern printed moments\nearlier -- an earlier command's own output, say -- can already be\nsitting there, and a caller that treated that as a fresh match would\nact on something that happened before this call, not because of it.\nA line this server typed and submitted with `send_keys` is discounted\nrather than reported here or as [`Self::Matched`], for a short time\nafter it was submitted.",
          "type": "string"
        },
        {
          "const": "pending",
          "description": "A wanted pattern's only occurrence is the row still being typed\ninto: text this server (or a person sharing the pane) sent and has\nnot submitted, not anything that has run.\n\nSubmit it, then wait again: the next wait sees the command's own\noutput on a row above a new one still being typed into, which is\n[`Self::PresentAtEntry`] or [`Self::Matched`] depending on when it\narrived, never this -- and never the submitted line's own echo,\nwhich stays discounted for a short time after.",
          "type": "string"
        },
        {
          "const": "matched",
          "description": "A pattern matched, in output that arrived after the wait attached.",
          "type": "string"
        },
        {
          "const": "stopped",
          "description": "A stop pattern matched, so the wait ended early.",
          "type": "string"
        },
        {
          "const": "deadline",
          "description": "The time the caller allowed ran out.",
          "type": "string"
        },
        {
          "const": "pane_closed",
          "description": "The pane stopped writing for good: it closed, or the server holding it\nexited. `text` holds the output seen up to then.",
          "type": "string"
        },
        {
          "const": "stream_lost",
          "description": "The control stream ended while the pane was still alive, for example\nbecause its client was detached.\n\nNothing says the pane stopped, only that this wait can no longer see\nit. Wait again to watch it afresh; `text` holds the output seen up to\nthe loss. The polling path, used below tmux 3.7, has no stream to lose.",
          "type": "string"
        },
        {
          "const": "cancelled",
          "description": "The client withdrew the request while the wait was still running.",
          "type": "string"
        }
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "bytes": {
      "description": "How many bytes arrived, before filtering or truncation.",
      "minimum": 0,
      "type": "integer"
    },
    "matched_index": {
      "description": "Which pattern matched, indexed into the list it came from.",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "matched_pattern": {
      "description": "The pattern that matched, as it was given.",
      "type": [
        "string",
        "null"
      ]
    },
    "outcome": {
      "$ref": "#/$defs/WaitOutcome",
      "description": "How the wait finished."
    },
    "pane": {
      "description": "The pane that was watched.",
      "type": "string"
    },
    "text": {
      "description": "Retained stream text, or captured screen text on the polling path.\n\nStreamed results are not the rendered screen: escape sequences are\nremoved and a line redrawn in place repeats. `capture_pane` shows the\nscreen. Below tmux 3.7 this is the last visible screen read instead;\na present-at-entry match can also return captured screen text.",
      "type": "string"
    }
  },
  "required": [
    "pane",
    "outcome",
    "matched_index",
    "matched_pattern",
    "text",
    "bytes"
  ],
  "type": "object"
}

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

`wait_for_text`

Arguments#

Result#

Types#

`WaitOutcome`: "present_at_entry" | "pending" | "matched" | "stopped" | "deadline" | "pane_closed" | "stream_lost" | "cancelled"

Annotations#

Protocol data#

Arguments#

Result#

Types#

WaitOutcome: "present_at_entry" | "pending" | "matched" | "stopped" | "deadline" | "pane_closed" | "stream_lost" | "cancelled"

Annotations#

Protocol data#

`WaitOutcome`: "present_at_entry" | "pending" | "matched" | "stopped" | "deadline" | "pane_closed" | "stream_lost" | "cancelled"