# libtmux_mcp.tools.pane_tools.search_panes

- **Module:** libtmux_mcp.tools.pane_tools
- **Package:** libtmux-mcp
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/search.py#L137
- **Page:** https://libtmux.org/en/py/latest/mcp/reference/libtmux_mcp-tools-pane_tools-search_panes/

```
libtmux_mcp.tools.pane_tools.search_panes(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
```

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.