Skip to content

perf: Push QueryList filters to tmux via -f format filter #646

@tony

Description

@tony

Problem

server.panes.filter(pane_current_command__contains="vim") fetches ALL panes from tmux, then filters in Python. For servers with many sessions/windows, this is unnecessarily slow.

tmux native support

tmux's list-panes, list-windows, and list-sessions commands support a -f flag that applies a format-string filter server-side:

Filter panes by command (done in C, not Python):

$ tmux list-panes -a -f "#{m:*vim*,#{pane_current_command}}"

Filter panes by content (C-level grid search):

$ tmux list-panes -a -f "#{C:search_term}"

Case-insensitive metadata match:

$ tmux list-panes -a -f "#{m/i:*pattern*,#{window_name}}"

Format matching operators:

  • #{m:glob,text} — glob match (wraps with *...* for contains)
  • #{m/i:glob,text} — case-insensitive glob
  • #{m/r:regex,text} — POSIX extended regex
  • #{C:text} — content search (visible pane text)

Proposed approach

Add a method or option to push compatible QueryList filters into tmux's -f flag:

# Option A: New method
server.panes.tmux_filter(pane_current_command__contains="vim")

# Option B: Optimize existing .filter() transparently
# Detect when filters can be pushed to tmux and do so automatically

Performance impact

For a server with 50 panes, Python-side filtering requires fetching and parsing all 50 pane objects. Tmux-side filtering returns only matching panes, reducing both IPC and object creation overhead.

Context

The libtmux-mcp search_panes tool uses server.cmd('list-panes', '-a', '-f', ...) directly as a proof of concept for tmux-side filtering. See also #645 for the content search API.

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