libtmux_mcp.tools.pane_tools.wait_for_text

Description#

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.

Notes

Matching happens in Python, never in tmux. Patterns are never interpolated into a tmux format string: tmux's format parser treats # and } structurally, so an ordinary regex quantifier corrupts field parsing and a pattern ending in # swallows the rest of the format. Only fixed literal formats reach tmux.

Every tmux call is timeout-bounded. Reads are spawned with asyncio.create_subprocess_exec and bounded against the wait's own deadline, rather than going through libtmux's untimed Popen.communicate(). Nothing in this path runs on a worker thread, so a wedged tmux server can neither pin the event loop nor hang interpreter shutdown.

Alternate screen / pagers suppress matching. Inside less or any full-screen program, capture-pane returns the program's painted rows, so matching them would report text the program had already drawn. Matching is skipped for as long as the alternate screen lasts and the result comes back as alternate_screen rather than timeout — read the screen, don't retry the wait.

Scrollback rollover detection is partial. The tool raises when hsize shrinks below the entry value (clear-history, and any rollover whose dip is observable between polls). It does not reliably detect grid_collect_history trim during continuous output; a runtime ctx.warning fires when sampled state enters the trim-risk band. Use wait_for_channel when correctness matters more than convenience.