Wait for text¶

`wait_for_text`¶

wait_for_text

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

Returns:: WaitForTextResult

Use when you need to block until specific output appears — waiting for a server to start, a build to complete, or a prompt to return.

Avoid when the expected text may never appear — always set a reasonable timeout. For repeated observation or tailing, use capture_since; for command completion you control, use wait_for_channel.

Side effects: None. Readonly. Blocks until text appears or timeout.

Example:

{
  "tool": "wait_for_text",
  "arguments": {
    "patterns": ["Server listening"],
    "stop": ["Address already in use"],
    "pane_id": "%2",
    "timeout": 30
  }
}

patterns is a list; pass null to wait for any new output at all. A stop entry is a failure marker — a hit ends the wait immediately with outcome="stopped".

Response:

{
  "found": true,
  "outcome": "matched",
  "matched_index": 0,
  "matched_lines": [
    "Server listening on port 8000"
  ],
  "tail": [
    "Server listening on port 8000"
  ],
  "saw_new_output": true,
  "matched_at_entry": false,
  "alternate_screen": false,
  "pane_id": "%2",
  "elapsed_seconds": 0.002,
  "effective_timeout": 30.0
}

outcome states how the wait ended: matched, any_output, stopped, alternate_screen, or timeout. matched_index names which patterns or stop entry fired. matched_at_entry is true when a pattern was already on screen when the wait began and was excluded as stale paint.

effective_timeout is the timeout actually enforced. An over-large timeout is clamped to the server ceiling (LIBTMUX_MCP_WAIT_MAX_SECONDS, 30 s by default) rather than rejected, so this can be lower than what you asked for.

Matching is best-effort once polling enters tmux’s history-limit trim-risk band, because older scrollback can be discarded while the wait is active. The server reports that as an MCP warning notification; use wait_for_channel for deterministic command completion.

Parameters

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

Wait for text¶

wait_for_text¶

`wait_for_text`¶