Options and Hooks¶

libtmux provides a unified API for managing tmux options and hooks across all object types (Server, Session, Window, Pane).

Options¶

tmux options control the behavior and appearance of sessions, windows, and panes. libtmux provides a consistent interface through OptionsMixin.

Getting options¶

Use show_options() to get all options:

>>> session.show_options()
{...}

Use show_option() to get a single option:

>>> server.show_option('buffer-limit')
50

Setting options¶

Use set_option() to set an option:

>>> window.set_option('automatic-rename', False)
Window(@... ...)

>>> window.show_option('automatic-rename')
False

Unsetting options¶

Use unset_option() to revert an option to its default:

>>> window.unset_option('automatic-rename')
Window(@... ...)

Option scopes¶

tmux options exist at different scopes. Use the scope parameter to specify:

>>> from libtmux.constants import OptionScope

>>> # Get window-scoped options from a session
>>> session.show_options(scope=OptionScope.Window)
{...}

Global options¶

Use global_=True to work with global options:

>>> server.show_option('buffer-limit', global_=True)
50

Hooks¶

tmux hooks allow you to run commands when specific events occur. libtmux provides hook management through HooksMixin.

Setting and getting hooks¶

Use set_hook() to set a hook and show_hook() to get its value:

>>> session.set_hook('session-renamed', 'display-message "Session renamed"')
Session(...)

>>> session.show_hook('session-renamed')
{0: 'display-message "Session renamed"'}

>>> session.show_hooks()
{...}

Note that hooks are stored as indexed arrays in tmux, so show_hook() returns a SparseArray (dict-like) with index keys.

Removing hooks¶

Use unset_hook() to remove a hook:

>>> session.unset_hook('session-renamed')
Session(...)

Indexed hooks¶

tmux hooks support multiple values via indices (e.g., session-renamed[0], session-renamed[1]). This allows multiple commands to run for the same event:

>>> session.set_hook('after-split-window[0]', 'display-message "Split 0"')
Session(...)

>>> session.set_hook('after-split-window[1]', 'display-message "Split 1"')
Session(...)

>>> hooks = session.show_hook('after-split-window')
>>> sorted(hooks.keys())
[0, 1]

The return value is a SparseArray, which preserves sparse indices (e.g., indices 0 and 5 with no 1-4).

Bulk hook operations¶

Use set_hooks() to set multiple indexed hooks:

>>> session.set_hooks('window-linked', {
...     0: 'display-message "Window linked 0"',
...     1: 'display-message "Window linked 1"',
... })
Session(...)

>>> # Clean up
>>> session.unset_hook('after-split-window[0]')
Session(...)
>>> session.unset_hook('after-split-window[1]')
Session(...)
>>> session.unset_hook('window-linked[0]')
Session(...)
>>> session.unset_hook('window-linked[1]')
Session(...)

tmux version compatibility¶

Feature	Minimum tmux
All options/hooks features	3.2+
Window/Pane hook scopes (`-w`, `-p`)	3.2+
`client-active`, `window-resized` hooks	3.3+
`pane-title-changed` hook	3.5+