Options and hooks

Use options to change tmux behavior, such as oautomatic-rename or the status-line format. Use hooks to run commands on events such as hsession-renamed or hafter-split-window. Choose the scope supported by the option or hook.

Reading and writing options¶

Read, set, or unset an option at its supported scope. Distinguish a local override from the effective value inherited from a parent scope.

Read all (this scope): mpane.show_options()

Read effective/inherited: mpane.show_option(name, global_=True) reaches the global fallback explicitly; no separate “resolved” call

Set: mpane.set_option(name, value)

Unset: mpane.unset_option(name)

Examples¶

After a successful write completes, read the option to obtain its updated value. The following examples set, read, and unset an option:

pane.set_option("automatic-rename", "off")
pane.show_options()
pane.unset_option("automatic-rename")

Hooks¶

Set: mpane.set_hook(name, command)

Unset: mpane.unset_hook(name)

List: mpane.show_hook(name), mpane.show_hooks() (all)

Run now, without the event: Not listed.

Examples¶

tmux stores hook commands in indexed arrays, such as hafter-new-window[0].

Include the array index in the hook name.

Set and list a session hook. The next section explains window and pane scope limitations:

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

Supported hook scopes¶

tmux stores hooks globally or per session. Accepted $set-hook -w or -p flags do not imply a separate window or pane hook table, and $show-hooks does not provide a corresponding listing. Check the event’s supported scope if a hook is accepted but never fires.

Options have window and pane tables of their own. The hook-scope limitation does not apply to ordinary options.

tmux version compatibility¶

The compatibility notes list these tmux requirements:

The pane-title-changed hook was added before tmux 3.2. It is present in both the documented 3.2a source and the 3.7c source.

Check the library’s supported tmux versions before using a version-specific option or hook.