libtmux_mcp.tools.pane_tools.search_panes

API reference · Markdown

libtmux_mcp.tools.pane_tools.search_panes

( 11 parameters )

( pattern : str , regex : bool = False , session_name : str | None = None , session_id : str | None = None , match_case : bool = False , content_start : int | None = None , content_end : int | None = None , max_matched_lines_per_pane : int = SEARCH_DEFAULT_MAX_LINES_PER_PANE , limit : int | None = SEARCH_DEFAULT_LIMIT , offset : int = 0 , socket_name : str | None = None )

→ SearchPanesResult

function [source] ¶

function [source] ¶

libtmux_mcp.tools.pane_tools.search_panes

Search visible terminal text across all tmux panes.

Use when the user asks what panes 'contain', 'mention', or 'show' — e.g. 'find the pane with the pytest failure'. Searches each pane's visible terminal scrollback content (not editor or browser text) and returns panes where the pattern is found, with matching lines.

Bounded output contract ----------------------- The result is paginated at the pane level. The matching panes are sorted by pane_id and then sliced with offset / limit. Each matching pane's matched_lines is further tail-truncated to at most max_matched_lines_per_pane entries (most-recent lines preserved). Caps apply only to the slow path (pane.capture_pane(join_wrapped=True) + Python regex); the tmux fast path at #{C:pattern} returns pane IDs only and is already bounded by tmux. The slow path joins wrapped visual rows so long lines can match across the pane's wrap column. The fast path remains tmux's native visual-row search, so use regex=True or an explicit content range to force the slow path when wrap-spanning text matters.

Parameters

• pattern ( str ) – Text to search for in pane contents. Treated as literal text by default. Set regex=True to interpret as a regular expression.

• regex ( bool ) – Whether to interpret pattern as a regular expression. Default False (literal text matching).

• session_name ( str | None ) – Limit search to panes in this session.

• session_id ( str | None ) – Limit search to panes in this session (by ID).

• match_case ( bool ) – Whether to match case. Default False (case-insensitive).

• content_start ( int | None ) – Start line for capture. Negative values reach into scrollback.

• content_end ( int | None ) – End line for capture.

• max_matched_lines_per_pane ( int ) – Per-pane cap on matched_lines. Defaults to SEARCH_DEFAULT_MAX_LINES_PER_PANE.

• limit ( int | None ) – Maximum matching panes returned on this call. Defaults to SEARCH_DEFAULT_LIMIT. Pass None to disable the cap.

• offset ( int ) – Skip this many matching panes from the start. Use with limit for pagination.

• socket_name ( str | None ) – tmux socket name.

Returns

SearchPanesResult Paginated match list with truncated / truncated_panes / total_panes_matched / offset / limit fields.

Raises

• ExpectedToolError – If pattern is over SEARCH_MAX_PATTERN_LENGTH, does not compile, or if matching it against the captured lines exceeds SEARCH_MATCH_MAX_SECONDS in total. A pattern with nested quantifiers such as (a+)+ can backtrack for hours on one ordinary line; anchor it or search for a literal.