Hooks

Helpers for tmux hooks.

tmux Hook Features

Hooks are array options (e.g., session-renamed[0], session-renamed[1]) with sparse index support (can have gaps: [0], [5], [10]).

All features available in libtmux’s minimum supported version (tmux 3.2+):

• Session, window, and pane-level hooks

• Window hooks via -w flag, pane hooks via -p flag

• Hook scope separation (session vs window vs pane)

tmux 3.3+: - client-active hook - window-resized hook

tmux 3.5+: - pane-title-changed hook - client-light-theme / client-dark-theme hooks - command-error hook

Bulk Operations API

This module provides bulk operations for managing multiple indexed hooks:

• set_hooks() - Set multiple hooks at once

class libtmux.hooks.HooksMixin

Mixin for manager scoped hooks in tmux.

Requires tmux 3.1+. For older versions, use raw commands.

When not a user (custom) hook, scope can be implied.

__init__(default_hook_scope)

When not a user (custom) hook, scope can be implied.

Parameters:

default_hook_scope (OptionScope | None)

Return type:

None

run_hook(hook, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)

Run a hook immediately. Useful for testing.

Return type:

Self

Parameters:

• hook (str)

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)

Set hook for tmux target.

Wraps $ tmux set-hook <hook> <value>.

Return type:

Self

Parameters:

• hook (str) – hook to set, e.g. ‘aggressive-resize’

• value (str) – hook command.

• unset (bool | None)

• run (bool | None)

• append (bool | None)

• g (bool | None)

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

Raises:

• exc.OptionError –

• exc.InvalidOption –

unset_hook(hook, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)

Unset hook for tmux target.

Wraps $ tmux set-hook -u <hook> / $ tmux set-hook -U <hook>

Return type:

Self

Parameters:

• hook (str) – hook to unset, e.g. ‘after-show-environment’

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

Raises:

• exc.OptionError –

• exc.InvalidOption –

show_hooks(global_=False, scope=<libtmux.constants._DefaultOptionScope object>)

Return a dict of hooks for the target.

Return type:

dict[str, Any]

Parameters:

• global (bool, optional) – Pass -g flag for global hooks, default False.

• scope (OptionScope | _DefaultOptionScope | None, optional) – Hook scope (Server/Session/Window/Pane), defaults to object’s scope.

• global_ (bool | None)

Returns:

Dictionary mapping hook names to their values.

Return type:

HookDict

Examples

>>> session.set_hook('session-renamed[0]', 'display-message "test"')
Session($...)

>>> hooks = session.show_hooks()
>>> isinstance(hooks, dict)
True

>>> 'session-renamed[0]' in hooks
True

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

show_hook(hook, global_=False, scope=<libtmux.constants._DefaultOptionScope object>)

Return value for a hook.

For array hooks (e.g., session-renamed), returns a SparseArray with hook values at their original indices. Use .keys() for indices and .values() for values.

Return type:

str | int | SparseArray[str] | None

Parameters:

• hook (str) – Hook name to query

• global_ (bool)

• scope (OptionScope | _DefaultOptionScope | None)

Returns:

Hook value. For array hooks, returns SparseArray.

Return type:

str | int | SparseArray[str] | None

Raises:

• exc.OptionError –

• exc.InvalidOption –

Examples

>>> session.set_hook('session-renamed[0]', 'display-message "test"')
Session($...)

>>> hooks = session.show_hook('session-renamed')
>>> isinstance(hooks, SparseArray)
True

>>> sorted(hooks.keys())
[0]

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

set_hooks(hook, values, *, clear_existing=False, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)

Set multiple indexed hooks at once.

Return type:

Self

Parameters:

• hook (str) – Hook name, e.g. ‘session-renamed’

• values (HookValues) – Values to set. Can be: - dict[int, str]: {0: ‘cmd1’, 1: ‘cmd2’} - explicit indices - SparseArray[str]: preserves indices from another hook - list[str]: [‘cmd1’, ‘cmd2’] - sequential indices starting at 0

• clear_existing (bool) – If True, unset all existing hook values first

• global (bool | None) – Use global hooks

• scope (OptionScope | None) – Scope for the hook

• global_ (bool | None)

Returns:

Returns self for method chaining.

Return type:

Self

Examples

Set hooks with explicit indices:

>>> session.set_hooks('session-renamed', {
...     0: 'display-message "hook 0"',
...     1: 'display-message "hook 1"',
... })
Session($...)

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

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

Set hooks from a list (sequential indices):

>>> session.set_hooks('after-new-window', [
...     'select-pane -t 0',
...     'send-keys "clear" Enter',
... ])
Session($...)

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

Replace all existing hooks with clear_existing=True:

>>> session.set_hooks(
...     'session-renamed',
...     {0: 'display-message "new"'},
...     clear_existing=True,
... )
Session($...)

>>> hooks = session.show_hook('session-renamed')
>>> sorted(hooks.keys())
[0]

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

>>> session.unset_hook('after-new-window')
Session($...)