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

class

Bases: CmdMixin

Mixin for manager scoped hooks in tmux.

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

__init__(default_hook_scope)

method

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

Parameters:

default_hook_scope (OptionScope | None)

Return type:

None

default_hook_scope: OptionScope | None

attribute

hooks: Hooks

attribute

property _tmux_bin: str | None

property

Resolve tmux_bin from self (Server) or self.server (Session/Window/Pane).

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

method

Run a hook immediately. Useful for testing.

Parameters:

• hook (str)

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

Return type:

Self

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

method

Set hook for tmux target.

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

Parameters:

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

• value (int | str) – hook command.

• unset (bool | None)

• run (bool | None)

• append (bool | None)

• g (bool | None)

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

Return type:

Self

:raises exc.OptionError, exc.UnknownOption,: :raises exc.InvalidOption, exc.AmbiguousOption:

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

method

Unset hook for tmux target.

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

Parameters:

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

• global_ (bool | None)

• scope (OptionScope | _DefaultOptionScope | None)

Return type:

Self

:raises exc.OptionError, exc.UnknownOption,: :raises exc.InvalidOption, exc.AmbiguousOption:

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

method

Return a dict of hooks for the target.

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>)

method

Return value for the hook.

Parameters:

• hook (str)

• global_ (bool)

• scope (OptionScope | _DefaultOptionScope | None)

Return type:

list[str] | None

:raises exc.OptionError, exc.UnknownOption,: :raises exc.InvalidOption, exc.AmbiguousOption:

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

method

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.

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.UnknownOption,: :raises exc.InvalidOption, exc.AmbiguousOption:

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>)

method

Set multiple indexed hooks at once.

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($...)