tmux-python / tmux-python/libtmux
feat: Add search_pane_contents() using tmux's native content search
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 127
- Avg merge
- 2h 13m
- Merged PRs (30d)
- 1
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the existing server.cmd('list-panes', ...) entry point and the libtmux-mcp search_panes consumer described in the issue. Confirm how matching pane IDs can be resolved to Pane objects, then verify that server- and session-scoped searches return only panes whose visible contents match the requested pattern and flags.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100