Options and hooks

Use options to change tmux behavior, such as automatic-rename or the status-line format. Use hooks to run commands on events such as session-renamed or after-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.

Python¶

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

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

Set: pane.set_option(name, value)

Unset: pane.unset_option(name)

TypeScript¶

Read all (this scope): pane.showOptions()

Read effective/inherited: pane.showResolvedOptions()

Set: pane.setOption(name, value)

Unset: pane.unsetOption(name)

Go¶

pane.Options(ctx) returns a fresh typed snapshot, including inherited values. Its accessors return an OptionValue; use OptionValue.Get to distinguish a present value from an absent one. Check the read error before inspecting the snapshot.

Use the handle that owns the option's scope. For example, automatic-rename belongs to a window: use Window.SetOption or Window.UnsetOption, then read Window.Options again for an updated snapshot.

For a single raw value, Pane.RawOption returns the string, its presence, and an error. Do not treat an error as an absent option.

Rust¶

Read all (this scope): pane.options() (typed BTreeMap), pane.option_names()

Read effective/inherited: pane.typed_option(name) decodes one value by its declared kind

Set: pane.set_option(name, value), pane.append_option(name, value)

Unset: pane.unset_option(name)

Java¶

Read all (this scope): pane.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)

C#¶

Read all (this scope): pane.Options.GetAllAsync()

Read effective/inherited: pane.Options.GetAsync(new GetOptionRequest(name, includeInherited: true)): an explicit opt-in flag, mapped straight to tmux's own -A

Set: pane.Options.SetAsync(new SetOptionRequest(name, value))

Unset: pane.Options.UnsetAsync(...)

C++¶

Read all (this scope): pane->options()

Read effective/inherited: Not listed.

Set: pane->set_option(name, value)

Unset: pane->unset_option(name)

Swift¶

Read all (this scope): server.options(.pane(pane))

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

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

Unset: server.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:

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

await pane.setOption("automatic-rename", "off");
await pane.showOptions();
await pane.unsetOption("automatic-rename");

if err := window.SetOption(ctx, "automatic-rename", "off", tmux.SetOptionOptions{}); err != nil {
    return fmt.Errorf("set automatic rename: %w", err)
}
options, err := window.Options(ctx)
if err != nil {
    return fmt.Errorf("read window options: %w", err)
}
value, present := options.AutomaticRename().Get()
fmt.Println("automatic rename:", value, "present:", present)
if err := window.UnsetOption(ctx, "automatic-rename", tmux.UnsetOptionOptions{}); err != nil {
    return fmt.Errorf("unset automatic rename: %w", err)
}

pane.set_option("automatic-rename", "off").await?;
pane.options().await?;
pane.unset_option("automatic-rename").await?;

pane.options().set("automatic-rename", "off");
pane.options().all();
pane.options().unset("automatic-rename");

await pane.Options.SetAsync(new SetOptionRequest("automatic-rename", "off"));
await pane.Options.GetAllAsync();
await pane.Options.UnsetAsync("automatic-rename");

pane->set_option("automatic-rename", "off");
pane->options();
pane->unset_option("automatic-rename");

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¶

Python¶

Set: pane.set_hook(name, command)

Unset: pane.unset_hook(name)

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

Run now, without the event: Not listed.

TypeScript¶

Set: pane.setHook(name, command, { append })

Unset: pane.unsetHook(name)

List: pane.showHooks() (all; no singular showHook)

Run now, without the event: Not listed.

Go¶

Use session.SetHook to register a command and session.Hooks to read the session's typed hook values. session.UnsetHook removes a registration. Session.SetHooks writes indexed entries when an event needs more than one command.

Use server.GlobalSessionScope() for hooks shared by sessions. Keep hook registration at a scope supported by the tmux event.

Rust¶

Set: pane.set_hook(name, command)

Unset: pane.unset_hook(name)

List: pane.hook(name): one name only; no listing at pane/window scope, by design (see below)

Run now, without the event: Not listed.

Java¶

Set: pane.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

C#¶

Set: pane.Hooks.SetAsync(new SetHookRequest(event, command))

Unset: pane.Hooks.UnsetAsync(...)

List: pane.Hooks.GetAllAsync()

Run now, without the event: pane.Hooks.RunAsync(...)

C++¶

Set: session.set_hook(name, command): no Window/Pane overload exists at all

Unset: Not listed.

List: session.hooks(), server.global_hooks()

Run now, without the event: Not listed.

Swift¶

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

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

List: server.hooks(scope)

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

Examples¶

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

Include the array index in the hook name. Include the array index in the hook name or pass { append: true } to append. Session.SetHooks accepts indexed hook entries. Pass a context and check errors from both mutations and reads; a successful write does not refresh earlier snapshots. The at: parameter selects the array index. 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.set_hook("session-renamed", "display-message 'renamed'")
session.show_hooks()

await session.setHook("session-renamed", "display-message 'renamed'");
await session.showHooks();

if err := session.SetHook(ctx, "session-renamed", "display-message 'renamed'"); err != nil {
    return fmt.Errorf("set session hook: %w", err)
}
value, present, err := session.RawHook(ctx, "session-renamed")
if err != nil {
    return fmt.Errorf("read session hooks: %w", err)
}
fmt.Println("session-renamed:", value, "present:", present)

session.set_hook("session-renamed", "display-message 'renamed'").await?;
session.hooks().await?;

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

await session.Hooks.SetAsync(new SetHookRequest("session-renamed", "display-message 'renamed'"));
await session.Hooks.GetAllAsync();

session.set_hook("session-renamed", "display-message 'renamed'");
session.hooks(); // No session unset helper is listed above.

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.

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

Pane::set_hook and Window::set_hook return Error::OptionScopeMismatch for an unsupported scope.

HookScope restricts registration to .global and .session.

Use Session::set_hook or Server::global_hooks(). Window and pane handles do not provide hook methods.

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:

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

Use the command references for show-options, set-option, show-hooks, and set-hook to check the flags and scope rules for your tmux version.