# wait_for_text

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

> Wait for NEW output in a tmux pane, then return.

MCP is in development

Server behavior and tool contracts may change. Tool availability depends on the server configuration.

Wait for NEW output in a tmux pane, then return.

Polls until one of `patterns` appears on a line written *after* this call starts, one of `stop` appears (immediate failure exit), or the timeout expires. Pass `patterns=null` to wait for any new output at all. Use this instead of polling [`capture_pane`](https://libtmux.org/en/py/latest/mcp/tools/capture_pane/) in a loop.

Pre-existing scrollback is never matched, and neither is paint left below the cursor at entry — only rows written after the call began count. If a pattern was already on screen the result says so via `matched_at_entry`.

**Last resort: reserve for output you did not author.** Commands you send are AUTHORED — use [`run_command`](https://libtmux.org/en/py/latest/mcp/tools/run_command/) (returns exit status) or compose `; tmux wait-for -S <channel>` with [`wait_for_channel`](https://libtmux.org/en/py/latest/mcp/tools/wait_for_channel/) instead, both cheaper and exact. For unattributable recurring prompts or background log lines, bracket your own command with a unique sentinel (`cmd; echo __WAIT_$RANDOM__`) and wait for that.

`stop` is the cheap way to avoid burning the whole budget: pass the failure markers you already know (`"error:"`, `"FAILED"`, `"Traceback"`) and a failed run returns in milliseconds instead of at the ceiling.

The server caps `timeout`. An over-large value is not an error — the wait returns at the ceiling and reports `effective_timeout`.

[All Python tools](../) · [JSON](../wait_for_text.json) · [Source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L153)

## Arguments

* `interval` optional · number

  Seconds between polls. Default 0.05 (50ms). Minimum 0.01.

  Default: `0.05`.

* `match_case` optional · boolean

  Whether to match case. Default False (case-insensitive).

  Default: `false`.

* `pane_id` optional

  Pane ID (e.g. '%1').

  Default: `null`.

* `patterns` optional

  Success patterns; the first one to match ends the wait. Literal text unless \`\`regex=True\`\`. Omit or pass \`\`null\`\` to wait for any new output.

  Default: `null`.

* `regex` optional · boolean

  Interpret \`\`patterns\`\` and \`\`stop\`\` as regular expressions. Default False (literal text).

  Default: `false`.

* `session_id` optional

  Session ID (e.g. '$1') for pane resolution.

  Default: `null`.

* `session_name` optional

  Session name for pane resolution.

  Default: `null`.

* `socket_name` optional

  tmux socket name.

  Default: `null`.

* `stop` optional

  Failure patterns. A hit ends the wait immediately with \`\`outcome="stopped"\`\` and \`\`found=false\`\`; \`\`matched\_index\`\` says which entry fired.

  Default: `null`.

* `timeout` optional · number

  Requested seconds to wait. Default 8.0. Clamped by server policy; see \`\`effective\_timeout\`\` in the result.

  Default: `8`.

* `window_id` optional

  Window ID for pane resolution.

  Default: `null`.

## Schemas

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