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

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

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
python
Domain
api, cli

Research direction

Start at the server.panes.filter(...) entry point and compare it with the libtmux-mcp search_panes proof of concept, which calls server.cmd('list-panes', '-a', '-f', ...). Decide whether this should be a new tmux_filter method or a transparent filter optimization, then verify compatible filters are applied by tmux while existing QueryList behavior remains correct.

Written by the indexing model from the issue text.

Description

enhancement

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.