libtmux_mcp.tools.pane_tools.wait_for_text

API reference · Markdown

libtmux_mcp.tools.pane_tools.wait_for_text

( 12 parameters )

( 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

functionasync [source] ¶

functionasync [source] ¶

libtmux_mcp.tools.pane_tools.wait_for_text

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.

Discussed in Python MCP examples , Python MCP topics