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.options().all()

Read effective/inherited: pane.options().get(name) reads $show-options -A -v: inherited, not just local

Set: pane.options().set(name, value)

Unset: pane.options().unset(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.options().set("automatic-rename", "off");
pane.options().all();
pane.options().unset("automatic-rename");

Hooks¶

Set: mpane.hooks().set(event, command), .append(event, command)

Unset: pane.hooks().unset(event)

List: pane.hooks().all()

Run now, without the event: pane.hooks().run(event): tmux’s $set-hook -R

Examples¶

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

Use .append() to add a command without choosing the next array index.

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

session.hooks().set("session-renamed", "display-message 'renamed'");
session.hooks().all();

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.

Check hooks().all() when diagnosing a hook that does not fire. tmux can accept a hook at an unsupported scope without an effective registration.

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

tmux version compatibility¶

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