perf: Push QueryList filters to tmux via -f format filter
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
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
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from tmux-python/libtmux
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
tmux-python/libtmux#759 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
tmux-python/libtmux#745 · 2 comments ·
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
tmux-python/libtmux#744 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
tmux-python/libtmux#731 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
tmux-python/libtmux#654 ·