# wait_for_text

Source: https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/

> 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.

tool MCPlatest

MCP concept example

A working example of the core library. It can change without notice.

[What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha)

* **wait_for_text**( [cursor](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fcursor)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [patterns](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns)?: [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>, [regex](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fregex)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [timeoutMs](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FtimeoutMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), )

  tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/wait.ts#L503)][¶](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text)

  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](https://libtmux.org/en/ts/latest/mcp/tools/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[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.parameters)

  * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fcursor)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Start from a cursor an earlier [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) or wait returned.

    * pattern

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

  * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

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

    * maximum

      `9007199254740991`

    * exclusiveMinimum

      `0`

  * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Stable pane id, e.g. %1.

    * pattern

      `"^%\\d+$"`

  * **[`patterns`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>)

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

    * maxItems

      `64`

    - **[Items](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

      * minLength

        `1`

  * **[`regex`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fregex)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

    Interpret patterns using libtmux’s bounded regular-expression grammar.

  * **[`timeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FtimeoutMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

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

    * maximum

      `9007199254740991`

    * exclusiveMinimum

      `0`

  ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.result)

  Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")

  * **[`alreadyOnScreen`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FalreadyOnScreen)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

    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](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) rather than waiting again.

  * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fcursor)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"))

    Pass to [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) or another wait; null means the live stream cannot be resumed.

    Matches one or more variants.

    * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fcursor%2FanyOf%2F0)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

      * pattern

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

  * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    Output lines omitted by the result limit.

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`effectiveTimeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FeffectiveTimeoutMs)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    The timeout actually enforced, after clamping.

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`matched`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fmatched)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"))

    The text that matched, or null.

  * **[`missedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FmissedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

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

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`omittedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FomittedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    Output bytes omitted by the result ceiling.

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`outcome`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Foutcome)** ("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`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Foutput)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    The bounded tail of what the pane printed while waiting.

  * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Stable pane id, e.g. %1.

    * pattern

      `"^%\\d+$"`

  * **[`returnedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FreturnedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    UTF-8 bytes returned across output and screen.

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`screen`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fscreen)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

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

  * **[`screenClamped`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FscreenClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"))

    Whether result limits shortened the pane screen.

  * **[`streamFailure`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FstreamFailure)** ("connection_lost" | "events_dropped" | "expired" | "hub_closed" | "topology_changed" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"))

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

  No other properties are accepted.

  ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.annotations)

  * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint)

    `true`

  * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint)

    `false`

  * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint)

    `true`

  * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint)

    `false`

  ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.schemas)

  Use the complete advertised contract for validation and client integration.

  Input schema

  ```json
  {
    "$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

  ```json
  {
    "$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"
  }
  ```