libtmux_mcp.tools.pane_tools.search_panes
- libtmux_mcp.tools.pane_tools.search_panesSearch
( 11 parameters )
Panes Result -
Search visible terminal text across all tmux panes.
Description#
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_idand then sliced withoffset/limit. Each matching pane'smatched_linesis further tail-truncated to at mostmax_matched_lines_per_paneentries (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 useregex=Trueor an explicit content range to force the slow path when wrap-spanning text matters.Notes
The deadline bounds pattern matching across the call, not the call: capturing each pane is a separate tmux round-trip outside it, and the work still grows with the number of panes in scope.
- Parameters
-
-
pattern(str) # – Text to search for in pane contents. Treated as literal text by default. Setregex=Trueto 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 onmatched_lines. Defaults toSEARCH_DEFAULT_MAX_LINES_PER_PANE. -
limit(int | None) # – Maximum matching panes returned on this call. Defaults toSEARCH_DEFAULT_LIMIT. PassNoneto disable the cap. -
offset(int) # – Skip this many matching panes from the start. Use withlimitfor pagination. -
socket_name(str | None) # – tmux socket name.
-
- Returns
-
SearchPanesResult Paginated match list with
truncated/truncated_panes/total_panes_matched/offset/limitfields. - Raises
-
-
Expected
Tool – IfError patternis overSEARCH_MAX_PATTERN_LENGTH, does not compile, or if matching it against the captured lines exceedsSEARCH_MATCH_MAX_SECONDSin total. A pattern with nested quantifiers such as(a+)+can backtrack for hours on one ordinary line; anchor it or search for a literal.
-