tmux parity: add interactive command coverage and align flag semantics with tmux

[tony]

Summary

This PR expands libtmux's tmux command parity across Server, Session, Window, and Pane, with a focus on interactive and client-dependent commands. It also tightens several flag mappings and state-refresh behaviors so the high-level API matches tmux semantics more closely.

In addition to the new command coverage, this includes the three follow-up fixes from review:

• Session.detach_client() no longer forces -s, so targeted detach behaves like tmux.
• Window.move_window() now refreshes after successful moves, so returned objects are not stale after relative or cross-session moves.
• ControlMode now binds client_name to the spawned client by matching client_pid, which fixes multi-client races.

Main Changes

New or expanded tmux command coverage

• Add Server support for commands such as bind_key, unbind_key, list_keys, list_commands, start_server, lock_server, lock_client, refresh_client, suspend_client, server_access, run_shell, if_shell, source_file, buffer commands, confirm_before, command_prompt, and display_menu.
• Add Session.detach_client() and window navigation helpers.
• Add Window support for move_window flags, select_layout flags, last_pane, next_layout, previous_layout, rotate, swap, respawn, link, and unlink.
• Expand Pane coverage for display_popup, capture_pane, send_keys, select, copy_mode, clock_mode, choose_*, customize_mode, display_panes, find_window, paste_buffer, clear_history, pipe, join, break_pane, move, respawn, and related flags.

tmux semantics and compatibility fixes

• Correct several flag mappings and version gates to match tmux behavior.
• Treat move-window -r as standalone renumbering.
• Fix popup, prompt, paste-buffer, rotate, choose-tree, clear-history, capture-pane, and run-shell semantics where prior mappings diverged from tmux.
• Add version annotations and parity docs where new parameters were introduced on existing APIs.

Test and tooling support

• Add ControlMode and pytest fixture support for commands that require a real attached client.
• Add extensive functional coverage for new command paths and regression cases.
• Add parity-analysis support files under .claude/ and skills/tmux-parity/ to help maintain command coverage against tmux.

Testing

Ran:

• uv run ruff check . --fix --show-fixes
• uv run ruff format .
• uv run mypy
• uv run py.test --reruns 0 -vvv

Latest full run:

• 1067 passed, 1 skipped

Notes

• Diff vs origin/master is broad because this branch includes both the parity feature work and the review-driven correctness fixes on top.
• The attached-client test infrastructure is intentionally part of this PR because several new tmux commands cannot be exercised correctly without a real client.

[codecov]

Codecov Report

❌ Patch coverage is 48.51695% with 486 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.02%. Comparing base (0b77cd5) to head (dd3da50).

Files with missing lines	Patch %	Lines
src/libtmux/server.py	46.19%	110 Missing and 81 partials ⚠️
src/libtmux/pane.py	50.39%	107 Missing and 80 partials ⚠️
src/libtmux/window.py	48.62%	32 Missing and 24 partials ⚠️
src/libtmux/_internal/control_mode.py	48.21%	28 Missing and 1 partial ⚠️
src/libtmux/session.py	45.16%	11 Missing and 6 partials ⚠️
src/libtmux/common.py	66.66%	2 Missing ⚠️
src/libtmux/options.py	50.00%	1 Missing and 1 partial ⚠️
src/libtmux/pytest_plugin.py	33.33%	2 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## master #653 +/- ##
==========================================
+ Coverage 46.58% 47.02% +0.44% 
==========================================
Files 22 23 +1 Lines 2372 3296 +924 Branches 390 709 +319 ==========================================
+ Hits 1105 1550 +445 - Misses 1098 1384 +286 - Partials 169 362 +193 

☔ 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

Found 4 issues:

1. Pane.display_message(): no_expand maps to the wrong tmux flag. -I in display-message opens the pane for stdin input forwarding (window_pane_start_input()), not format suppression. The correct flag is -l (literal/no-expand, tmux 3.4+). Additionally, list_formats is also mapped to -l with the doc claiming it "lists format variables", but -l means suppress expansion; listing variables is done by -a (already mapped to all_formats). Both parameters are misassigned.

libtmux/src/libtmux/pane.py

Lines 700 to 714 in 857384a

	tmux_args+= ("-v",)
	ifno_expand:
	tmux_args+= ("-I",)
	ifnotify:
	tmux_args+= ("-N",)
	iflist_formats:
	ifhas_gte_version("3.4", tmux_bin=self.server.tmux_bin):
	tmux_args+= ("-l",)
	else:
	warnings.warn(
	"list_formats requires tmux 3.4+, ignoring",
	stacklevel=2,

2. Window.swap() does not call self.refresh() after the operation, leaving window_index stale. The docstring example works around this by manually calling w1.refresh()/w2.refresh(), but the method itself never refreshes. Commit 3654a36e fixed the identical issue in move_window() for the same reason ("move-window can land on an index different from the requested target… leaving the returned Window stale"); swap-window has the same behaviour.

libtmux/src/libtmux/window.py

Lines 822 to 829 in 857384a

	target_id=target.window_idifisinstance(target, Window) elsetarget
	tmux_args+= ("-s", str(target_id))
	proc=self.cmd("swap-window", *tmux_args)
	ifproc.stderr:
	raiseexc.LibTmuxException(proc.stderr)

3. Server.show_prompt_history() and Server.clear_prompt_history() have no version guard. Both commands were added in tmux 3.3; libtmux's declared minimum is 3.2a. On tmux 3.2a the calls will raise LibTmuxException with a raw "unknown command" tmux error instead of a clean version message. The pattern established in the same PR for confirm_before and command_prompt (has_gte_version("3.3") + raise) should be applied here too.

libtmux/src/libtmux/server.py

Lines 1119 to 1158 in 857384a

	defshow_prompt_history(
	self,
	*,
	prompt_type: str|None=None,
	) ->list[str]:
	"""Show prompt history via ``$ tmux show-prompt-history``.
	Parameters
	----------
	prompt_type : str, optional
	Prompt type to show (``-T`` flag). One of: ``command``,
	``search``, ``target``, ``window-target``.
	Returns
	-------
	list[str]
	Prompt history lines.
	Examples
	--------
	>>> result = server.show_prompt_history()
	>>> isinstance(result, list)
	True
	"""
	tmux_args: tuple[str, ...] = ()
	ifprompt_typeisnotNone:
	tmux_args+= ("-T", prompt_type)
	proc=self.cmd("show-prompt-history", *tmux_args)
	ifproc.stderr:
	raiseexc.LibTmuxException(proc.stderr)
	returnproc.stdout
	defclear_prompt_history(
	self,
	*,

4. display_popup docstring cross-reference uses the wrong module path: ~libtmux.test.control_mode.ControlMode — that module does not exist. The class lives at libtmux._internal.control_mode.ControlMode, which is already used correctly in server.py line 1013. This will produce a broken Sphinx link in generated docs.

libtmux/src/libtmux/pane.py

Lines 1202 to 1206 in 857384a

	Requires tmux 3.2+ and an attached client. Use
	:class:`~libtmux.test.control_mode.ControlMode` in tests to provide
	a client.

🤖 Generated with Claude Code

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

[tony]

Code review

Found 1 issue:

1. Server.command_prompt(bspace_exit=True) emits -e with no version guard, while the sibling literal parameter on the same method does guard -l with has_gte_version("3.6") and a warnings.warn fallback. The docstring acknowledges that -e was added by upstream commit 1e5f93b7 on 2026-01-14 and is "not in any tagged release at the time of writing", so any caller passing bspace_exit=True on currently-released tmux (3.2a–3.6a) will get an unknown flag -e error from tmux. The CI hides this because tests/test_server.py::test_command_prompt_extra_flags[bspace_exit] monkeypatches server.cmd, never invoking real tmux for the assertion.

libtmux/src/libtmux/server.py

Lines 1066 to 1077 in 095758a

	ifliteral:
	ifhas_gte_version("3.6", tmux_bin=self.tmux_bin):
	tmux_args+= ("-l",)
	else:
	warnings.warn(
	"literal requires tmux 3.6+, ignoring",
	stacklevel=2,
	)
	ifbspace_exit:
	tmux_args+= ("-e",)

Suggested fix: mirror the literal pattern — guard the -e append on has_gte_version (e.g. > 3.6 once a tag exists, or check tmux master) and emit a warning when the user requests bspace_exit=True on a version that lacks it.

Other items considered and dropped below the 80 confidence threshold: ControlMode _write_fd is not closed if subprocess.Popen raises before the registration loop (control_mode.py L61–L92) — real but error-path-only; and Session.detach_client(all_clients=True, target_client=...) enumerates list-clients then issues per-client detaches non-atomically — race window is microseconds and the docstring acknowledges it.

🤖 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 against the 3 commits since the prior review (095758a..1704a54).

🤖 Generated with Claude Code

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