# tmux_hook

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_hook.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_hook/

Store builtin hook commands and run them in an explicit observed context.

`set/3` replaces one indexed entry. `append/3` uses tmux's first vacant index;
`clear/2` leaves an empty local array and `unset/2` restores inheritance.
`get/3` reads local values unless inheritance is requested. Commands are
`t:tmux_command:t/0` values, rendered by `tmux_command:to_config/1` before tmux
parses and stores them. A successful write confirms registration, while later
hook effects need their own completion evidence.

Table scope and execution context are separate. `run/2` selects a session,
checked window link or checked pane/link pair. Physical windows can belong to
several sessions; a link preserves the chosen session and index. Preflight and
dispatch are separate observations, with no atomic compare-and-act guarantee.
Known restarts and closed owners invalidate references. Captured rows never
refresh during these actions.

Names and table scopes use the exact source-derived version catalogue from
`tmux_option:catalogue/1`. User options, prefixes and aliases are rejected.
The native custom-event and monitor interfaces are outside this API. Deliberate
raw integration remains available through `tmux_command:raw/2`. Calls perform
I/O after validation and never retry uncertain mutations. The
[hook guide](hooks.md) demonstrates registration and an effect acknowledgement.

## Members

### Common operations

- [`set/3`](/en/erlang/latest/reference/tmux_hook-set-3/) (function): Replace one {Name, Index} entry with validated command values. An explicit index is required; other entries remain. Indexes range from zero to 2147483647. The rendered command text is bounded before dispatch. Native commands still interpret their arguments and formats when the hook later runs. Use `append/3` for native vacant-index selection and `clear/2` to mask inherited hooks with an empty local array.
- [`get/3`](/en/erlang/latest/reference/tmux_hook-get-3/) (function): Read a builtin hook array or indexed entry. Options follow `t:tmux_option:read_options/0`: local-only by default, inherit = true follows its parent tables. Missing local arrays or entries return none; an empty local array returns {ok, #{}} and masks inheritance.
- [`run/2`](/en/erlang/latest/reference/tmux_hook-run-2/) (function): Request native set-hook -R in the explicit `t:context/0`. tmux resolves the hook through that context's effective tables; global table flags do not select a separate execution scope. A session uses its current window and pane. A window link fixes the observed session/index and expected physical window; a pane context additionally checks that pane's observed parent.

### Other members

- [`append/3`](/en/erlang/latest/reference/tmux_hook-append-3/) (function): Store commands at tmux's first vacant local index for the unindexed name. A new local array starts independently of inherited entries; this does not copy the parent's array. The command result does not report the chosen index; `get/3` observes current entries separately. Performs I/O with the parsing and unknown-outcome semantics of `set/3`.
- [`clear/2`](/en/erlang/latest/reference/tmux_hook-clear-2/) (function): Leave an empty local hook array, masking inherited entries. This differs from `unset/2`, which restores inheritance. Global clear empties that defaults table. Performs I/O; existing effects already queued by tmux are not cancelled.
- [`commands/0`](/en/erlang/latest/reference/t-tmux_hook-commands-0/) (typealias): One validated command or a nonempty list; at most 256 commands and 32 KiB rendered text.
- [`context/0`](/en/erlang/latest/reference/t-tmux_hook-context-0/) (typealias): A session's current context, one observed membership, or a pane in that membership.
- [`scope/0`](/en/erlang/latest/reference/t-tmux_hook-scope-0/) (typealias): A registered local table or explicit global session/window defaults; see `t:tmux_option:scope/0`.
- [`unset/2`](/en/erlang/latest/reference/tmux_hook-unset-2/) (function): Remove one indexed entry or the whole local array. Removing an entry leaves its local array, possibly empty. Removing the whole array restores inheritance; unsetting a global builtin resets its native default. Missing local values are a successful native no-op. Performs I/O; queued hook effects are unaffected.
- [`value/0`](/en/erlang/latest/reference/t-tmux_hook-value-0/) (typealias): Canonical native command-list text, or a sparse map of indexes to that text.

## Guides

Pages that discuss `tmux_hook`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)