# Libtmux_unix.Client

- **Package:** libtmux-unix
- **Language:** OCaml
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-ocaml/blob/205dfda49742592b479247049d186956e4a4cfe9/unix/libtmux_unix.mli#L186
- **Public owner:** Libtmux_unix
- **Page:** https://libtmux.org/en/ocaml/latest/reference/libtmux_unix-client/

```ocaml
module Client
```

An explicit generation-bound connection. Applications retain ownership of the endpoint choice and resource lifetime.

## Members

### Collections and queries

- [`capture`](/en/ocaml/latest/reference/libtmux_unix-client-capture/) (function): Acquire a complete graph over a recorded interval, with a fixed number of listing commands. Races fail validation. Access to returned values performs no I/O, including after closing the client.

### Common operations

- [`t`](/en/ocaml/latest/reference/libtmux_unix-client-t/) (typealias)
- [`capture_text`](/en/ocaml/latest/reference/libtmux_unix-client-capture_text/) (function): Capture ordinary rendered screen rows, inclusively, via an owned paste buffer and private file. Reject applicable capture/save hooks. The scratch directory defaults to `/tmp` and must be local storage shared with the daemon. Pending and alternate-screen byte modes are unsupported. This observes an interval and establishes no stream continuity barrier.
- [`send_keys`](/en/ocaml/latest/reference/libtmux_unix-client-send_keys/) (function): Send named tmux keys in order, without an implicit Enter. Use {!send_text} for literal bytes rather than key interpretation.
- [`create_session`](/en/ocaml/latest/reference/libtmux_unix-client-create_session/) (function): Create a detached session on the bound daemon. Name collisions fail.
- [`create_window`](/en/ocaml/latest/reference/libtmux_unix-client-create_window/) (function): Create detached, rejecting an occupied explicit index.
- [`split_pane`](/en/ocaml/latest/reference/libtmux_unix-client-split_pane/) (function): Create a detached pane beside the target and return the IDs reported by tmux. Omitted `size` lets tmux choose the split; tmux rejects splits when no space remains.
- [`select_layout`](/en/ocaml/latest/reference/libtmux_unix-client-select_layout/) (function): Apply a preset or validated custom layout to the window. Pane geometry follows tmux layout rules; capture again to observe the result.
- [`kill_session`](/en/ocaml/latest/reference/libtmux_unix-client-kill_session/) (function): Remove the session and its window links. Windows with no other links and their panes are destroyed. Removing the last session may stop tmux.
- [`kill_window`](/en/ocaml/latest/reference/libtmux_unix-client-kill_window/) (function): Destroy the window, all its session links and every contained pane. This acts on the global window, not a single contextual link.
- [`kill_pane`](/en/ocaml/latest/reference/libtmux_unix-client-kill_pane/) (function): Destroy the target pane and its running process. tmux removes a window that becomes empty and may remove its now-empty sessions.
- [`rename_session`](/en/ocaml/latest/reference/libtmux_unix-client-rename_session/) (function): Set the session name, rejecting a conflicting existing name. Bound IDs remain usable; existing snapshots retain their captured names.
- [`rename_window`](/en/ocaml/latest/reference/libtmux_unix-client-rename_window/) (function): Set the global window name. Every session link observes the new name on its next capture; existing snapshots retain the old value.
- [`link_window`](/en/ocaml/latest/reference/libtmux_unix-client-link_window/) (function): Add a session-specific link to the global window at `index`, rejecting an occupied index. The source window and its panes stay shared.
- [`respawn_pane`](/en/ocaml/latest/reference/libtmux_unix-client-respawn_pane/) (function): Start the supplied command in the existing pane. A running process causes failure unless `kill_running:true` explicitly replaces it. The pane ID remains unchanged.
- [`unlink_window_at`](/en/ocaml/latest/reference/libtmux_unix-client-unlink_window_at/) (function): Without `allow_kill`, tmux rejects removal of the last link to a window.
- [`select_window_at`](/en/ocaml/latest/reference/libtmux_unix-client-select_window_at/) (function): Operate on the session's current index at execution, not an old link incarnation.
- [`select_pane`](/en/ocaml/latest/reference/libtmux_unix-client-select_pane/) (function): Make the pane active in its containing window. This does not open or attach a terminal client.
- [`resize_pane`](/en/ocaml/latest/reference/libtmux_unix-client-resize_pane/) (function): Request positive cell dimensions, supplying at least one dimension. Omit either dimension to retain it. tmux can constrain the result to the available layout. Capture again to observe the actual dimensions.
- [`capture_hooks`](/en/ocaml/latest/reference/libtmux_unix-client-capture_hooks/) (function): Capture locally configured built-in hooks. Command values are tmux's printed representation, retained as data.
- [`move_window_at`](/en/ocaml/latest/reference/libtmux_unix-client-move_window_at/) (function): Move the source session's current link at `from_index`. Destination collisions fail.
- [`break_pane`](/en/ocaml/latest/reference/libtmux_unix-client-break_pane/) (function): Move the pane into a new window at an explicit session index. An occupied destination fails. The returned IDs describe the resulting context; the pane itself already existed.
- [`set_pane_title`](/en/ocaml/latest/reference/libtmux_unix-client-set_pane_title/) (function): Set the pane title as literal text, without tmux format expansion. A running terminal application can subsequently replace the title.
- [`swap_panes`](/en/ocaml/latest/reference/libtmux_unix-client-swap_panes/) (function): Exchange pane positions without exchanging their identities or running processes. Both targets must belong to the same bound generation.
- [`clear_history`](/en/ocaml/latest/reference/libtmux_unix-client-clear_history/) (function): Clear stored scrollback for this pane. The visible screen and running process remain; later captures cannot recover discarded history.
- [`capture_options`](/en/ocaml/latest/reference/libtmux_unix-client-capture_options/) (function): Acquire one bounded option table, excluding hooks. The default includes only local entries. Inherited table enumeration includes built-ins; inherited user options require `read_option` with their explicit name. Built-in descriptors cover every supported release from tmux 3.3a through 3.8; other versions return {!Libtmux.Error.Unsupported}.
- [`resize_window`](/en/ocaml/latest/reference/libtmux_unix-client-resize_window/) (function): Request positive cell dimensions, supplying at least one dimension. Omit either dimension to retain it. Client-size and window-size policies can affect subsequent sizing.
- [`move_pane`](/en/ocaml/latest/reference/libtmux_unix-client-move_pane/) (function): Move the source pane beside another pane, optionally setting the split size. Both targets must belong to the same bound generation. An emptied source window is removed by tmux.
- [`rotate_panes`](/en/ocaml/latest/reference/libtmux_unix-client-rotate_panes/) (function): Rotate pane positions in the selected direction. Pane identities and running processes remain attached to their panes.
- [`set_option`](/en/ocaml/latest/reference/libtmux_unix-client-set_option/) (function): Validate the scope and scalar kind before admission. Array values require an index, or `append:true`. Without an index, tmux splits appended text using the option's separator and fills the lowest unused indexes. Text is literal; tmux format expansion is disabled. Hooks use a separate operation.
- [`unset_option`](/en/ocaml/latest/reference/libtmux_unix-client-unset_option/) (function): Remove a local override or one array element. Global built-ins reset to their tmux defaults; this does not recursively unset child overrides.
- [`set_hook`](/en/ocaml/latest/reference/libtmux_unix-client-set_hook/) (function): Set a hook to a nonempty command list. Without an index, replace the whole hook array, or fill the lowest free index when appending. An explicit `@name` custom hook stores command text as a user option; it requires complete replacement and has no array indexes. `read_hook` returns its `Libtmux.Options.Text` value; bulk hook capture includes built-ins. Commands may cause arbitrary tmux effects when triggered. Hooks that print output are outside the supported control transport contract.
- [`capture_environment`](/en/ocaml/latest/reference/libtmux_unix-client-capture_environment/) (function): Acquire a bounded table through a read-only command process. Its response must identify the bound daemon while the original pidfd remains live. Unsupported external variable names fail decoding; they are not omitted.
- [`set_environment`](/en/ocaml/latest/reference/libtmux_unix-client-set_environment/) (function): Set a local environment value for future pane processes. `hidden` defaults to false; hidden values remain internal to tmux. Existing processes keep their environment.
- [`unset_environment`](/en/ocaml/latest/reference/libtmux_unix-client-unset_environment/) (function): Remove the local entry, allowing a global value to apply to future panes.
- [`wait_for`](/en/ocaml/latest/reference/libtmux_unix-client-wait_for/) (function): Wait on a named tmux semaphore using a dedicated bound lane.
- [`read_option`](/en/ocaml/latest/reference/libtmux_unix-client-read_option/) (function): Read one exact name, including user-option inheritance. `None` means no entry under the selected policy. An invalid target remains an error. The default follows inheritance; this does not identify the defining parent scope.
- [`remove_hook`](/en/ocaml/latest/reference/libtmux_unix-client-remove_hook/) (function): Remove the local hook or one indexed array entry. An inherited hook may become effective again; this does not stop work it already started.
- [`version`](/en/ocaml/latest/reference/libtmux_unix-client-version/) (function): Read the bound daemon's observed version without I/O.
- [`remove_environment`](/en/ocaml/latest/reference/libtmux_unix-client-remove_environment/) (function): Store a removal marker, excluding the variable from future panes.
- [`request_detach_client_at`](/en/ocaml/latest/reference/libtmux_unix-client-request_detach_client_at/) (function): Request detachment of the client currently bearing this name. Success confirms request processing, not peer exit. Detaching the library's own primary lane can lose the response and retire its generation.
- [`refresh_client_at`](/en/ocaml/latest/reference/libtmux_unix-client-refresh_client_at/) (function): Request a redraw; no terminal-rendering completion is implied.
- [`switch_client_at`](/en/ocaml/latest/reference/libtmux_unix-client-switch_client_at/) (function): Switch the client currently bearing this name to the bound session. Environment updates are disabled by default. This can move either a terminal client or a control client; it does not open a new terminal.
- [`send_text`](/en/ocaml/latest/reference/libtmux_unix-client-send_text/) (function): Literal bytes, without an implicit Enter. NUL is rejected at admission.

### Other members

- [`await`](/en/ocaml/latest/reference/libtmux_unix-client-await/) (function): Pump admitted work until this operation is finished. Only one blocking caller may own the client at a time. Cancellation removes queued work or drains admitted work before raising `Cancellation.Cancelled`. The handle retains its outcome. Draining has at most one exchange timeout from detection; local scratch filesystem I/O and owned-child cleanup must also finish. Each owned child gets 200 ms of TERM grace before forced termination and reaping; scheduling and kernel completion can add time. No background scheduler or worker is started.
- [`cleanup`](/en/ocaml/latest/reference/libtmux_unix-client-cleanup/) (function): Read the report supplied at connection time, or its fresh default. {!Cleanup.inspect} remains available after close.
- [`clear_option_array`](/en/ocaml/latest/reference/libtmux_unix-client-clear_option_array/) (function): Set a local empty array, masking inheritance.
- [`close`](/en/ocaml/latest/reference/libtmux_unix-client-close/) (function): Close owned control clients and descriptors on the owning domain. Later calls retain the original cleanup result, including failure. Each owned helper gets 200 ms of TERM grace, followed by KILL if needed and reaping. This is not a whole-client deadline or a bound on uninterruptible kernel work. No signal targets the daemon. tmux's `exit-unattached` and `exit-empty` policies can end the daemon after its clients or sessions disappear.
- [`connect`](/en/ocaml/latest/reference/libtmux_unix-client-connect/) (function): Attach to an existing local daemon with at least one session. The caller and daemon must share the PID namespace and filesystem. A local socket pathname alone does not establish these preconditions. `timeout` is the maximum seconds per control exchange, defaulting to one second. Requires Linux pidfd support. The client belongs to the current domain. Initial and auxiliary attachments suppress tmux's `update-environment` behavior.
- [`cycle_layout`](/en/ocaml/latest/reference/libtmux_unix-client-cycle_layout/) (function): Select the next or previous tmux preset layout for this window.
- [`read_hook`](/en/ocaml/latest/reference/libtmux_unix-client-read_hook/) (function): Read an exact hook name. Inheritance is included by default; `None` means no entry under the selected policy. Missing targets remain errors.
- [`resize_control_client_at`](/en/ocaml/latest/reference/libtmux_unix-client-resize_control_client_at/) (function): Set a control client's reported size. tmux rejects terminal clients.
- [`run`](/en/ocaml/latest/reference/libtmux_unix-client-run/) (function): Submit and await. Use the two calls separately to retain an operation handle.
- [`run_hook`](/en/ocaml/latest/reference/libtmux_unix-client-run_hook/) (function): Run the effective hook in an explicit session, window or pane context. A successful result follows completion of its synchronous command queue. Background work started by a hook has its own lifetime. A later hook failure returns an uncertain outcome; preceding effects remain. Named `@` hooks return `Unsupported` because tmux can hide their parse failures in the server log. Configuration and inspection remain available.
- [`signal`](/en/ocaml/latest/reference/libtmux_unix-client-signal/) (function): Signal a named tmux semaphore, releasing a waiter or retaining the signal for a later {!wait_for}. This does not signal an OS process.
- [`source`](/en/ocaml/latest/reference/libtmux_unix-client-source/) (function): Read the retained endpoint, daemon PID and connection generation without I/O.
- [`submit`](/en/ocaml/latest/reference/libtmux_unix-client-submit/) (function): Validate and reserve queue capacity without I/O.
- [`subscribe`](/en/ocaml/latest/reference/libtmux_unix-client-subscribe/) (function): Acquire verified coverage of the pane's observed session/window. Choose the least session ID unless explicitly supplied. Reuse one lane per session. Defaults: 1 MiB and 1024 queued events per subscriber; at most 16 subscribers and eight client lanes including commands. Reserve payload against the shared 32 MiB budget before admission.
- [`wait_for_text`](/en/ocaml/latest/reference/libtmux_unix-client-wait_for_text/) (function): Subscribe, capture the ordinary screen immediately, and recapture after output. Membership/overflow gaps trigger explicit fresh capture and new coverage in the same binding. Maximum pattern: 64 KiB. Success returns a capture that contains the text. Transient text between captures may be missed. Check the deadline between bounded acquisitions; in-flight I/O retains the client's exchange timeout. Release the temporary subscription without replacing an earlier error or cancellation; inspect {!cleanup} for secondary failures. Otherwise cleanup failure prevents success or renewed coverage. No capture/stream barrier exists.
- [`zoom_pane`](/en/ocaml/latest/reference/libtmux_unix-client-zoom_pane/) (function): Toggle the window's zoom state around this pane.

## Guides

Pages that discuss `Client`.

- [Submit actions and retain their outcomes](/en/ocaml/latest/guides/control/)