-
Notifications
You must be signed in to change notification settings - Fork 116
Description
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.