Increase tmux coverage: Client, typed fields, Native filtering

[tony]

Summary

libtmux 0.57.0 broadens tmux coverage. It introduces Client as a first-class typed object, threads tmux's C-side -f filter through the typed listing methods so callers can push predicates into the tmux server, adds typed access to many more format tokens with scope-and-version-gated -F templates, and propagates subcommand context through LibTmuxException so downstream tools can dispatch on which tmux command produced an error.

What's new

• Client object and Server.clients accessor. New typed dataclass for attached terminals. client_name is the stable identifier; session_id / window_id / pane_id are attached-view snapshots hydrated via tmux's downward format_defaults cascade. attached_session / attached_window / attached_pane re-read list-clients before resolving; attached_pane is session-scope (cascade), not the client's CLIENT_ACTIVEPANE focus.
• Server.display_message and Window.display_message. Server reads like #{version} and #{socket_path} work without a pane handle; window reads (#{window_zoomed_flag}, #{window_active_clients_list}) auto-bind to the window's id. All three display_message wrappers (including the existing Pane.display_message) surface tmux stderr via warnings.warn rather than dropping it silently. Callers that want to escalate can wrap in warnings.catch_warnings with filterwarnings("error").
• C-side -f filter on typed listing methods. Server.search_panes / search_windows / search_sessions plus the Session and Window analogues take a filter= kwarg routed to tmux's -f flag. tmux evaluates the predicate and drops non-matching rows before any Python instance is constructed. Caveat: tmux silently expands a malformed predicate to empty, which the format engine treats as false — a typo looks identical to "no matches".
• Scope-and-version-aware -F templates. The format string libtmux sends each list-* subcommand is now scope- and version-aware. A Session row hydrates active-window and active-pane fields via tmux's downward cascade; a Client row likewise hydrates the client's attached session, window, and active pane. Tokens introduced after tmux 3.2a are gated through FIELD_VERSION so the -F template stays safe on the project's minimum supported tmux. Unknown tokens stay None on the typed surface — no crash, no warning.
• Typed Pane / Window / Session / Client format-token fields for the 3.2a set. Pane state (pane_dead, pane_in_mode, pane_marked, pane_synchronized, pane_path, pane_pipe …), window state (window_zoomed_flag, window_silence_flag, window_flags …), session state (session_marked …), and client view (client_session, client_readonly, client_termtype …).
• Server.run_shell(cwd=, show_stderr=). New kwargs map to tmux's -c (3.4+) and -E (3.6+) flags. Older tmux warns and ignores the kwarg instead of erroring.
• Pane.send_keys(cmd=None, …) flag-only invocation. Pass cmd=None together with reset=True or repeat=N to invoke tmux's flag-only send-keys -R / send-keys -N <n> form without any trailing key argument.
• Server.list_buffers(format_string=, filter=). Project a chosen -F template or push a buffer-name match expression through tmux's format engine.
• Pane.capture_pane(pending=True). Return bytes tmux has read from the pane but not yet committed to the terminal — useful for diagnosing programs whose output stalls mid-sequence.

Fixes

• Pane.reset() now clears pane scrollback. The history clear silently no-op'd in 0.56.0, leaving the scrollback intact (mcp(pane_tools): clear_pane does not reliably clear visible content #650).

Breaking changes

• LibTmuxException string form gains a subcommand prefix. str(exc) now begins with the originating tmux subcommand name followed by ": ". An error from Session.last_window() used to render as "can't find window" and now renders as "last-window: can't find window". The wrapped-stderr type also changed: exc.args[0] is now str (joined with "\n" when tmux emitted multiple stderr lines); previously it was list[str]. Substring matches and unanchored re.search patterns continue to work unchanged.
• Server.sessions, Server.clients, and Server.search_sessions raise on tmux errors. Previously, a tmux command failure was swallowed by a bare except Exception: pass, returning an empty QueryList indistinguishable from "no sessions/clients" or "filter matched nothing". The wrappers now let LibTmuxException propagate. Genuine empty results still return an empty QueryList; "no server running" is still treated as an empty result, preserving the contract that a fresh Server can be introspected before its daemon is up.

Deferred to follow-up shipments

• Typed Obj fields for tokens tmux added in 3.4 / 3.5 / 3.6 and the forward-looking set from tmux master. Held until tmux 3.7 reaches a tagged release.
• Per-client active-pane resolution via tmux's CLIENT_ACTIVEPANE flag. Client.attached_pane currently follows the cascade (session's current window's active pane); the two diverge once a client has used select-pane -P to set its own active pane.
• A predictable error contract for display_message (version-gated raise, per-call raise_on_stderr kwarg, or kept-permanent warn).

Test plan

• rm -rf docs/_build && uv run ruff format . && uv run ruff check . && uv run mypy src tests && uv run pytest --reruns 0 -vvv && just -f docs/justfile html — passes locally on tmux 3.6a
• CI matrix (3.2a through master) green via gh pr checks --watch

Refs

• Closes mcp(pane_tools): clear_pane does not reliably clear visible content #650 (Pane.reset scrollback)
• Refs Wrapper gaps surfaced by libtmux-mcp adoption of 0.56.0 (14 sites) #670 (umbrella)
• Companion: chore(deps[libtmux]): adopt libtmux 0.56.0 wrappers, drop raw cmd() escape hatches libtmux-mcp#48

[codecov]

Codecov Report

❌ Patch coverage is 67.02413% with 123 lines in your changes missing coverage. Please review.
✅ Project coverage is 51.26%. Comparing base (4d5f7f7) to head (61688af).

Files with missing lines	Patch %	Lines
src/libtmux/neo.py	38.46%	55 Missing and 1 partial ⚠️
src/libtmux/server.py	77.77%	20 Missing and 4 partials ⚠️
src/libtmux/client.py	60.41%	16 Missing and 3 partials ⚠️
src/libtmux/window.py	67.92%	12 Missing and 5 partials ⚠️
src/libtmux/session.py	85.71%	3 Missing ⚠️
src/libtmux/common.py	50.00%	2 Missing ⚠️
src/libtmux/exc.py	75.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #672      +/-   ##
==========================================
+ Coverage   47.02%   51.26%   +4.23%     
==========================================
  Files          23       25       +2     
  Lines        3296     3482     +186     
  Branches      709      686      -23     
==========================================
+ Hits         1550     1785     +235     
- Misses       1384     1403      +19     
+ Partials      362      294      -68     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Scope: commit 972c3149 ("neo(fix[scope-gate]): Widen SCOPES_BY_LIST_CMD to admit downward cascade") — 3 files, +67/-6.

Verified across 5 review passes (CLAUDE.md compliance, shallow bug scan, git history of the scope gate, prior PR comments on neo.py/test_server.py/test_client.py, in-file comment compliance). The widening preserves the original tmux 3.2a defense (upward client_* queries still gated to list-clients only) while restoring downward-cascade hydration on Server.sessions[i]/Server.windows[i]/Server.clients[i] that was silently lost in the prior symmetric narrowing.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Scope: commit 8e14c0cf ("common(perf[get_version]): Memoize via @functools.cache to eliminate per-call fork") — 3 files, +155.

Verified across 5 review passes (CLAUDE.md compliance, shallow bug scan, git history of get_version and @functools.cache precedent at neo.py:415, prior PR comments on common.py/test_common.py, in-file comment compliance). History shows an independent prior attempt (da877f49 on 2026-04-perf-and-profiling) arrived at the same shape, and the sibling @functools.cache on get_output_format (27d9ad75) has shipped on master without issue. The autouse cache-clear fixture in the new tests/conftest.py correctly anticipates the test-mock pollution hazard for tests/test_common.py and tests/legacy_api/test_common.py parametrized tmux_cmd monkeypatches. The new test_get_version_binary_swap_requires_explicit_cache_clear test explicitly documents the sticky-cache trap with tmux_bin=None and validates the cache_clear() escape hatch.

One scoping nuance was considered (autouse fixture flushes cache for all tests in tests/, not just monkeypatched ones) but scored below the review threshold — it's a test-runtime concern, not a production-perf or correctness one, and not called out in CLAUDE.md.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue:

1. Multiple user-facing surfaces describe branch-internal "instead of raising" history for symbols that never shipped publicly (CLAUDE.md says: "Before adding... 'previously' / 'formerly' / 'no longer X' phrasing, 'removed' / 'moved' / 'refactored' / 'fixed' diff paraphrases, or ### Fixes entries to a user-facing surface, ask: Did users of the most recently published release ever experience this old name, old behavior, or bug? If the answer is no, it is branch-internal narrative. Move it to the commit message and describe only the current state in the artifact.")

   libtmux 0.56.0 (the most recently published release) did not ship Server.clients, Server.search_sessions, Server.display_message, or Window.display_message. Pane.display_message shipped, but did not raise on stderr. The LibTmuxException-raising state these artifacts contrast against was entirely branch-internal.

   • CHANGES Breaking changes block — "Previously, a tmux command failure under Server.sessions, Server.clients, or Server.search_sessions was swallowed..." conflates Server.sessions (published, real history) with clients and search_sessions (branch-internal):

     libtmux/CHANGES

     Lines 103 to 113 in 794cd60

     	#### `Server.sessions`, `Server.clients`, and `Server.search_sessions` raise on tmux errors (#672)
     	Previously, a tmux command failure under
     	{attr}`~libtmux.Server.sessions`, {attr}`~libtmux.Server.clients`, or
     	{meth}`~libtmux.Server.search_sessions` was swallowed by a bare
     	``except Exception: pass``, returning an empty
     	{class}`~libtmux._internal.query_list.QueryList` indistinguishable
     	from "no sessions / no clients attached" or "filter matched nothing".
     	The wrappers now let {exc}`~libtmux.exc.LibTmuxException` propagate
     	via {func}`~libtmux.common.raise_if_stderr`.

   • CHANGES Fixes bullet — "surface tmux stderr via warnings.warn instead of silently returning []" describes a return-shape that no published display_message ever had:

     libtmux/CHANGES

     Lines 249 to 258 in 794cd60

     	the history clear silently no-op'd, leaving the scrollback intact
     	(#650).
     	- {meth}`~libtmux.Server.display_message`,
     	{meth}`~libtmux.Window.display_message`, and
     	{meth}`~libtmux.Pane.display_message` surface tmux stderr via
     	:func:`warnings.warn` instead of silently returning ``[]``. tmux uses
     	stderr for both genuine errors and informational messages on some
     	versions, so the wrappers warn rather than raise; callers that want
     	to escalate can wrap the call in :func:`warnings.catch_warnings` with
     	``filterwarnings("error")`` (#672).

   • Server.display_message .. versionchanged:: 0.57 — Reports stderr via warnings.warn instead of raising — method didn't exist in 0.56:

     libtmux/src/libtmux/server.py

     Lines 1516 to 1520 in 794cd60

     	.. versionchanged:: 0.57
     	Reports stderr via :func:`warnings.warn` instead of raising.
     	Parameters

   • Window.display_message — same, didn't exist in 0.56:

     libtmux/src/libtmux/window.py

     Lines 992 to 996 in 794cd60

     	.. versionchanged:: 0.57
     	Reports stderr via :func:`warnings.warn` instead of raising.
     	"""
     	tmux_args: tuple[str, ...] = ()

   • Pane.display_message — existed in 0.56 but didn't raise:

     libtmux/src/libtmux/pane.py

     Lines 788 to 792 in 794cd60

     	.. versionchanged:: 0.57
     	Reports stderr via :func:`warnings.warn` instead of raising.
     	"""
     	tmux_args: tuple[str, ...] = ()

   • MIGRATION — "now report tmux stderr via warnings.warn rather than raising LibTmuxException":

     libtmux/MIGRATION

     Lines 210 to 215 in 794cd60

     	### `Server.display_message` / `Window.display_message` / `Pane.display_message` warn instead of raise
     	The three ``display_message`` wrappers now report tmux stderr via
     	:func:`warnings.warn` rather than raising
     	{exc}`~libtmux.exc.LibTmuxException`. tmux uses stderr for both genuine
     	errors and informational messages, and the right escalation depends on

   Rule body: https://github.com/tmux-python/libtmux/blob/794cd60edca8511ddaafc1d06687345c3d528627/CLAUDE.md#L584-L594

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

Found 1 issue:

1. Broken Sphinx cross-reference — {doc} MIGRATION (uppercase) won't resolve. The Sphinx-rendered page is docs/migration.md (anchor (migration)=); the existing reference at the bottom of CHANGES uses lowercase {doc} migration. The docs build emits WARNING: unknown document: 'MIGRATION' [ref.doc] for this line.

   libtmux/CHANGES

   Lines 180 to 182 in 068ce01

   	call in :func:`warnings.catch_warnings` with
   	``filterwarnings("error")``. See {doc}`MIGRATION` for the escalation
   	pattern.

   Reference page anchor:

   libtmux/docs/migration.md

   Lines 1 to 3 in 068ce01

   	(migration)=
   	```{currentmodule} libtmux

   Existing lowercase usage in the same file (for comparison):

   libtmux/CHANGES

   Lines 651 to 653 in 068ce01

   	attribute and {class}`~libtmux.common.QueryList` interface documented in
   	{doc}`migration`.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}