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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions