# Options and hooks

Source: https://libtmux.org/en/py/stable/topics/options-and-hooks/

> Read and update tmux options, and register commands for tmux events.

Use options to change tmux behavior, such as [`automatic-rename`](https://libtmux.org/en/tmux/latest/catalog/options/automatic-rename/) or the
status-line format. Use hooks to run commands on events such as
[`session-renamed`](https://libtmux.org/en/tmux/latest/catalog/hooks/session-renamed/) or [`after-split-window`](https://libtmux.org/en/tmux/latest/catalog/hooks/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.

**Read all (this scope):** [`pane.show_options()`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-show_options/>)

**Read effective/inherited:** [`pane.show_option(name, global_=True)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-show_option/>) reaches the
global fallback explicitly; no separate "resolved" call

**Set:** [`pane.set_option(name, value)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-set_option/>)

**Unset:** [`pane.unset_option(name)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-unset_option/>)

### Examples

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

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

## Hooks

**Set:** [`pane.set_hook(name, command)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-set_hook/>)

**Unset:** [`pane.unset_hook(name)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-unset_hook/>)

**List:** [`pane.show_hook(name)`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-show_hook/>), [`pane.show_hooks()`](<https://libtmux.org/en/py/stable/reference/libtmux-pane-show_hooks/>) (all)

**Run now, without the event:** Not listed.

### Examples

tmux stores hook commands in indexed arrays, such as [`after-new-window[0]`](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-window/).

Include the array index in the hook name.

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

```python
session.set_hook("session-renamed", "display-message 'renamed'")
session.show_hooks()
```

<a id="window-and-pane-hook-scopes-are-mostly-fiction"></a>

## Supported hook scopes

tmux stores hooks globally or per session. Accepted [`set-hook -w`](https://libtmux.org/en/tmux/latest/manual/set-hook/) or `-p` flags
do not imply a separate window or pane hook table, and [`show-hooks`](https://libtmux.org/en/tmux/latest/manual/show-hooks/) does not
provide a corresponding listing. Check the event's supported scope if a hook is
accepted but never fires.

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:

| Feature | Minimum tmux |
|---------|-------------|
| All options/hooks features | 3.2+ |
| Window/pane hook *scope flags* (`-w`, `-p`) accepted | 3.2+; see the supported-scope caveat above |
| [`client-active`](https://libtmux.org/en/tmux/latest/catalog/hooks/client-active/), [`window-resized`](https://libtmux.org/en/tmux/latest/catalog/hooks/window-resized/) hooks | 3.3+ |
| [`pane-title-changed`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-title-changed/) hook | 3.2+ |

The [`pane-title-changed`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-title-changed/) hook was
[added before tmux 3.2](https://github.com/tmux/tmux/commit/d329b035cee47d968a8c93b5cbd8fde879ce6f0d).
It is present in both the documented
[3.2a source](https://github.com/tmux/tmux/blob/3b929f332aafa7f1080eacc31feb11ffbb1d1841/options-table.c#L1143)
and the
[3.7c source](https://github.com/tmux/tmux/blob/e476c1230b958df0cb12977517d24b3dc931375b/options-table.c#L1700).

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

<details>
<summary>tmux manual and source</summary>

The tmux manual defines [option scopes and inherited reads](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/tmux.1#L4725).
Unsetting a local value restores inheritance. Hook programs run in tmux when
their event occurs; see the [hook implementation](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/cmd-set-option.c).

</details>