# tmux_pane

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

Create, observe and rearrange panes using registered physical IDs.

`split/2` accepts a pane or a window; a window means its active pane
at execution. Options (`t:split_options/0`) are direction
(horizontal or vertical), size ({cells, N} or {percent, N}), before,
full_size, zoom, cwd, env, launch and detach. It defaults to a detached
vertical split. `get/2` returns newly observed fields; existing rows
remain unchanged. Reads span several commands and do not claim atomicity.
Launch and environment options follow `tmux_session:create/2`. An absent or
zero tmux pane_pid is represented as none. A captured positive PID is an
observation, not a guarantee that the process remains alive.

A successful split followed by a failed observation retains the completed
mutation and command result in its error. `kill/1` returns the
command result. Detached or stale references cannot act. `resize_command/2`
builds a reusable value without tmux I/O; the other calls perform I/O after
validation.

`send_text/2` sends up to 2,000 literal bytes, including NUL, in one
command using tmux's hexadecimal key form. It adds no Enter key and never
splits a large input into partially applied commands. `send_keys/2`
accepts up to 256 named keys, single UTF-8 characters, {function, 1..12} and
{control, <<Letter>>}. Named keys are enter, tab, escape, backspace, space,
up, down, left, right, home, 'end', insert, delete, page_up, page_down and
back_tab. Terminal modes still govern how input is consumed; command
completion does not mean a program processed it.

`capture/2` returns stdout bytes unchanged, including final
newlines. Options (`t:capture_options/0`) are start and 'end' (line
integers or all), join_lines, escape_sequences, escape_control,
retain_trailing_spaces, alternate, pending and quiet. Defaults are tmux's
current-screen capture without escapes, joined wraps or padding. The
endpoint's output limit applies; an oversized capture returns an error.

Use `join/3`, `move/3` and `swap/3` to rearrange existing panes without
respawning their processes. `break/4` takes an explicit source window link:
breaking a window's only pane moves that membership, while breaking one of
several panes creates a new physical window. The [topology guide](panes.md)
shows the distinction. Use `get/2` or a new snapshot for updated parents and
indexes; actions leave captured values unchanged.

`pipe/3` connects a tmux-owned shell process to pane output, input or both.
It protects the shell text from tmux hash/strftime expansion; shell quoting
remains the caller's responsibility. `stop_pipe/1` closes that native pipe.
These actions do not create an Erlang output subscription or transfer process
ownership to the endpoint. Use an application acknowledgement for consumer
readiness, delivered bytes and job completion.

## Members

### Common operations

- [`capture/2`](/en/erlang/latest/reference/tmux_pane-capture-2/) (function): Capture terminal bytes, preserving final newlines. Options select line range, joined wraps, escapes, alternate screen and padding; defaults follow tmux current-screen capture. Performs I/O and returns an explicit output-limit error instead of silently truncating.
- [`send_keys/2`](/en/erlang/latest/reference/tmux_pane-send_keys-2/) (function): Send at most 256 validated key tokens. Named keys, single UTF-8 characters, function keys and control-letter tuples are supported. Performs I/O; terminal modes determine the resulting input bytes. Use `send_text/2` for arbitrary bytes.
- [`split/2`](/en/erlang/latest/reference/tmux_pane-split-2/) (function): Split a pane, or the supplied window's active pane, and observe the new pane. Defaults to a detached vertical split. Options and launch semantics are described in the module docs. Performs I/O; a post-creation read error retains the completed mutation rather than pretending that no pane was created.
- [`kill/1`](/en/erlang/latest/reference/tmux_pane-kill-1/) (function): Destroy this registered pane. Performs I/O after validating its origin and stable ID; it never falls back to a positional target.
- [`respawn/2`](/en/erlang/latest/reference/tmux_pane-respawn-2/) (function): Respawn this registered physical pane, keeping its pane ID. force defaults false and a running pane normally returns command_error. force = true lets tmux close its existing PTY before spawning again. This acknowledges the tmux command, not former-job termination or successful application initialization. The old PTY can already be closed if a later spawn step fails.
- [`resize/2`](/en/erlang/latest/reference/tmux_pane-resize-2/) (function): Request an absolute width, height or both for this registered physical pane. Performs I/O after validating dimensions and origin. tmux can clamp the request to its layout constraints and can resize neighboring panes. Resizing a tiled pane unzooms its window. Use `get/2` for actual dimensions; the input row is unchanged. The accepted library range is not a promise that every server accepts every dimension: tmux versions can impose tighter limits and return a command error.
- [`break/4`](/en/erlang/latest/reference/tmux_pane-break-4/) (function): Break a physical pane through its explicit source membership into a destination session/index. Source, link and session must have the same registered owner. The source link's expected window and the pane's observed parent are checked before dispatch. The source selector also includes the stable pane ID, never its positional index. Preflight and action are not atomic.
- [`swap/3`](/en/erlang/latest/reference/tmux_pane-swap-3/) (function): Exchange two panes' layout positions within or across physical windows. Preserves their IDs and processes; parent windows, dimensions, indexes and inherited options can change. Both rows require the same registered owner. detach defaults true; active positions can still receive different panes. zoom maps to native -Z. Identical IDs do not exchange panes, but native zoom handling still runs; the default can unzoom even a same-pane swap. Returns the command result; `get/2` observes the resulting values explicitly.
- [`join/3`](/en/erlang/latest/reference/tmux_pane-join-3/) (function): Move a source pane into a split beside the destination pane. Both physical IDs must belong to the same registered owner and must differ. Geometry follows `t:join_options/0`. Existing processes and pane IDs survive; dimensions, indexes and inherited window options can change. Removing a window's last pane destroys that physical window and its links, and can remove sessions.
- [`pipe/3`](/en/erlang/latest/reference/tmux_pane-pipe-3/) (function): Connect a shell process to this registered physical pane, performing I/O. An explicit nonempty `#{shell => Command}` is required (`t:pipe_command/0`). tmux hash formats and strftime directives are escaped so the shell receives the supplied text. This does not quote values interpolated into shell code; the caller owns that quoting. Executable argv is not accepted by this shell-only native command. Encoding follows `tmux_command:literal_format/2` in time mode. A percent-bearing command above its native 8191-byte intermediate limit returns `format_limit` before dispatch, preserving any existing pipe.
- [`get/2`](/en/erlang/latest/reference/tmux_pane-get-2/) (function): Read fresh fields for a physical pane ID. Performs I/O and returns target_gone for a vanished pane. A captured PID remains an observation, not a live-process guarantee.
- [`move/3`](/en/erlang/latest/reference/tmux_pane-move-3/) (function): Rearrange a source pane beside the destination, including within one window. Uses native move-pane, whose placement and lifetime behavior follow `join/3`. Both calls use explicit physical IDs and leave captured rows unchanged.
- [`stop_pipe/1`](/en/erlang/latest/reference/tmux_pane-stop_pipe-1/) (function): Close this registered pane's native pipe, performing I/O. On a live pane, closing an already closed pipe succeeds. An exited pane can produce a native command error; a vanished ID returns `target_gone`.
- [`join_options/0`](/en/erlang/latest/reference/t-tmux_pane-join_options-0/) (typealias): Join/move geometry: detach true, vertical split by default. before and full_size follow tmux layout rules.
- [`resize_command/2`](/en/erlang/latest/reference/tmux_pane-resize_command-2/) (function): Build a resize command without tmux I/O. Uses the dimensions and validation rules of `resize/2`, preserving the row's captured origin and stable pane ID. Endpoint liveness and native layout constraints are checked during execution. Submit through `tmux_server:command/3` or `tmux_operation:start/3`.

### Other members

- [`break_options/0`](/en/erlang/latest/reference/t-tmux_pane-break_options-0/) (typealias): Break placement: explicit destination index, optional literal window name. detach defaults true.
- [`capture_options/0`](/en/erlang/latest/reference/t-tmux_pane-capture_options-0/) (typealias): Capture range and rendering flags. Byte output and its final newline are preserved.
- [`coordinate/0`](/en/erlang/latest/reference/t-tmux_pane-coordinate-0/) (typealias): A capture line coordinate, or all for tmux's full available range.
- [`key/0`](/en/erlang/latest/reference/t-tmux_pane-key-0/) (typealias): A validated named key, single UTF-8 character, function key or control-letter key.
- [`pipe_command/0`](/en/erlang/latest/reference/t-tmux_pane-pipe_command-0/) (typealias): Explicit shell code: a nonempty NUL-free binary, with no tmux format or strftime expansion.
- [`pipe_options/0`](/en/erlang/latest/reference/t-tmux_pane-pipe_options-0/) (typealias): Pipe direction defaults to output. toggle defaults false; true closes an existing pipe instead of replacing it.
- [`resize_options/0`](/en/erlang/latest/reference/t-tmux_pane-resize_options-0/) (typealias): Requested absolute pane dimensions in cells. Supply at least one dimension; tmux can clamp it to fit the layout.
- [`respawn_options/0`](/en/erlang/latest/reference/t-tmux_pane-respawn_options-0/) (typealias): Respawn options. Defaults: force false, launch previous, saved cwd. Environment augments tmux's resolved session environment for this spawn.
- [`send_text/2`](/en/erlang/latest/reference/tmux_pane-send_text-2/) (function): Send at most 2,000 literal bytes as hexadecimal tmux keys. Adds no Enter key and does not invoke a shell. Performs I/O in one command; oversized input is rejected before partial submission. Completion does not prove that a terminal program processed the input.
- [`split_options/0`](/en/erlang/latest/reference/t-tmux_pane-split_options-0/) (typealias): Split geometry, placement and explicit launch options. Defaults to a detached vertical split.
- [`swap_options/0`](/en/erlang/latest/reference/t-tmux_pane-swap_options-0/) (typealias): Swap controls: detach defaults true; zoom maps to tmux -Z to retain zoom.

## Guides

Pages that discuss `tmux_pane`.

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