# libtmux_mcp.tools.pane_tools.wait_for_text

- **Module:** libtmux_mcp.tools.pane_tools
- **Package:** libtmux-mcp
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/wait.py#L455
- **Page:** https://libtmux.org/en/py/latest/mcp/reference/libtmux_mcp-tools-pane_tools-wait_for_text/

```
libtmux_mcp.tools.pane_tools.wait_for_text(patterns: list[str] | None = None, stop: list[str] | None = None, regex: bool = False, pane_id: str | None = None, session_name: str | None = None, session_id: str | None = None, window_id: str | None = None, timeout: float = 8.0, interval: float = 0.05, match_case: bool = False, socket_name: str | None = None, ctx: Context | None = None) -> WaitForTextResult
```

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`` 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`` (returns exit status)
or compose ``; tmux wait-for -S <channel>`` with ``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``.

## Parameters

- `patterns` (list[str] | None): 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.
- `stop` (list[str] | None): Failure patterns. A hit ends the wait immediately with
``outcome="stopped"`` and ``found=false``; ``matched_index``
says which entry fired.
- `regex` (bool): Interpret ``patterns`` and ``stop`` as regular expressions.
Default False (literal text).
- `pane_id` (str | None): Pane ID (e.g. '%1').
- `session_name` (str | None): Session name for pane resolution.
- `session_id` (str | None): Session ID (e.g. '$1') for pane resolution.
- `window_id` (str | None): Window ID for pane resolution.
- `timeout` (float): Requested seconds to wait. Default 8.0. Clamped by server
policy; see ``effective_timeout`` in the result.
- `interval` (float): Seconds between polls. Default 0.05 (50ms). Minimum 0.01.
- `match_case` (bool): Whether to match case. Default False (case-insensitive).
- `socket_name` (str | None): tmux socket name.
- `ctx` (Context | None): FastMCP context; when injected the tool reports progress to the
client. Omitted in tests.

## Returns

WaitForTextResult
    Match outcome, a bounded tail of what the pane printed, and the
    timeout actually enforced.