Search panes

search_panes

search_panes

readonly tool

Search for text across all pane contents.

Returns:

SearchPanesResult

Use when you need to find specific text across multiple panes — locating which pane has an error, finding a running process, or checking output without knowing which pane to look in.

Avoid when you already know the target pane — use capture_pane directly.

Side effects: None. Readonly.

Example:

{
  "tool": "search_panes",
  "arguments": {
    "pattern": "FAIL",
    "session_name": "dev"
  }
}

Response is a SearchPanesResult wrapper: the matching panes live under matches, and the wrapper fields (truncated, truncated_panes, total_panes_matched, offset, limit) support pagination. For larger result sets, iterate by re-calling with offset += len(matches); stop when truncated == false and truncated_panes == [].

Note

Migrating from the flat-list shape Earlier alpha releases returned a bare list[PaneContentMatch]. Clients iterating the old shape directly (e.g. for m in search_panes(...)) must switch to for m in search_panes(...).matches. See the CHANGES entry for context.

{
  "matches": [
    {
      "pane_id": "%0",
      "pane_current_command": "zsh",
      "pane_current_path": "/home/user/myproject",
      "window_id": "@0",
      "window_name": "editor",
      "session_id": "$0",
      "session_name": "dev",
      "matched_lines": [
        "FAIL: test_upload (AssertionError)",
        "3 tests: 2 passed, 1 failed"
      ],
      "is_caller": false
    }
  ],
  "truncated": false,
  "truncated_panes": [],
  "total_panes_matched": 1,
  "offset": 0,
  "limit": 500
}

Parameters

Parameter	Type	Required	Default	Description
pattern	str	yes	—	Text to search for in pane contents. Treated as literal text by default. Set regex=True to interpret as a regular expression.
regex	bool	no	False	Whether to interpret pattern as a regular expression. Default False (literal text matching).
session_name	str	no	—	Limit search to panes in this session.
session_id	str	no	—	Limit search to panes in this session (by ID).
match_case	bool	no	False	Whether to match case. Default False (case-insensitive).
content_start	int	no	—	Start line for capture. Negative values reach into scrollback.
content_end	int	no	—	End line for capture.
max_matched_lines_per_pane	int	no	50	Per-pane cap on matched_lines. Defaults to :data:SEARCH_DEFAULT_MAX_LINES_PER_PANE.
limit	int	no	500	Maximum matching panes returned on this call. Defaults to :data:SEARCH_DEFAULT_LIMIT. Pass None to disable the cap.
offset	int	no	0	Skip this many matching panes from the start. Use with limit for pagination.
socket_name	str	no	—	tmux socket name.