From fbe8f19c8faa680af64a4ec9742575fbc92a887b Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:24:05 -0500 Subject: [PATCH 1/7] py(docs[constants]) Document Hooks fields why: autodoc renders every dataclass field whether or not it is described, so the hook fields reach the API reference bare with no indication of when tmux fires them. The man-page text already sits beside each field as a source comment, invisible to readers of the published docs. what: - Add an Attributes section to Hooks covering every hook field - Note that an empty SparseArray means tmux reported no commands --- src/libtmux/_internal/constants.py | 197 +++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py index a0b798111..9f115a876 100644 --- a/src/libtmux/_internal/constants.py +++ b/src/libtmux/_internal/constants.py @@ -300,6 +300,203 @@ class Hooks( Parses tmux hook output into typed :class:`SparseArray` fields, preserving array indices for hooks that can have multiple commands at different indices. + A field holds an empty :class:`SparseArray` when tmux reports no commands + for that hook. + + Attributes + ---------- + alert_activity : SparseArray[str] + Run when a window has activity. See monitor-activity. + alert_bell : SparseArray[str] + Run when a window has received a bell. See monitor-bell. + alert_silence : SparseArray[str] + Run when a window has been silent. See monitor-silence. + client_active : SparseArray[str] + Run when a client becomes the latest active client of its session. + client_attached : SparseArray[str] + Run when a client is attached. + client_detached : SparseArray[str] + Run when a client is detached. + client_focus_in : SparseArray[str] + Run when focus enters a client. + client_focus_out : SparseArray[str] + Run when focus exits a client. + client_resized : SparseArray[str] + Run when a client is resized. + client_session_changed : SparseArray[str] + Run when a client's attached session is changed. + pane_died : SparseArray[str] + Run when the program running in a pane exits, but remain-on-exit is on so the + pane has not closed. + pane_exited : SparseArray[str] + Run when the program running in a pane exits. + pane_focus_in : SparseArray[str] + Run when the focus enters a pane, if the focus-events option is on. + pane_focus_out : SparseArray[str] + Run when the focus exits a pane, if the focus-events option is on. + pane_set_clipboard : SparseArray[str] + Run when the terminal clipboard is set using the xterm(1) escape sequence. + session_created : SparseArray[str] + Run when a new session created. + session_closed : SparseArray[str] + Run when a session closed. + session_renamed : SparseArray[str] + Run when a session is renamed. + window_linked : SparseArray[str] + Run when a window is linked into a session. + window_renamed : SparseArray[str] + Run when a window is renamed. + window_resized : SparseArray[str] + Run when a window is resized. This may be after the client-resized hook is run. + window_unlinked : SparseArray[str] + Run when a window is unlinked from a session. + pane_title_changed : SparseArray[str] + Run when a pane title changes (tmux 3.5+). + client_light_theme : SparseArray[str] + Run when terminal reports a light theme (tmux 3.5+). + client_dark_theme : SparseArray[str] + Run when terminal reports a dark theme (tmux 3.5+). + client_detached_control : SparseArray[str] + The client has detached. + client_session_changed_control : SparseArray[str] + The client is now attached to the session with ID session-id, which is named + name. + config_error : SparseArray[str] + An error has happened in a configuration file. + continue_control : SparseArray[str] + The pane has been continued after being paused (if the pause-after flag is set, + see refresh-client -A). + exit_control : SparseArray[str] + The tmux client is exiting immediately, either because it is not attached to any + session or an error occurred. + extended_output : SparseArray[str] + New form of %output sent when the pause-after flag is set. + layout_change : SparseArray[str] + The layout of a window with ID window-id changed. + message_control : SparseArray[str] + A message sent with the display-message command. + output : SparseArray[str] + A window pane produced output. + pane_mode_changed : SparseArray[str] + The pane with ID pane-id has changed mode. + paste_buffer_changed : SparseArray[str] + Paste buffer name has been changed. + paste_buffer_deleted : SparseArray[str] + Paste buffer name has been deleted. + pause_control : SparseArray[str] + The pane has been paused (if the pause-after flag is set). + session_changed_control : SparseArray[str] + The client is now attached to the session with ID session-id, which is named + name. + session_renamed_control : SparseArray[str] + The current session was renamed to name. + session_window_changed : SparseArray[str] + The session with ID session-id changed its active window to the window with ID + window-id. + sessions_changed : SparseArray[str] + A session was created or destroyed. + subscription_changed : SparseArray[str] + The value of the format associated with subscription name has changed to value. + unlinked_window_add : SparseArray[str] + The window with ID window-id was created but is not linked to the current + session. + unlinked_window_close : SparseArray[str] + The window with ID window-id, which is not linked to the current session, was + closed. + unlinked_window_renamed : SparseArray[str] + The window with ID window-id, which is not linked to the current session, was + renamed. + window_add : SparseArray[str] + The window with ID window-id was linked to the current session. + window_close : SparseArray[str] + The window with ID window-id closed. + window_layout_changed : SparseArray[str] + The layout of a window with ID window-id changed. The new layout is + window-layout. The window's visible layout is window-visible-layout and the + window flags are window-flags. + window_pane_changed : SparseArray[str] + The active pane in the window with ID window-id changed to the pane with ID + pane-id. + window_renamed_control : SparseArray[str] + The window with ID window-id was renamed to name. + after_bind_key : SparseArray[str] + Runs after 'bind-key' completes. + after_capture_pane : SparseArray[str] + Runs after 'capture-pane' completes. + after_copy_mode : SparseArray[str] + Runs after 'copy-mode' completes. + after_display_message : SparseArray[str] + Runs after 'display-message' completes. + after_display_panes : SparseArray[str] + Runs after 'display-panes' completes. + after_kill_pane : SparseArray[str] + Runs after 'kill-pane' completes. + after_list_buffers : SparseArray[str] + Runs after 'list-buffers' completes. + after_list_clients : SparseArray[str] + Runs after 'list-clients' completes. + after_list_keys : SparseArray[str] + Runs after 'list-keys' completes. + after_list_panes : SparseArray[str] + Runs after 'list-panes' completes. + after_list_sessions : SparseArray[str] + Runs after 'list-sessions' completes. + after_list_windows : SparseArray[str] + Runs after 'list-windows' completes. + after_load_buffer : SparseArray[str] + Runs after 'load-buffer' completes. + after_lock_server : SparseArray[str] + Runs after 'lock-server' completes. + after_new_session : SparseArray[str] + Runs after 'new-session' completes. + after_new_window : SparseArray[str] + Runs after 'new-window' completes. + after_paste_buffer : SparseArray[str] + Runs after 'paste-buffer' completes. + after_pipe_pane : SparseArray[str] + Runs after 'pipe-pane' completes. + after_queue : SparseArray[str] + Runs after 'queue' command is processed. + after_refresh_client : SparseArray[str] + Runs after 'refresh-client' completes. + after_rename_session : SparseArray[str] + Runs after 'rename-session' completes. + after_rename_window : SparseArray[str] + Runs after 'rename-window' completes. + after_resize_pane : SparseArray[str] + Runs after 'resize-pane' completes. + after_resize_window : SparseArray[str] + Runs after 'resize-window' completes. + after_save_buffer : SparseArray[str] + Runs after 'save-buffer' completes. + after_select_layout : SparseArray[str] + Runs after 'select-layout' completes. + after_select_pane : SparseArray[str] + Runs after 'select-pane' completes. + after_select_window : SparseArray[str] + Runs after 'select-window' completes. + after_send_keys : SparseArray[str] + Runs after 'send-keys' completes. + after_set_buffer : SparseArray[str] + Runs after 'set-buffer' completes. + after_set_environment : SparseArray[str] + Runs after 'set-environment' completes. + after_set_hook : SparseArray[str] + Runs after 'set-hook' completes. + after_set_option : SparseArray[str] + Runs after 'set-option' completes. + after_show_environment : SparseArray[str] + Runs after 'show-environment' completes. + after_show_messages : SparseArray[str] + Runs after 'show-messages' completes. + after_show_options : SparseArray[str] + Runs after 'show-options' completes. + after_split_window : SparseArray[str] + Runs after 'split-window' completes. + after_unbind_key : SparseArray[str] + Runs after 'unbind-key' completes. + command_error : SparseArray[str] + Runs when a command fails (tmux 3.5+). Examples -------- From 14bae5e3d2a731ecbc07453e73c02bc6dd814299 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:30:19 -0500 Subject: [PATCH 2/7] py(docs[constants]) Document options fields why: autodoc renders every dataclass field whether or not it is described, so the server, session, window, and pane option fields reach the API reference bare. Readers cannot tell what a field controls without opening the tmux man page and translating the underscored name back to its hyphenated option. what: - Add Attributes sections to ServerOptions, SessionOptions, WindowOptions, and PaneOptions describing each option field - Note in each summary that a field keeps its default when tmux reports no value for that option --- src/libtmux/_internal/constants.py | 345 ++++++++++++++++++++++++++++- 1 file changed, 341 insertions(+), 4 deletions(-) diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py index 9f115a876..df4d9843f 100644 --- a/src/libtmux/_internal/constants.py +++ b/src/libtmux/_internal/constants.py @@ -23,7 +23,66 @@ class ServerOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux server options.""" + """Container for tmux server options. + + Each field carries the value of the tmux server option named the same with + hyphens in place of underscores. A field keeps its default — ``None``, or an + empty container for the array options — when tmux reports no value for it. + + Attributes + ---------- + backspace : str | None + Key tmux sends when backspace is pressed. + buffer_limit : int | None + Number of paste buffers kept before the oldest is discarded. + command_alias : SparseArray[str] + Command aliases by array index, each a ``name=value`` pair expanded when a + command is parsed. + default_terminal : str | None + Value of ``TERM`` given to new windows. + copy_command : str | None + Shell command that copy-pipe pipes to when called without arguments. + escape_time : int | None + Milliseconds tmux waits after an escape to decide whether it starts a key + sequence. + editor : str | None + Command tmux runs when it needs an editor. + exit_empty : Literal["on", "off"] | None + Whether the server exits once no sessions remain. + exit_unattached : Literal["on", "off"] | None + Whether the server exits once no clients are attached. + extended_keys : Literal["on", "off", "always"] | None + Whether keys pressed with Control, Meta, or Shift are reported as extended + sequences, and whether the program in the pane may pick the mode. + focus_events : Literal["on", "off"] | None + Whether focus events are requested from the terminal and passed through to + applications. + history_file : str | None + File command prompt history is loaded from and written back to; an empty + value keeps no history file. + message_limit : int | None + Number of messages kept in each client's message log. + prompt_history_limit : int | None + Number of entries kept in the history file for each type of prompt. + set_clipboard : Literal["on", "external", "off"] | None + Whether tmux sets the terminal clipboard, and whether applications may + create paste buffers with the escape sequence. + terminal_features : TerminalFeatures + Feature names tmux applies to each terminal type pattern, for classes of + functionality terminfo does not report. + terminal_overrides : SparseArray[str] + terminfo capability overrides by array index, each a terminal type pattern + followed by ``name=value`` entries. + user_keys : SparseArray[str] + Escape sequences by array index, bound to the keys named ``User0``, + ``User1``, and so on. + default_client_command : str | None + Command run when tmux is invoked without one. + extended_keys_format : Literal["csi-u", "xterm"] | None + Escape sequence format used to report modified keys to applications. + get_clipboard : Literal["off", "buffer", "request", "both"] | None + How tmux answers an application that asks for the clipboard. + """ backspace: str | None = field(default=None) buffer_limit: int | None = field(default=None) @@ -62,7 +121,127 @@ def __init__(self, **kwargs: object) -> None: class SessionOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux session options.""" + """Container for tmux session options. + + Each field carries the value of the tmux session option named the same with + hyphens in place of underscores. A field keeps its default — ``None``, or an + empty container for the array options — when tmux reports no value for it. + + Attributes + ---------- + activity_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on activity while monitor-activity is on. + assume_paste_time : int | None + Milliseconds below which consecutive input counts as a paste and key + bindings are not processed; zero disables. + base_index : int | None + Index of the first window in the session. + bell_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on a bell while monitor-bell is on. + default_command : str | None + Command run in new windows; empty starts a login shell from default-shell. + default_shell : str | None + Full path of the shell used when default-command is empty. + default_size : str | None + Size of new windows as ``WIDTHxHEIGHT``, used when window-size is manual + or a session is created detached. + destroy_unattached : Literal["on", "off"] | None + Whether the session is destroyed once its last client detaches. + detach_on_destroy : Literal["off", "on", "no-detached", "previous", "next"] | None + Where a client goes when the session it is attached to is destroyed. + display_panes_active_colour : str | None + Colour of the active pane indicator shown by display-panes. + display_panes_colour : str | None + Colour of the inactive pane indicators shown by display-panes. + display_panes_time : int | None + Milliseconds the display-panes indicators stay on screen. + display_time : int | None + Milliseconds status line messages and indicators stay on screen; zero + holds them until a key is pressed. + history_limit : int | None + Lines of scrollback kept per pane, applied to panes created afterwards. + key_table : str | None + Key table key presses are looked up in first. + lock_after_time : int | None + Seconds of inactivity after which the session locks; zero never locks. + lock_command : str | None + Shell command run to lock each client. + menu_style : str | None + Style of menus. + menu_selected_style : str | None + Style of the selected menu item. + menu_border_style : str | None + Style of menu borders. + menu_border_lines : Literal["single", ...] | None + Characters used to draw menu borders. + message_command_style : str | None + Style of the command prompt while in vi command mode. + message_line : int | None + Status line row that messages and the command prompt are drawn on. + message_style : str | None + Style of messages and the command prompt. + mouse : Literal["on", "off"] | None + Whether tmux captures the mouse so mouse events run key bindings. + prefix : str | None + Key accepted as the prefix key; the tmux key name ``None`` sets no prefix. + prefix2 : str | None + Second key accepted as a prefix key. + renumber_windows : Literal["on", "off"] | None + Whether closing a window renumbers the rest so no gaps are left. + repeat_time : int | None + Milliseconds a key bound with ``-r`` may be repeated without the prefix. + set_titles : Literal["on", "off"] | None + Whether tmux sets the client terminal title. + set_titles_string : str | None + Format expanded to build the terminal title while set-titles is on. + silence_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on silence while monitor-silence is on. + status : Literal["off", "on"] | int | None + Whether the status line is shown, and how many rows it occupies. + status_format : list[str] | None + Format of each status line row, one entry per row. + status_interval : int | None + Seconds between status line updates; zero disables timed redraws. + status_justify : Literal["left", "centre", "right", "absolute-centre"] | None + Position of the window list within the status line. + status_keys : Literal["vi", "emacs"] | None + Key set used at the command prompt and in the status line. + status_left : str | None + Format drawn on the left of the status line. + status_left_length : int | None + Maximum width of the left side of the status line. + status_left_style : str | None + Style of the left side of the status line. + status_position : Literal["top", "bottom"] | None + Edge of the terminal the status line sits on. + status_right : str | None + Format drawn on the right of the status line. + status_right_length : int | None + Maximum width of the right side of the status line. + status_right_style : str | None + Style of the right side of the status line. + status_style : str | None + Style of the status line. + update_environment : SparseArray[str] + Environment variable names by array index, copied from the client into the + session environment when a session is created or attached. + visual_activity : Literal["on", "off", "both"] | None + Whether an activity alert shows a message, rings the bell, or both. + visual_bell : Literal["on", "off", "both"] | None + Whether a bell alert shows a message, rings the bell, or both. + visual_silence : Literal["on", "off", "both"] | None + Whether a silence alert shows a message, rings the bell, or both. + word_separators : str | None + Characters that separate words for the copy mode word commands. + focus_follows_mouse : Literal["on", "off"] | None + Whether moving the mouse into a pane selects it, while mouse is on. + message_format : str | None + Format of the prompt and message area, where ``#{message}`` expands to the + prompt or message text. + prompt_command_cursor_style : Literal["default", ...] | None + Shape of the cursor in the command prompt while in vi command mode, and + whether it blinks. + """ activity_action: t.Literal["any", "none", "current", "other"] | None = field( default=None, @@ -154,7 +333,116 @@ def __init__(self, **kwargs: object) -> None: class WindowOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux window options.""" + """Container for tmux window options. + + Each field carries the value of the tmux window option named the same with + hyphens in place of underscores, and is ``None`` when tmux reports no value + for it. + + Attributes + ---------- + aggressive_resize : Literal["on", "off"] | None + Whether the window is sized from the sessions where it is the current + window rather than from every session it is linked to. + automatic_rename : Literal["on", "off"] | None + Whether tmux renames the window from automatic-rename-format. + automatic_rename_format : str | None + Format used to build the name while automatic-rename is on. + clock_mode_colour : str | None + Colour of the clock in clock mode. + clock_mode_style : Literal["12", "24"] | None + Hour format of the clock in clock mode. + fill_character : str | None + Character filling terminal area the window does not cover. + main_pane_height : int | str | None + Height of the main pane in the main-horizontal layouts, in rows or as a + percentage such as ``"10%"``. + main_pane_width : int | str | None + Width of the main pane in the main-vertical layouts, in columns or as a + percentage such as ``"10%"``. + copy_mode_match_style : str | None + Style of search matches in copy mode. + copy_mode_mark_style : str | None + Style of the line holding the mark in copy mode. + copy_mode_current_match_style : str | None + Style of the search match the cursor is on in copy mode. + mode_keys : Literal["vi", "emacs"] | None + Key set used in copy mode. + mode_style : str | None + Style of indicators and highlighting in window modes. + monitor_activity : Literal["on", "off"] | None + Whether activity in the window raises an alert. + monitor_bell : Literal["on", "off"] | None + Whether a bell in the window raises an alert. + monitor_silence : int | None + Seconds of silence after which the window raises an alert; zero disables. + other_pane_height : int | str | None + Height of the panes beside the main one in the main-horizontal layouts, in + rows or as a percentage; zero has no effect. + other_pane_width : int | str | None + Width of the panes beside the main one in the main-vertical layouts, in + columns or as a percentage; zero has no effect. + pane_active_border_style : str | None + Style of the border around the active pane. + pane_base_index : int | None + Index of the first pane in the window. + pane_border_format : str | None + Format of the text shown in pane border status lines. + pane_border_indicators : Literal["off", "colour", "arrows", "both"] | None + How the active pane is marked on the border, by colouring it, by arrow + markers, by both, or not at all. + pane_border_lines : Literal["single", "double", "heavy", "simple", "number"] | None + Characters used to draw pane borders. + pane_border_status : Literal["off", "top", "bottom"] | None + Whether pane border status lines are drawn, and on which border. + pane_border_style : str | None + Style of the borders around panes other than the active one. + popup_style : str | None + Style of popups. + popup_border_style : str | None + Style of popup borders. + popup_border_lines : Literal["single", ...] | None + Characters used to draw popup borders. + window_status_activity_style : str | None + Style of a window in the status line while it has an activity alert. + window_status_bell_style : str | None + Style of a window in the status line while it has a bell alert. + window_status_current_format : str | None + Format of the current window in the status line window list. + window_status_current_style : str | None + Style of the current window in the status line. + window_status_format : str | None + Format of windows other than the current one in the status line window + list. + window_status_last_style : str | None + Style of the last active window in the status line. + window_status_separator : str | None + Text drawn between windows in the status line window list. + window_status_style : str | None + Style of windows other than the current and last ones in the status line. + window_size : Literal["largest", "smallest", "manual", "latest"] | None + How tmux derives the window size from the attached clients. + wrap_search : Literal["on", "off"] | None + Whether a copy mode search wraps around the end of the pane contents. + tiled_layout_max_columns : int | None + Maximum columns in the tiled layout, with further panes stacked in extra + rows; zero means no limit. + copy_mode_line_numbers : Literal["off", ...] | None + Whether copy mode shows line numbers, and whether they are counted from + the start of the history or from the cursor. + copy_mode_line_number_style : str | None + Style of line numbers in copy mode. + copy_mode_current_line_number_style : str | None + Style of the line number on the cursor line in copy mode. + tree_mode_preview_format : str | None + Format of the preview indicator in tree mode. + tree_mode_preview_style : str | None + Style of the preview indicator in tree mode. + window_pane_status_format : str | None + Format of panes other than the current one in the status line pane list. + window_pane_current_status_format : str | None + Format of the current pane in the status line pane list. + """ aggressive_resize: t.Literal["on", "off"] | None = field(default=None) automatic_rename: t.Literal["on", "off"] | None = field(default=None) @@ -229,7 +517,56 @@ def __init__(self, **kwargs: object) -> None: class PaneOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux pane options.""" + """Container for tmux pane options. + + Each field carries the value of the tmux pane option named the same with + hyphens in place of underscores, and is ``None`` when tmux reports no value + for it. + + Attributes + ---------- + allow_passthrough : Literal["on", "off", "all"] | None + Whether programs in the pane may bypass tmux with the passthrough escape + sequence, and whether an invisible pane may do so. + allow_rename : Literal["on", "off"] | None + Whether programs in the pane may rename the window with an escape + sequence. + alternate_screen : Literal["on", "off"] | None + Whether programs in the pane may use the terminal alternate screen, which + restores the earlier pane contents when they exit. + cursor_colour : str | None + Colour of the cursor in the pane. + pane_colours : list[str] | None + Colour palette the pane uses for the colours numbered zero to 255, in + index order. + cursor_style : Literal["default", ...] | None + Shape of the cursor in the pane, and whether it blinks. + remain_on_exit : Literal["on", "off", "failed", "key"] | None + Whether the pane stays open once the program running in it exits. + remain_on_exit_format : str | None + Text shown at the bottom of a pane held open by remain-on-exit. + scroll_on_clear : Literal["on", "off"] | None + Whether clearing the whole screen scrolls its contents into history first. + synchronize_panes : Literal["on", "off"] | None + Whether input is duplicated to the other panes in the window that also + have this on. + window_active_style : str | None + Style of the pane while it is the active pane. + window_style : str | None + Style of the pane while it is not the active pane. + pane_scrollbars : Literal["off", "modal", "on"] | None + Whether a character based scrollbar is drawn beside the pane, all the time + or only while the pane is in copy or view mode. + pane_scrollbars_style : str | None + Style of the pane scrollbar, whose width and pad attributes size it and + the gap to the pane. + tree_mode_preview_format : str | None + Format of the preview indicator in tree mode. + pane_active_border_style : str | None + Style of the pane border while the pane is active. + pane_border_style : str | None + Style of the pane border while the pane is not active. + """ allow_passthrough: t.Literal["on", "off", "all"] | None = field(default=None) allow_rename: t.Literal["on", "off"] | None = field(default=None) From 9ef497f3a548befad3995beed04b1c34b633b34f Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:37:02 -0500 Subject: [PATCH 3/7] py(docs[neo]) Document Obj format fields why: autodoc renders every dataclass field whether or not it is described, so Obj's tmux format fields reach the API reference bare, both on Obj and on the Pane, Session, and Window pages that inherit them. A reader cannot tell what a field reports without opening the tmux man page and matching the token by name. what: - Add an Attributes section to Obj covering the server handle and every tmux format token it carries - Describe client_mode_format from tmux's client mode default format, the one token the man page's FORMATS table omits - Note in the summary that tmux reports each token as a string, and that None means the token was out of the listing's scope, absent from the running tmux, or expanded to empty --- src/libtmux/neo.py | 378 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) diff --git a/src/libtmux/neo.py b/src/libtmux/neo.py index 7a7d1a46a..98ece86fa 100644 --- a/src/libtmux/neo.py +++ b/src/libtmux/neo.py @@ -284,6 +284,384 @@ def _normalize_tmux_version(version: str) -> LooseVersion: class Obj: """Dataclass of generic tmux object. + Every field but ``server`` is a tmux format token, and tmux reports each + one as a string. A field is ``None`` when its token was left out of the + query or expanded to empty: tokens outside the listing's scope (see + :data:`SCOPES_BY_LIST_CMD`) and tokens the running tmux is too old to + register (see :data:`FIELD_VERSION`) are never requested, and copy-mode + and command-context tokens only resolve at event time. + + Attributes + ---------- + server : Server + Server the object was queried from, and the connection every refresh + re-runs its ``list-*`` command over. + active_window_index : str | None + Index of the session's active window. + alternate_saved_x : str | None + Saved cursor X position for the pane's alternate screen. + alternate_saved_y : str | None + Saved cursor Y position for the pane's alternate screen. + bracket_paste_flag : str | None + ``"1"`` when the pane's terminal has bracketed paste mode enabled. + buffer_name : str | None + Name of the buffer. + buffer_sample : str | None + Sample taken from the start of the buffer's contents. + buffer_size : str | None + Size of the buffer, in bytes. + client_activity : str | None + Time the client last had activity. + client_cell_height : str | None + Height of one of the client's terminal cells, in pixels. + client_cell_width : str | None + Width of one of the client's terminal cells, in pixels. + client_control_mode : str | None + ``"1"`` when the client is running in control mode. + client_created : str | None + Time the client was created. + client_discarded : str | None + Bytes discarded because the client fell behind. + client_flags : str | None + List of the client's flags. + client_height : str | None + Height of the client, in cells. + client_key_table : str | None + Name of the key table the client is currently using. + client_last_session : str | None + Name of the session the client was attached to before its current one. + client_mode_format : str | None + Default format string tmux's client mode (``choose-client``) renders + each client row with. + client_name : str | None + Name of the client. + client_pid : str | None + PID of the client process. + client_prefix : str | None + ``"1"`` while the prefix key has been pressed. + client_readonly : str | None + ``"1"`` when the client is attached read-only. + client_session : str | None + Name of the session the client is attached to. + client_termfeatures : str | None + Terminal features tmux detected for the client, if any. + client_termname : str | None + Terminal name of the client. + client_termtype : str | None + Terminal type of the client, if available. + client_tty : str | None + Path to the client's pseudo terminal. + client_uid : str | None + UID of the client process. + client_user : str | None + User the client process runs as. + client_utf8 : str | None + ``"1"`` when the client supports UTF-8. + client_width : str | None + Width of the client, in cells. + client_written : str | None + Bytes written to the client. + command_list_alias : str | None + Command alias, when listing commands. + command_list_name : str | None + Command name, when listing commands. + command_list_usage : str | None + Command usage string, when listing commands. + config_files : str | None + List of the configuration files tmux loaded. + copy_cursor_line : str | None + Text of the line the cursor sits on in copy mode. + copy_cursor_word : str | None + Word under the cursor in copy mode. + copy_cursor_x : str | None + Cursor X position in copy mode. + copy_cursor_y : str | None + Cursor Y position in copy mode. + current_file : str | None + Configuration file currently being parsed. + cursor_character : str | None + Character at the pane's cursor position. + cursor_flag : str | None + ``"1"`` when the pane's cursor is visible. + cursor_x : str | None + Cursor X position in the pane. + cursor_y : str | None + Cursor Y position in the pane. + history_bytes : str | None + Bytes held in the pane's scrollback history. + history_limit : str | None + Maximum number of scrollback lines the pane keeps. + history_size : str | None + Lines currently held in the pane's scrollback history. + insert_flag : str | None + ``"1"`` when the pane's terminal is in insert mode. + keypad_cursor_flag : str | None + ``"1"`` when the pane's terminal is in application cursor key mode. + keypad_flag : str | None + ``"1"`` when the pane's terminal is in application keypad mode. + last_window_index : str | None + Index of the last window in the session. + line : str | None + Row number tmux assigns to the entry in the listing. + mouse_all_flag : str | None + ``"1"`` when the pane's terminal has all-motion mouse reporting + enabled. + mouse_any_flag : str | None + ``"1"`` when the pane's terminal has any mouse reporting mode enabled. + mouse_button_flag : str | None + ``"1"`` when the pane's terminal has button-event mouse reporting + enabled. + mouse_sgr_flag : str | None + ``"1"`` when the pane's terminal reports mouse events in SGR form. + mouse_standard_flag : str | None + ``"1"`` when the pane's terminal has standard mouse reporting enabled. + next_session_id : str | None + Session ID tmux will give the next new session. + origin_flag : str | None + ``"1"`` when the pane's terminal is in origin mode. + pane_active : str | None + ``"1"`` when this is the active pane of its window. + pane_at_bottom : str | None + ``"1"`` when the pane touches the bottom of the window. + pane_at_left : str | None + ``"1"`` when the pane touches the left of the window. + pane_at_right : str | None + ``"1"`` when the pane touches the right of the window. + pane_at_top : str | None + ``"1"`` when the pane touches the top of the window. + pane_bg : str | None + Pane background colour. + pane_bottom : str | None + Bottom edge of the pane, as a window row. + pane_current_command : str | None + Command running in the pane, if available. + pane_current_path : str | None + Working directory of the pane, if available. + pane_dead : str | None + ``"1"`` when the pane's process has exited and the pane is dead. + pane_dead_signal : str | None + Signal that killed the process in a dead pane. + pane_dead_status : str | None + Exit status of the process in a dead pane. + pane_dead_time : str | None + Time the process in a dead pane exited. + pane_fg : str | None + Pane foreground colour. + pane_flags : str | None + Pane flags: ``*`` for the active pane, ``-`` for the last used, ``Z`` + for zoomed, ``F`` for floating. + pane_floating_flag : str | None + ``"1"`` when the pane is floating. + pane_format : str | None + ``"1"`` when the format is being evaluated for a pane. + pane_height : str | None + Height of the pane, in cells. + pane_id : str | None + Unique pane ID, e.g. ``"%3"`` (the ``#D`` alias). + pane_in_mode : str | None + Number of modes the pane is in. + pane_index : str | None + Index of the pane within its window (the ``#P`` alias). + pane_input_off : str | None + ``"1"`` when input to the pane is disabled. + pane_last : str | None + ``"1"`` when this is the window's last used pane. + pane_left : str | None + Left edge of the pane, as a window column. + pane_marked : str | None + ``"1"`` when this pane is the marked pane. + pane_marked_set : str | None + ``"1"`` when a marked pane is set on the server. + pane_mode : str | None + Name of the mode the pane is in, if any. + pane_path : str | None + Path of the pane; the application running in it can set this. + pane_pb_progress : str | None + Progress percentage of the pane's progress bar; the application running + in it can set this. + pane_pb_state : str | None + Pane progress bar state, one of ``hidden``, ``normal``, ``error``, + ``indeterminate``, or ``paused``; the application running in the pane + can set this. + pane_pid : str | None + PID of the first process started in the pane. + pane_pipe : str | None + ``"1"`` while the pane's output is being piped. + pane_pipe_pid : str | None + PID of the pipe process, if any. + pane_right : str | None + Right edge of the pane, as a window column. + pane_search_string : str | None + Last search string used in the pane's copy mode. + pane_start_command : str | None + Command the pane was started with. + pane_start_path : str | None + Working directory the pane was started in. + pane_synchronized : str | None + ``"1"`` when the pane has ``synchronize-panes`` in effect. + pane_tabs : str | None + Tab stop positions in the pane. + pane_title : str | None + Title of the pane; the application running in it can set this (the + ``#T`` alias). + pane_top : str | None + Top edge of the pane, as a window row. + pane_tty : str | None + Path to the pane's pseudo terminal. + pane_width : str | None + Width of the pane, in cells. + pane_x : str | None + X position of the pane. + pane_y : str | None + Y position of the pane. + pane_z : str | None + Z position of the pane. + pane_zoomed_flag : str | None + ``"1"`` when the pane is zoomed. + pid : str | None + PID of the tmux server process. + scroll_position : str | None + Scroll position in copy mode. + scroll_region_lower : str | None + Bottom line of the pane's scroll region. + scroll_region_upper : str | None + Top line of the pane's scroll region. + search_match : str | None + Search match in the pane's copy mode, if any. + selection_end_x : str | None + X position of the end of the copy-mode selection. + selection_end_y : str | None + Y position of the end of the copy-mode selection. + selection_start_x : str | None + X position of the start of the copy-mode selection. + selection_start_y : str | None + Y position of the start of the copy-mode selection. + session_activity : str | None + Time of the session's last activity. + session_alerts : str | None + List of indexes of the session's windows with alerts. + session_attached : str | None + Number of clients attached to the session. + session_attached_list : str | None + List of the clients attached to the session. + session_created : str | None + Time the session was created. + session_format : str | None + ``"1"`` when the format is being evaluated for a session. + session_group : str | None + Name of the session group the session belongs to. + session_group_attached : str | None + Number of clients attached to sessions in the session group. + session_group_attached_list : str | None + List of the clients attached to sessions in the session group. + session_group_list : str | None + List of the sessions in the session group. + session_group_many_attached : str | None + ``"1"`` when more than one client is attached to sessions in the + session group. + session_group_size : str | None + Number of sessions in the session group. + session_grouped : str | None + ``"1"`` when the session belongs to a session group. + session_id : str | None + Unique session ID, e.g. ``"$1"``. + session_last_attached : str | None + Time the session was last attached. + session_many_attached : str | None + ``"1"`` when more than one client is attached to the session. + session_marked : str | None + ``"1"`` when the session contains the marked pane. + session_name : str | None + Name of the session (the ``#S`` alias). + session_path : str | None + Working directory of the session. + session_stack : str | None + Indexes of the session's windows, most recently used first. + session_windows : str | None + Number of windows in the session. + socket_path : str | None + Path to the tmux server's socket. + start_time : str | None + Time the tmux server started. + synchronized_output_flag : str | None + ``"1"`` when the pane's terminal has synchronized output enabled. + uid : str | None + UID the tmux server runs as. + user : str | None + User the tmux server runs as. + version : str | None + Version of the running tmux server. + window_active : str | None + ``"1"`` when the window is its session's current window. + window_active_clients : str | None + Number of clients viewing the window. + window_active_clients_list : str | None + List of the clients viewing the window. + window_active_sessions : str | None + Number of sessions in which the window is the active one. + window_active_sessions_list : str | None + List of the sessions in which the window is the active one. + window_activity : str | None + Time of the window's last activity. + window_activity_flag : str | None + ``"1"`` when the window has an activity alert. + window_bell_flag : str | None + ``"1"`` when the window has a bell alert. + window_bigger : str | None + ``"1"`` when the window is larger than the client viewing it. + window_cell_height : str | None + Height of one of the window's cells, in pixels. + window_cell_width : str | None + Width of one of the window's cells, in pixels. + window_end_flag : str | None + ``"1"`` when the window has the highest index in the session. + window_flags : str | None + Window flags, with ``#`` escaped as ``##`` (the ``#F`` alias). + window_format : str | None + ``"1"`` when the format is being evaluated for a window. + window_height : str | None + Height of the window, in cells. + window_id : str | None + Unique window ID, e.g. ``"@2"``. + window_index : str | None + Index of the window in its session (the ``#I`` alias). + window_last_flag : str | None + ``"1"`` when the window is the session's last used one. + window_layout : str | None + Window layout description, ignoring zoomed panes. + window_linked : str | None + ``"1"`` when the window is linked across sessions. + window_linked_sessions : str | None + Number of sessions the window is linked into. + window_linked_sessions_list : str | None + List of the sessions the window is linked into. + window_marked_flag : str | None + ``"1"`` when the window contains the marked pane. + window_name : str | None + Name of the window (the ``#W`` alias). + window_offset_x : str | None + X offset into the window when it is larger than the client. + window_offset_y : str | None + Y offset into the window when it is larger than the client. + window_panes : str | None + Number of panes in the window. + window_raw_flags : str | None + Window flags, with nothing escaped. + window_silence_flag : str | None + ``"1"`` when the window has a silence alert. + window_stack_index : str | None + Index of the window in its session's most recently used stack. + window_start_flag : str | None + ``"1"`` when the window has the lowest index in the session. + window_visible_layout : str | None + Window layout description, respecting zoomed panes. + window_width : str | None + Width of the window, in cells. + window_zoomed_flag : str | None + ``"1"`` when the window is zoomed. + wrap_flag : str | None + ``"1"`` when the pane's terminal wraps at the right margin. + Notes ----- tmux may return fields from an object's active children along with the From 52faaa44afe1f1539f9eded64c4a9a5f82fce946 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:40:19 -0500 Subject: [PATCH 4/7] Pane(docs): Document scope and server fields why: autodoc renders every dataclass field whether or not it is described, so Pane's option scope, hook scope, and server fields reach the API reference bare. A reader cannot tell which tmux flag a scope selects, or what the server handle is used for, without reading OptionsMixin and HooksMixin. what: - Add an Attributes section to Pane covering default_option_scope, default_hook_scope, and server - Name the tmux flag each scope sends, and what an unset scope means for set-option, show-options, set-hook, and show-hooks --- src/libtmux/pane.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/libtmux/pane.py b/src/libtmux/pane.py index d10dabb0b..e0c2f5961 100644 --- a/src/libtmux/pane.py +++ b/src/libtmux/pane.py @@ -57,6 +57,22 @@ class Pane( ``Pane`` instances can send commands directly to a pane, or traverse between linked tmux objects. + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``OptionScope.Pane`` sends + ``set-option`` and ``show-options`` with tmux's ``-p`` flag; ``None`` + sends no scope flag, which tmux resolves as session scope. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``OptionScope.Pane`` sends ``set-hook`` + and ``show-hooks`` with tmux's ``-p`` flag; ``None`` sends no scope + flag, which tmux resolves as session scope. + server : Server + Server the pane was queried from, and the connection every command + and refresh runs over. + Examples -------- >>> pane From b921a9d84054b862a42be7fe3eaa0115abea30df Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:40:23 -0500 Subject: [PATCH 5/7] Window(docs): Document scope and server fields why: autodoc renders every dataclass field whether or not it is described, so Window's option scope, hook scope, and server fields reach the API reference bare. A reader cannot tell which tmux flag a scope selects, or what the server handle is used for, without reading OptionsMixin and HooksMixin. what: - Add an Attributes section to Window covering default_option_scope, default_hook_scope, and server - Name the tmux flag each scope sends, and what an unset scope means for set-option, show-options, set-hook, and show-hooks --- src/libtmux/window.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/libtmux/window.py b/src/libtmux/window.py index 02c16f3f6..b57db9969 100644 --- a/src/libtmux/window.py +++ b/src/libtmux/window.py @@ -64,6 +64,22 @@ class Window( ---------- session : :class:`Session` + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``OptionScope.Window`` sends + ``set-option`` and ``show-options`` with tmux's ``-w`` flag; ``None`` + sends no scope flag, which tmux resolves as session scope. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``OptionScope.Window`` sends ``set-hook`` + and ``show-hooks`` with tmux's ``-w`` flag; ``None`` sends no scope + flag, which tmux resolves as session scope. + server : Server + Server the window was queried from, and the connection every command + and refresh runs over. + Examples -------- >>> window = session.new_window('My project', attach=True) From dea94393128c4eb688f3178e6da3b603bba79e0d Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:40:26 -0500 Subject: [PATCH 6/7] Session(docs): Document scope and server fields why: autodoc renders every dataclass field whether or not it is described, so Session's option scope and hook scope fields reach the API reference bare, and the server entry carries a type with no text. Both scopes default to None, which reads as "no scope" rather than the session scope tmux actually applies. what: - Add an Attributes section to Session covering default_option_scope and default_hook_scope - Explain that an unset scope sends no flag, which tmux resolves as session scope, and that OptionScope.Session maps to the same - Describe the server handle on the existing Parameters entry --- src/libtmux/session.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/libtmux/session.py b/src/libtmux/session.py index 31d071aca..4277052a3 100644 --- a/src/libtmux/session.py +++ b/src/libtmux/session.py @@ -62,6 +62,21 @@ class Session( Parameters ---------- server : :class:`Server` + Server the session was queried from, and the connection every command + and refresh runs over. + + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``None`` sends ``set-option`` and + ``show-options`` with no scope flag, which tmux resolves as session + scope; ``OptionScope.Session`` maps to that same empty flag. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``None`` sends ``set-hook`` and + ``show-hooks`` with no scope flag, which tmux resolves as session + scope. Examples -------- From 851e95f363583a57aaa05de3363bb13e647adc80 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 20:13:11 -0500 Subject: [PATCH 7/7] docs(CHANGES) Documented class fields why: The unreleased entry did not record that class fields now carry descriptions where the API reference renders them. what: - Note the described fields under Documentation --- CHANGES | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGES b/CHANGES index ceafe8c33..09fa208fd 100644 --- a/CHANGES +++ b/CHANGES @@ -66,6 +66,13 @@ Workflow actions moved to their current major releases: `actions/checkout` v7, and `dorny/paths-filter` v4. Workflow behavior is unchanged, though setup-uv no longer prunes the uv cache, so the first run after this repopulates it. +#### tmux options, hooks, and formats are described (#721) + +The server, session, window, and pane option classes, the hook table, and +the format object now carry the tmux manual's description for every field. +They previously reached the rendered API reference as "Alias for field +number 0" or as a bare name carrying only its type. + ## libtmux 0.62.0 (2026-07-12) libtmux 0.62.0 teaches libtmux objects to locate themselves and to resolve