API additions for tmuxinator/teamocil parity

[tony]

Summary

tmuxp is working toward feature parity with tmuxinator (3.3.7) and teamocil (1.4.2). Three libtmux API additions are needed to unblock tmuxp-side features. All are non-breaking additions.

Tracking issue for tmuxp-side work: tmux-python/tmuxp#1016

L1. Pane.set_title() Method

Priority: Phase 3 (near-term blocker)

libtmux has no method wrapping select-pane -T <title>. tmux itself supports both #{pane_title} (in format.c:205) and select-pane -T (added in tmux 2.6). libtmux already knows about the display options (pane_border_status, pane_border_format in constants.py:163-173) but has no setter for the title itself.

The pane_title format variable is excluded from libtmux's bulk format queries (formats.py:70, commented out with note "removed in 3.1+"), but this is a libtmux-side exclusion.

Blocks: Pane titles in tmuxp — tmuxinator's named pane syntax (pane_name: command -> select-pane -T), plus enable_pane_titles, pane_title_position, pane_title_format session-level config.

Implementation:

def set_title(self, title: str) -> "Pane":
    self.cmd("select-pane", "-T", title)
    return self

Pane.cmd() already exists (pane.py:177) and select-pane is already used for Pane.select() (pane.py:601). This is a one-liner wrapper.

Non-breaking: Pure addition, no existing API changes.

L2. Configurable tmux Binary Path

Priority: Phase 5 (nice-to-have)

shutil.which("tmux") is used in two independent code paths:

• common.py:252 — tmux_cmd.__init__(), the class through which all libtmux commands flow
• server.py:223 — Server.raise_if_dead(), a separate code path that calls subprocess.check_call() directly

There is no way to use a custom tmux binary (wemux, byobu, or custom-built tmux).

Blocks: Wemux support (tmuxinator tmux_command: wemux). Also blocks CI/container use with non-standard tmux locations.

Implementation: Add optional tmux_bin parameter to Server.__init__() that propagates to tmux_cmd. Both code paths must be updated. Default remains shutil.which("tmux").

Non-breaking: Optional parameter with backward-compatible default.

L3. Pre-Execution Command Logging

Priority: Phase 5 (nice-to-have)

tmux_cmd (common.py:252-296) always executes commands. Debug logging exists (logger.debug at line 291) but logs the command and its stdout after execution, not before. There is no pre-execution logging or facility to collect commands without executing them.

Blocks: --debug / dry-run mode in tmuxp (both tmuxinator and teamocil have this).

Implementation: Add logger.debug call before subprocess.run() that logs the full command. This is a one-line change.

Non-breaking: Logging change only.

Note: Since tmuxp uses libtmux API calls (not command strings), a true dry-run would require a recording layer in WorkspaceBuilder. Pre-execution logging is the simpler prerequisite.

Existing APIs (No Changes Needed)

These libtmux APIs already support tmuxp parity features:

API	Location	Supports
Session.rename_session(name)	session.py:412	teamocil session rename mode
Window.rename_window(name)	window.py:462	teamocil --here flag
Pane.resize(height, width)	pane.py:217	teamocil v0.x pane width/height
Pane.send_keys(cmd, enter)	pane.py:423	All command sending
Pane.select()	pane.py:577	Pane focus
Window.set_option(key, val)	options.py:578	synchronize-panes, window options
Session.set_hook(hook, cmd)	hooks.py:111	Lifecycle hooks (client-detached, etc.)
Session.set_option(key, val)	options.py:578	pane-border-status, pane-border-format
HooksMixin.set_hooks() (bulk)	hooks.py:430	Efficient multi-hook setup
Session.set_environment(key, val)	session.py:53	Session-level env vars
Pane.clear()	pane.py:818	Clear pane (teamocil clear)
Pane.reset()	pane.py:823	Full reset with history clear
Pane.split(target=...)	pane.py:625	Split targeting (teamocil v0.x target)