Skip to content

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

@tony

Description

@tony

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions