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): mserver.options(.pane(pane))

Read effective/inherited: mserver.option(name, scope: .pane(pane)) reads presence from the listing, then the value with -v

Set: mserver.setOption(name, to: value, scope: .pane(pane))

Unset: mserver.unsetOption(name, scope: .pane(pane))

Examples¶

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

try await server.setOption("automatic-rename", to: "off", scope: .pane(pane))
try await server.options(.pane(pane))
try await server.unsetOption("automatic-rename", scope: .pane(pane))

Hooks¶

Set: mserver.setHook(name, to: command, at: index, in: scope)

Unset: mserver.unsetHook(name, in: scope)

List: mserver.hooks(scope)

Run now, without the event: mserver.runHook(name, in: scope)

Examples¶

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

The at: parameter selects the array index.

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

try await server.setHook("session-renamed", to: "display-message 'renamed'", in: .session(session.id.rawValue))
try await server.hooks(.session(session.id.rawValue))

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.

EHookScope restricts registration to .global and .session.

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.