Problem
libtmux has no high-level API for searching text visible in pane contents. Users must manually iterate panes and call capture_pane() on each — slow for many panes.
tmux native support
tmux's format system includes a C modifier that searches pane contents in C via window_pane_search() (in window.c). This reads directly from the internal grid data structure — no serialization or fork overhead.
The fastest programmatic approach is list-panes -f "#{C:pattern}", which:
- Runs content matching in C (not Python)
- Returns only matching panes
- Supports flags:
#{C/i:pattern} (case-insensitive), #{C/r:pattern} (POSIX regex), #{C/ri:pattern} (both)
This is the same mechanism behind find-window -C, but returns structured output instead of entering interactive window-tree mode.
Proposed API
# Server-wide search
server.search_pane_contents("error", case_sensitive=False)
# → list of Pane objects whose visible content matches
# Session-scoped search
session.search_pane_contents("error")
Implementation: call server.cmd('list-panes', '-a', '-f', '#{C/i:pattern}', '-F', '#{pane_id}'), then resolve matching pane IDs to Pane objects.
Context
The libtmux-mcp server has a search_panes MCP tool that would be a consumer of this API. Currently it calls server.cmd() directly — a proper API method would be cleaner.
Problem
libtmux has no high-level API for searching text visible in pane contents. Users must manually iterate panes and call
capture_pane()on each — slow for many panes.tmux native support
tmux's format system includes a
Cmodifier that searches pane contents in C viawindow_pane_search()(inwindow.c). This reads directly from the internal grid data structure — no serialization or fork overhead.The fastest programmatic approach is
list-panes -f "#{C:pattern}", which:#{C/i:pattern}(case-insensitive),#{C/r:pattern}(POSIX regex),#{C/ri:pattern}(both)This is the same mechanism behind
find-window -C, but returns structured output instead of entering interactive window-tree mode.Proposed API
Implementation: call
server.cmd('list-panes', '-a', '-f', '#{C/i:pattern}', '-F', '#{pane_id}'), then resolve matching pane IDs to Pane objects.Context
The libtmux-mcp server has a
search_panesMCP tool that would be a consumer of this API. Currently it callsserver.cmd()directly — a proper API method would be cleaner.