feat: Add search_pane_contents() using tmux's native content search

Open
#645 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
50/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
api, cli

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.

Description

enhancement

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.

Dominant language
Python
Stars
1.2k
Forks
127
Avg merge
2h 13m
Merged PRs (30d)
1

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from tmux-python/libtmux

All issues in tmux-python/libtmux

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.