# libtmux

- **Package:** libtmux
- **Language:** Common Lisp
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-lisp/blob/c2e5fc4ed3befda21f45dfa5d5868c38fd138311/src/package.lisp#L1
- **Page:** https://libtmux.org/en/lisp/latest/reference/libtmux/

Native Common Lisp captured tmux graphs and explicit external operations.
OPEN-CLIENT/WITH-CLIENT establish connection scopes without starting a daemon.
FETCH-SNAPSHOT acquires sessions, physical windows, panes, window links and
attached clients. Captured getters, traversal and ENTITY-DATA are local and
remain usable after closure; captured strings and containers are owned copies. REFRESH returns
a new observation. Named mutators take CLIENT first and return COMMAND-OUTCOME;
OUTCOME-VALUE and FIELD-VALUE return value and presence as two values.
Operations are synchronous, bounded and cancellable, with one active operation
per client. Typed LIBTMUX-ERROR conditions retain diagnostic outcome and cause.
Closing a client releases owned resources and leaves the daemon alive.
START-DAEMON/WITH-DAEMON separately own a new empty-config foreground daemon;
STOP-DAEMON releases that owner, with incomplete cleanup retained for retry.
See docs/index.md for the tutorial, API reference and current capability limits.

## Members

### Collections and queries

- [`sessions`](/en/lisp/latest/reference/libtmux-sessions/) (function): Return a fresh vector of physical sessions in captured wire order. No I/O.
- [`windows`](/en/lisp/latest/reference/libtmux-windows/) (function): Return a fresh vector of captured windows, without I/O.
Snapshot windows are physical entities in first-occurrence order. Session
windows contain one item per link and preserve repeated physical windows.
- [`panes`](/en/lisp/latest/reference/libtmux-panes/) (function): Return a fresh vector of captured physical panes, without I/O.
Snapshots preserve first occurrence; windows preserve the captured pane order.
- [`clients`](/en/lisp/latest/reference/libtmux-clients/) (function): Return a fresh vector of attached-client observations, without I/O.
Preserve listing order and multiplicity, including repeated target names.
- [`fetch-snapshot`](/en/lisp/latest/reference/libtmux-fetch-snapshot/) (function): Acquire an eager native graph; all later accessors on it are local.
TIMEOUT controls one acquisition deadline and OUTPUT-LIMIT caps combined output,
including at most two retries after contradictory observations. Synchronous
setup and additional cleanup can extend caller wall time. ROW-LIMIT bounds each listing;
ENTITY-LIMIT bounds the complete graph; FIELD-LIMIT bounds encoded field bytes.
No daemon is started. A live daemon with zero sessions yields empty vectors;
connection/listing failures remain errors. Closing CLIENT leaves this snapshot
usable. This is an interval observation, not a transactional snapshot.

### Common operations

- [`session`](/en/lisp/latest/reference/libtmux-session-type/) (class): A captured physical tmux session.
- [`window`](/en/lisp/latest/reference/libtmux-window-type/) (class): A physical window shared by zero or more captured links.
- [`pane`](/en/lisp/latest/reference/libtmux-pane/) (class): A physical pane belonging to one captured window.
- [`send-keys`](/en/lisp/latest/reference/libtmux-send-keys/) (function): Send a finite nonempty list/vector of tmux key strings to PANE.
Return a COMMAND-OUTCOME. REPEAT is a positive count. Tmux interprets key names
such as C-c and Enter; its unrecognized strings fall back to literal input.
Use SEND-TEXT when key-name interpretation must be disabled. Acknowledgment
does not prove application readiness or consumption.
- [`kill-server`](/en/lisp/latest/reference/libtmux-kill-server/) (function): Terminate CLIENT's preflight-accepted daemon and return a COMMAND-OUTCOME.
Success requires both a pre-dispatch receipt and observed exit of the server
process accepted during this call. Missing evidence signals OUTCOME-UNKNOWN;
cancellation or a deadline never causes an automatic retry. The connection
CLIENT stays open but its generation is invalidated after observed server death.
A failed exit wait retains :SERVER-EXIT-UNOBSERVED and the underlying
ERROR-CAUSE. CLOSE-CLIENT never calls this function.
- [`run-command`](/en/lisp/latest/reference/libtmux-run-command/) (function): Execute explicit tmux argv and return a retained COMMAND-OUTCOME.
EFFECT must be :READ or :MUTATION. Arguments are literal argv strings; tmux's
own command/format grammar still applies. INPUT is an octet vector or NIL.
This escape hatch does not validate captured target identities. Failures signal
conditions retaining the outcome; uncertain mutations are never retried.
- [`capture-pane`](/en/lisp/latest/reference/libtmux-capture-pane/) (function): Read PANE now; return strict UTF-8 text and the diagnostic command outcome.
Preserve whitespace and trailing lines.
OPTIONS are the CAPTURE-PANE-BYTES options. Invalid UTF-8 signals DECODING-ERROR;
call CAPTURE-PANE-BYTES when byte preservation is required.
- [`new-session`](/en/lisp/latest/reference/libtmux-new-session/) (function): Create a detached session on the selected live daemon; return a COMMAND-OUTCOME.
NAME, WINDOW-NAME and CWD are literal. WIDTH/HEIGHT are positive initial cell
dimensions through 65535. ENVIRONMENT, COMMAND and SHELL-COMMAND follow
NEW-WINDOW. OUTCOME-VALUE supplies the created session; acquisition failure is
retained separately. This operation requires an existing daemon and never
silently starts or replaces one. A separate bootstrap path remains in development.
- [`pipe-pane`](/en/lisp/latest/reference/libtmux-pipe-pane/) (function): Configure PANE's tmux-owned pipe and return a COMMAND-OUTCOME.
SHELL-COMMAND is shell source, literal to tmux by default; FORMAT-P explicitly
enables tmux format and time expansion before shell execution. DIRECTION is
:OUTPUT (pane to shell), :INPUT (shell to pane), or :BOTH. Omit SHELL-COMMAND,
or pass an empty string, to close the pipe. TOGGLE closes an existing pipe
without starting its replacement. Replacing a pipe closes the previous one.
Completion acknowledges configuration, not shell startup, success or output
consumption. The daemon owns the pipe child; closing CLIENT leaves it running.
Literal commands exceeding tmux's time-format capacity fail before I/O.
Signals STALE-TARGET or an operational condition; never retries configuration.
- [`wait-for`](/en/lisp/latest/reference/libtmux-wait-for/) (function): Wait, signal, lock or unlock the literal CHANNEL; return a COMMAND-OUTCOME.
OPERATION is :WAIT (default), :SIGNAL, :LOCK or :UNLOCK. CHANNEL is a nonempty
string without NUL. This call performs I/O on an existing daemon. :WAIT and
:LOCK require tmux 3.8, whose client-loss handling removes queued waiters;
older daemons signal UNSUPPORTED-CAPABILITY before dispatch. :SIGNAL and
:UNLOCK support the library's tmux floor.
- [`capture-pane-bytes`](/en/lisp/latest/reference/libtmux-capture-pane-bytes/) (function): Read PANE now; return owned output octets and the diagnostic command outcome.
START/END accept signed line numbers or :ALL for the corresponding history edge.
JOIN-LINES joins wrapped rows; ESCAPE-SEQUENCES retains terminal styles;
ESCAPE-CONTROLS asks tmux to render controls as octal; ALTERNATE selects its
alternate screen; PENDING-OUTPUT requests tmux's pending input bytes. Tmux owns
these capture modes and may reject unavailable combinations. Does not decode or
trim bytes. Signals STALE-TARGET or an operational condition with its outcome.
- [`client`](/en/lisp/latest/reference/libtmux-client/) (class): A connection scope with one external-operation lease.
Closing cancels owned work and leaves the tmux daemon alive. Captured data may
outlive the client. Public operations never expose its mutable storage.
- [`client-busy`](/en/lisp/latest/reference/libtmux-client-busy/) (exception): Another external operation already owns the client's lease.
- [`close-client`](/en/lisp/latest/reference/libtmux-close-client/) (function): Reject new work, cancel active work and release owned resources.
The operation is idempotent and does not kill the daemon. A bounded teardown
failure signals CLEANUP-FAILED; the active owner still retains cleanup duty.
- [`command-cancelled`](/en/lisp/latest/reference/libtmux-command-cancelled/) (exception): Cancellation stopped an operation; inspect dispatch phase.
- [`command-outcome`](/en/lisp/latest/reference/libtmux-command-outcome/) (class): A retained command result; byte and argument readers copy storage.
STATUS is :SUCCEEDED, :FAILED, :UNKNOWN or :NOT-DISPATCHED. PHASE is separate
dispatch evidence. An observation error does not erase a successful mutation.
- [`entity-data`](/en/lisp/latest/reference/libtmux-entity-data/) (function): Return a fresh finite plist of captured fields and provenance.
Relationships contain identifiers, not operational handles. Absent optional
fields are omitted; present false values remain in the plist. No tmux I/O.
- [`error-cause`](/en/lisp/latest/reference/libtmux-error-cause/) (function): Return the original underlying condition, or NIL. No I/O; may be shared.
- [`field-unavailable`](/en/lisp/latest/reference/libtmux-field-unavailable/) (exception): The field is unregistered for this model or its relation is unloaded.
- [`refresh`](/en/lisp/latest/reference/libtmux-refresh/) (function): Acquire a replacement observation, leaving the earlier capture unchanged.
CLIENT must own the original context/generation. Missing or replaced targets
signal STALE-TARGET. Attached-client refresh requires one unique live target
name with the same PID/creation/tty fingerprint; its observation identity changes.
- [`send-text`](/en/lisp/latest/reference/libtmux-send-text/) (function): Send literal TEXT to PANE through tmux and return a COMMAND-OUTCOME.
ENTER appends one Return key in the same command. Text such as C-c remains
literal text; it is not parsed as a key name, tmux format or shell command.
Tmux's active pane mode still handles the resulting input. Completion means
tmux processed the send request, not that the application consumed it. An
oversized encoded command is rejected without silently splitting the input.
- [`stale-target`](/en/lisp/latest/reference/libtmux-stale-target/) (exception): Captured target authority or required dispatch context no longer agrees with live state.
- [`with-client`](/en/lisp/latest/reference/libtmux-with-client/) (function): Bind NAME to a client and close the original resource on every exit.
Body declarations and multiple values are preserved. Cleanup failure signals
after normal return; during unwind it is retained in CLIENT-CLEANUP-FAILURES.
- [`active-p`](/en/lisp/latest/reference/libtmux-active-p/) (function): Return captured active state and presence, without I/O. False is NIL,T.
- [`attached-client`](/en/lisp/latest/reference/libtmux-attached-client/) (class): One captured attached-tmux-client row; identity is observation-scoped.
- [`bind-key`](/en/lisp/latest/reference/libtmux-bind-key/) (function): Replace TABLE's KEY binding and return a COMMAND-OUTCOME.
TABLE defaults to prefix. KEY, TABLE and optional NOTE are literal strings.
REPEAT enables native key repetition. Supply exactly one of COMMAND argv or
COMMAND-SOURCE, explicit tmux parser source. COMMAND argv owns each argument
and preserves its token boundary; its first token must not contain =.
- [`break-pane`](/en/lisp/latest/reference/libtmux-break-pane/) (function): Break PANE from SOURCE-LINK into SESSION's free INDEX; return an outcome.
SOURCE-LINK fixes the session context when breaking the window's only pane;
tmux moves that link instead of creating another physical window. NAME is
literal. DETACHED defaults true. OBSERVE supplies the destination window link.
On tmux 3.7, a new named window requires a following RENAME-WINDOW in the same
guarded request; its configured hooks can run. Failure can leave the pane moved.
The pane keeps its identity. Signals INVALID-ARGUMENT, STALE-TARGET or an
operational condition. Occupied indexes are never overwritten.
- [`cancel`](/en/lisp/latest/reference/libtmux-cancel/) (function): Cancel registered operations and return true only for the first request.
Cancellation wakes each active owner. It does not wait for completion or undo
a mutation. Inspect the operation's outcome and dispatch phase.
- [`cleanup-failed`](/en/lisp/latest/reference/libtmux-cleanup-failed/) (exception): Owned resources could not be released within the cleanup bound.
- [`clear-history`](/en/lisp/latest/reference/libtmux-clear-history/) (function): Clear PANE's retained tmux history; return a COMMAND-OUTCOME.
Captured observations remain unchanged. This does not promise to clear the
application's current screen. Signals STALE-TARGET or an operational condition.
- [`client-cleanup-failures`](/en/lisp/latest/reference/libtmux-client-cleanup-failures/) (function): Return a fresh vector of secondary cleanup conditions, newest first. No I/O.
- [`copy-mode`](/en/lisp/latest/reference/libtmux-copy-mode/) (function): Enter PANE's tmux copy mode, or EXIT it; return a COMMAND-OUTCOME.
PAGE-UP scrolls up on entry and cannot be combined with EXIT. This addresses an
existing pane and does not create an interactive terminal frontend. Signals
STALE-TARGET or an operational condition.
- [`current-command`](/en/lisp/latest/reference/libtmux-current-command/) (function): Return copied captured command text and presence, without I/O.
- [`current-path`](/en/lisp/latest/reference/libtmux-current-path/) (function): Return copied captured path text and presence, without local pathname conversion.
- [`dead-p`](/en/lisp/latest/reference/libtmux-dead-p/) (function): Return tmux's captured dead flag and presence, without inferring it from PID.
- [`decoding-error`](/en/lisp/latest/reference/libtmux-decoding-error/) (exception): Captured bytes do not satisfy the expected text/record codec.
- [`delete-buffer`](/en/lisp/latest/reference/libtmux-delete-buffer/) (function): Delete the literal named buffer, or the current top buffer; return an outcome.
Named deletion requires a live tmux 3.4+ daemon because 3.3a can delete the top
buffer when the supplied name is missing. On 3.3a, an explicit NAME signals
UNSUPPORTED-CAPABILITY before payload dispatch; omission still deletes the top
buffer. A name identifies the buffer at dispatch, not an earlier incarnation.
Signals an operational condition on failure; never retries an unknown deletion.
- [`detach-client`](/en/lisp/latest/reference/libtmux-detach-client/) (function): Request detachment of captured terminal TARGET; return a COMMAND-OUTCOME.
CLIENT must own the observation. Success acknowledges the server's request,
not frontend process exit or terminal restoration. Returns no replacement.
Blocks under the supplied limits. The unique name/PID/creation/tty preflight
cannot exclude replacement between validation and dispatch. Missing or foreign
targets signal STALE-TARGET; external failures retain their outcome. Never
retries, detaches other clients, kills a parent, or starts a shell command.
- [`display-message`](/en/lisp/latest/reference/libtmux-display-message/) (function): Print MESSAGE through tmux; return owned UTF-8 text and a COMMAND-OUTCOME.
Always uses the ordinary -p printer, preserving its whitespace and trailing lines.
Native versions can escape output, so it is not a byte-identical echo. MESSAGE
is literal by default. FORMAT-P enables tmux format and time expansion;
#() may start shell jobs but does not wait for their output. Fresh requests can
print empty or incomplete job results. The native command client owns those
jobs; its disconnect cleans them up.
- [`error-actual-version`](/en/lisp/latest/reference/libtmux-error-actual-version/) (function): Return an owned copy of the live daemon release that failed the capability check.
- [`error-client`](/en/lisp/latest/reference/libtmux-error-client/) (function): Return the connection client associated with the failure, or NIL.
A partially opened client may still own cleanup work; retry CLOSE-CLIENT if
cleanup failed. Reading this slot performs no I/O.
- [`error-commands`](/en/lisp/latest/reference/libtmux-error-commands/) (function): Return an owned vector of command spellings implicated in the configuration failure.
- [`error-feature`](/en/lisp/latest/reference/libtmux-error-feature/) (function): Return the unsupported capability's keyword identifier. No I/O.
- [`error-outcome`](/en/lisp/latest/reference/libtmux-error-outcome/) (function): Return retained COMMAND-OUTCOME evidence, or NIL before one exists.
Inspect dispatch phase and status before deciding how to recover. No I/O.
- [`error-required-version`](/en/lisp/latest/reference/libtmux-error-required-version/) (function): Return an owned copy of the capability's minimum tmux release.
- [`error-setting`](/en/lisp/latest/reference/libtmux-error-setting/) (function): Return the daemon setting that violates a named command contract.
The captured diagnostic value may be shared; treat it as read-only. No I/O.
- [`fetch-clients`](/en/lisp/latest/reference/libtmux-fetch-clients/) (function): Acquire a complete snapshot and return every attached-client row. OPTIONS go to FETCH-SNAPSHOT.
- [`fetch-panes`](/en/lisp/latest/reference/libtmux-fetch-panes/) (function): Acquire a complete snapshot and return physical panes once each. OPTIONS go to FETCH-SNAPSHOT.
- [`fetch-sessions`](/en/lisp/latest/reference/libtmux-fetch-sessions/) (function): Acquire a complete snapshot and return its fresh session vector. OPTIONS go to FETCH-SNAPSHOT.
- [`fetch-windows`](/en/lisp/latest/reference/libtmux-fetch-windows/) (function): Acquire a complete snapshot and return physical windows once each. OPTIONS go to FETCH-SNAPSHOT.
- [`field-value`](/en/lisp/latest/reference/libtmux-field-value/) (function): Return a captured field and presence as two values, without I/O.
Present false is NIL,T; absence is NIL,NIL. Strings and relation containers are
copied. Unknown fields and unloaded relations signal FIELD-UNAVAILABLE.
- [`height`](/en/lisp/latest/reference/libtmux-height/) (function): Return the positive captured height and presence, without I/O.
- [`id`](/en/lisp/latest/reference/libtmux-id/) (function): Return the captured identity, copying mutable components. No I/O.
Physical IDs are strings; a link ID is (session-ID index window-ID). Attached
client IDs identify rows within a single observation, not stable daemon clients.
- [`incomplete-snapshot`](/en/lisp/latest/reference/libtmux-incomplete-snapshot/) (exception): Captured rows contradict each other or lack required references.
- [`index`](/en/lisp/latest/reference/libtmux-index/) (function): Return the nonnegative captured index and presence, without I/O.
- [`invalid-argument`](/en/lisp/latest/reference/libtmux-invalid-argument/) (exception): An argument violates the operation's declared contract.
- [`join-pane`](/en/lisp/latest/reference/libtmux-join-pane/) (function): Join SOURCE pane beside DESTINATION using tmux's join-pane command.
Arguments, outcomes, emptied-window effects and observation semantics match
MOVE-PANE. Both targets are captured physical panes. Signals STALE-TARGET or an
operational condition; a failed follow-up is distinct from mutation failure.
- [`kill-pane`](/en/lisp/latest/reference/libtmux-kill-pane/) (function): Delete exactly the captured physical PANE and return a COMMAND-OUTCOME.
The live pane identity is checked before dispatch. Other panes are preserved.
Signals STALE-TARGET when PANE disappeared or belongs to another generation.
Never retries the mutation.
- [`kill-session`](/en/lisp/latest/reference/libtmux-kill-session/) (function): Delete exactly the captured SESSION and return a COMMAND-OUTCOME.
Tmux removes that session's links and panes no longer referenced elsewhere.
The live identity is checked before dispatch; the mutation is never retried.
- [`kill-window`](/en/lisp/latest/reference/libtmux-kill-window/) (function): Delete exactly the captured physical WINDOW and return a COMMAND-OUTCOME.
Every link to that physical window is removed by tmux. Other windows remain.
The live identity is checked before dispatch; the mutation is never retried.
- [`last-pane`](/en/lisp/latest/reference/libtmux-last-pane/) (function): Select WINDOW's last active pane; return an outcome with that observed pane.
OBSERVE may omit follow-up acquisition. Tmux reports an error when no last
pane exists. Signals STALE-TARGET or an operational condition. Earlier
captures retain their original selection.
- [`last-window`](/en/lisp/latest/reference/libtmux-last-window/) (function): Select SESSION's last active link; return an outcome with that observed link.
OBSERVE may omit follow-up acquisition. Tmux reports an error when no last
window exists. Signals STALE-TARGET or an operational condition. Earlier
captures retain their original selection.
- [`link-window`](/en/lisp/latest/reference/libtmux-link-window/) (function): Link SOURCE-LINK's physical window into SESSION at the free INDEX.
Return a COMMAND-OUTCOME with the new window link when OBSERVE is true.
SOURCE-LINK preserves the source session context, including tmux group rules.
DETACHED defaults true. Never overwrites an occupied index. Signals STALE-TARGET
or an operational condition; observation failure is retained separately.
- [`list-buffers`](/en/lisp/latest/reference/libtmux-list-buffers/) (function): Acquire buffer metadata; return a fresh simple vector of owned plists and an outcome.
Each plist has :BUFFER/NAME, :BUFFER/SIZE (bytes) and :BUFFER/CREATED (Unix
seconds). Preserve tmux's listing order; buffer names are mutable locators,
not captured entity identities. Empty listing returns #(). ROW-LIMIT bounds
decoding. Signals an operational or decoding condition with the raw outcome.
- [`list-commands`](/en/lisp/latest/reference/libtmux-list-commands/) (function): Inspect built-in tmux commands; return owned UTF-8 printer text and an outcome.
Omit COMMAND to list all built-ins. COMMAND is an exact name or built-in alias
through tmux 3.5a; unknown selectors produce no rows. From 3.6, unique prefixes
are accepted and unknown/ambiguous selectors fail. Configured command-alias
entries are not listed or expanded by this selector.
- [`list-keys`](/en/lisp/latest/reference/libtmux-list-keys/) (function): Inspect key bindings; return owned UTF-8 printer text and a command outcome.
Omit TABLE to list every key table. TABLE and KEY are literal strings; native
unknown-table and invalid-key failures remain errors. An unbound valid KEY is
an error except on tmux 3.7 through 3.7c, which return empty text. Those releases
also send a single matching row to the server message log and any selected
frontend's status line instead of stdout. Empty text does not prove absence.
FORMAT is explicit tmux format source
and requires live tmux 3.7 or newer; older daemons signal UNSUPPORTED-CAPABILITY
before payload dispatch. Omission uses the native human-readable listing.
- [`list-server-access`](/en/lisp/latest/reference/libtmux-list-server-access/) (function): Print the daemon ACL; return owned UTF-8 text and a COMMAND-OUTCOME.
The ordinary native listing preserves escaping and whitespace. Before 3.8,
rows use (R)/(W); from 3.8 they include U/G account kinds. UID 0 is omitted and
unresolvable names print as unknown. An empty listing does not prove that no
account has access. This is printer output, not a decoded authorization model.
Blocks under shared preflight/dispatch limits and never retries or acquires an
observation. Invalid UTF-8 signals DECODING-ERROR; native and operational
failures retain their outcomes.
- [`load-buffer`](/en/lisp/latest/reference/libtmux-load-buffer/) (function): Load a file's bytes into a literal named or automatic buffer; return an outcome.
PATH is literal path text, not a format. Relative paths follow the tmux command
client's cwd. An empty file is tmux's no-op and preserves an existing buffer.
New names reject backslashes, ASCII controls and DEL before I/O.
Use SET-BUFFER for in-memory bytes. Signals INVALID-ARGUMENT or an operational
condition; a failure after dispatch may have an uncertain outcome.
- [`lock-client`](/en/lisp/latest/reference/libtmux-lock-client/) (function): Request locking of captured terminal TARGET; return a COMMAND-OUTCOME.
The frontend runs the session's configured lock-command through its shell.
Success acknowledges the request, not lock startup, completion or authentication.
An already suspended frontend or an empty/oversized lock command can be a no-op.
CLIENT must own TARGET.
Blocks under shared preflight/dispatch limits; returns no replacement. Stale or
foreign targets signal STALE-TARGET; other failures retain their outcome.
Preflight cannot exclude client replacement before dispatch. Never retries.
- [`lock-server`](/en/lisp/latest/reference/libtmux-lock-server/) (function): Request locking of all attached frontends on CLIENT's daemon.
Return a COMMAND-OUTCOME after guarded dispatch. Live frontend membership
determines the recipients; this is wider than one captured session. Each
frontend runs its configured lock-command. Control clients, suspended
frontends and empty/oversized commands are skipped. Success acknowledges
the request, not startup, completion or authentication. Blocks under shared
preflight/dispatch limits and returns no replacement. Failures retain their
outcome. Lock programs belong to the frontends; closing CLIENT leaves them
running. Never retries.
- [`lock-session`](/en/lisp/latest/reference/libtmux-lock-session/) (function): Request locking of SESSION's attached frontends; return a COMMAND-OUTCOME.
CLIENT must own the captured SESSION. The live session membership determines
which frontends receive the request. Each runs its configured lock-command;
control clients, suspended frontends and empty/oversized commands are skipped.
Success acknowledges the request, not startup, completion or authentication.
Blocks under shared preflight/dispatch limits and returns no replacement.
Foreign or vanished sessions signal STALE-TARGET; other failures retain their
outcome. Lock programs belong to the frontends; closing CLIENT leaves them
running. Never retries.
- [`make-cancellation-token`](/en/lisp/latest/reference/libtmux-make-cancellation-token/) (function): Create a token for one or more operations. CANCEL is idempotent.
Signals UNSUPPORTED-PLATFORM outside the qualified runtime profile.
- [`move-pane`](/en/lisp/latest/reference/libtmux-move-pane/) (function): Move SOURCE pane beside DESTINATION; return an outcome with the moved pane.
DIRECTION is :HORIZONTAL or :VERTICAL. SIZE is cells; PERCENT is 1..100,
mutually exclusive with SIZE. BEFORE changes placement and FULL-SIZE spans the
window. Percent sizing retains tmux's version semantics: with FULL-SIZE, 3.3a
uses destination-pane dimensions and 3.8 uses whole-window dimensions. Use SIZE
for cell-based control. DETACHED defaults true.
An emptied source window is destroyed, including all its links. With DETACHED
false, tmux chooses the session context of the physical destination. OBSERVE
supplies a replacement source pane; its old observation retains its old window.
Signals STALE-TARGET or an operational condition.
- [`move-window`](/en/lisp/latest/reference/libtmux-move-window/) (function): Move SOURCE-LINK into SESSION at the free INDEX; return a COMMAND-OUTCOME.
Other links to the physical window survive. Removing a session's last link can
destroy that session, following tmux semantics. OBSERVE supplies the destination
link. DETACHED defaults true; occupied indexes are never overwritten. Signals
STALE-TARGET or an operational condition; older link observations stay unchanged.
- [`name`](/en/lisp/latest/reference/libtmux-name/) (function): Return the captured name and presence, without I/O; text is copied.
- [`new-window`](/en/lisp/latest/reference/libtmux-new-window/) (function): Create a physical window in captured SESSION and return a COMMAND-OUTCOME.
NAME and CWD are literal strings. INDEX chooses a free link index; omission uses
tmux's next available index. DETACHED defaults true. ENVIRONMENT is a list/vector
of (name . value) string pairs. COMMAND is nonempty argv; SHELL-COMMAND is a
separate, mutually exclusive shell string. Omit both for tmux's default shell.
OUTCOME-VALUE supplies the resulting window; observation failure is separate.
Never replaces an occupied index or retries a mutation. Limits cover all I/O.
- [`next-layout`](/en/lisp/latest/reference/libtmux-next-layout/) (function): Cycle WINDOW to tmux's next layout; return an outcome and optional replacement.
Unzooms the window. Captured values remain unchanged. Signals STALE-TARGET or
an operational condition; follow-up acquisition failure is retained separately.
- [`next-window`](/en/lisp/latest/reference/libtmux-next-window/) (function): Select SESSION's next window link; return a COMMAND-OUTCOME.
ACTIVITY restricts selection to windows with an alert. OBSERVE supplies the
newly captured active link through OUTCOME-VALUE, or records an observation
failure separately. Signals STALE-TARGET or an operational condition.
- [`open-client`](/en/lisp/latest/reference/libtmux-open-client/) (function): Open an SBCL/Linux subprocess client and check its tmux version.
Checks the runtime profile and required OS facilities before resolving PROGRAM.
An unsupported profile or facility signals UNSUPPORTED-PLATFORM; ERROR-FEATURE
identifies the requirement. PROGRAM must resolve to a native x86_64 ELF tmux
executable; pass the underlying binary when PATH selects a script or shim.
SOCKET-NAME and SOCKET-PATH are mutually exclusive; omission selects tmux's
default socket. No daemon is started. TIMEOUT is seconds; OUTPUT-LIMIT bounds
combined stdout/stderr bytes per command. Signals an operational condition on
version/launch failure. Returned configuration strings are owned by the client.
- [`outcome-arguments`](/en/lisp/latest/reference/libtmux-outcome-arguments/) (function): Return an owned vector of the effective argv strings. No external I/O.
- [`outcome-exit-code`](/en/lisp/latest/reference/libtmux-outcome-exit-code/) (function): Return the subprocess's integer exit status, or NIL if unknown. No I/O.
- [`outcome-observation-error`](/en/lisp/latest/reference/libtmux-outcome-observation-error/) (function): Return the condition from follow-up acquisition, or NIL. No I/O.
A successful mutation remains :SUCCEEDED when its replacement observation
fails. Do not repeat the mutation merely to obtain a replacement observation.
- [`outcome-phase`](/en/lisp/latest/reference/libtmux-outcome-phase/) (function): Return retained dispatch evidence, without I/O.
Raw process phases are :PREPARED, :LAUNCHING, :DISPATCHED and :EXITED. Named
operations may also report :PREFLIGHT or :GUARD-REJECTED before payload dispatch.
Explicit server termination reports :SERVER-TERMINATED only after retained
pidfd readiness proves exit. Phase is separate from OUTCOME-STATUS; an exited
queue can have partially completed effects even when it reported failure.
- [`outcome-reason`](/en/lisp/latest/reference/libtmux-outcome-reason/) (function): Return the retained failure reason keyword, or NIL. No I/O.
Examples include :DEADLINE and :CANCELLED; inspect the condition and phase too.
- [`outcome-stderr`](/en/lisp/latest/reference/libtmux-outcome-stderr/) (function): Return a fresh octet vector containing retained diagnostic output.
- [`outcome-stdout`](/en/lisp/latest/reference/libtmux-outcome-stdout/) (function): Return a fresh octet vector containing retained standard output.
- [`outcome-value`](/en/lisp/latest/reference/libtmux-outcome-value/) (function): Return the resulting value and presence as two values, without I/O.
Copy data containers and strings; captured entity observations may be shared.
- [`paste-buffer`](/en/lisp/latest/reference/libtmux-paste-buffer/) (function): Paste a named or top buffer into PANE; return a COMMAND-OUTCOME.
Newlines become Return by default. RAW preserves newlines; SEPARATOR explicitly
replaces each newline with literal text and is mutually exclusive with RAW.
VERBATIM preserves every byte, implies RAW and disables tmux's newer control-byte
sanitization; it cannot be combined with a separator or bracket markers.
BRACKETED uses bracketed paste when the pane enabled it. DELETE removes the
selected buffer afterward. Tmux may accept without sending when input is
disabled; success does not prove application consumption. Signals STALE-TARGET
or an operational condition.
- [`previous-layout`](/en/lisp/latest/reference/libtmux-previous-layout/) (function): Cycle WINDOW to tmux's previous layout; return an outcome and optional replacement.
Unzooms the window. Captured values remain unchanged. Signals STALE-TARGET or
an operational condition; follow-up acquisition failure is retained separately.
- [`previous-window`](/en/lisp/latest/reference/libtmux-previous-window/) (function): Select SESSION's previous window link; return a COMMAND-OUTCOME.
ACTIVITY restricts selection to windows with an alert. OBSERVE supplies the
newly captured active link through OUTCOME-VALUE, or records an observation
failure separately. Signals STALE-TARGET or an operational condition.
- [`refresh-client`](/en/lisp/latest/reference/libtmux-refresh-client/) (function): Request a redraw of captured terminal TARGET; return a COMMAND-OUTCOME.
STATUS-ONLY requests only the status line; NIL requests the whole display.
Success acknowledges scheduling, not completed terminal rendering. This is an
external operation; REFRESH instead acquires a replacement observation.
CLIENT must own TARGET. Blocks under shared preflight/dispatch limits. A stale
or foreign target signals STALE-TARGET; other failures retain their outcome.
The client fingerprint is checked before dispatch, with a remaining replacement
race. Returns no replacement and never retries the request.
- [`remove-environment`](/en/lisp/latest/reference/libtmux-remove-environment/) (function): Store tmux's removal marker for NAME and return its COMMAND-OUTCOME.
SCOPE/TARGET follow SET-ENVIRONMENT. A removal marker is distinct from absence
and from a present empty string. UNSET-ENVIRONMENT deletes the entry instead.
Never retries the mutation.
- [`rename-session`](/en/lisp/latest/reference/libtmux-rename-session/) (function): Rename SESSION with literal TEXT, or an explicit FORMAT-P expression.
Return a COMMAND-OUTCOME. OBSERVE defaults true and supplies a replacement
through OUTCOME-VALUE; observation failure is retained separately. Tmux enforces
session-name restrictions and uniqueness. Signals STALE-TARGET or an operational
condition. Timeout and byte limits cover preflight, mutation and observation.
- [`rename-window`](/en/lisp/latest/reference/libtmux-rename-window/) (function): Rename the selected physical WINDOW and return a COMMAND-OUTCOME.
TEXT is literal by default; FORMAT-P explicitly enables tmux format expansion.
Tmux may normalize or reject names. OBSERVE acquires a replacement in
OUTCOME-VALUE; a failed follow-up stays in OUTCOME-OBSERVATION-ERROR without
erasing successful mutation. Earlier observations are unchanged. Signals
STALE-TARGET or an operational condition. Never retries the mutation.
- [`resize-pane`](/en/lisp/latest/reference/libtmux-resize-pane/) (function): Resize PANE and return a COMMAND-OUTCOME with an optional replacement pane.
Choose cell WIDTH/HEIGHT (1..10000), a DIRECTION and positive AMOUNT, or ZOOM.
DIRECTION is :LEFT, :RIGHT, :UP or :DOWN; AMOUNT defaults to one. ZOOM toggles
the window's zoom state. Modes are exclusive. Tmux may clamp sizes to the
available layout; inspect the observed value. Earlier captures stay unchanged.
Signals INVALID-ARGUMENT, STALE-TARGET or an operational condition.
- [`resize-window`](/en/lisp/latest/reference/libtmux-resize-window/) (function): Resize physical WINDOW and return an outcome with an optional replacement.
Choose cell WIDTH/HEIGHT (1..10000), a DIRECTION and positive AMOUNT, or FIT
(:SMALLEST or :LARGEST attached client). Modes are exclusive; dimensions are
subject to tmux's layout constraints. A resize sets the window-size option to
manual, as tmux does. Signals INVALID-ARGUMENT, STALE-TARGET or an operational
condition. Observation failure is retained separately from mutation success.
- [`respawn-pane`](/en/lisp/latest/reference/libtmux-respawn-pane/) (function): Restart PANE's process and return a COMMAND-OUTCOME.
KILL explicitly replaces a running process; otherwise tmux requires it to have
exited. Omit COMMAND and SHELL-COMMAND to reuse the previous command. Explicit
argv, shell text, literal CWD and ENVIRONMENT follow NEW-WINDOW. OBSERVE returns
a replacement pane through OUTCOME-VALUE; its earlier capture stays unchanged.
The process may exit before observation. Signals STALE-TARGET or an operational
condition; never retries an uncertain restart.
- [`respawn-window`](/en/lisp/latest/reference/libtmux-respawn-window/) (function): Restart WINDOW as one pane and return a COMMAND-OUTCOME.
KILL explicitly replaces running processes. Tmux retains its first pane and
destroys every other pane in the physical window, including through other links.
Other options follow RESPAWN-PANE. OBSERVE supplies a replacement window without
changing earlier observations. Linked-window session context is selected by tmux.
Signals STALE-TARGET or an operational condition; never retries the restart.
- [`rotate-window`](/en/lisp/latest/reference/libtmux-rotate-window/) (function): Rotate WINDOW's pane positions :UP or :DOWN; return an outcome and replacement.
Tmux also advances the active pane. PRESERVE-ZOOM restores zoom after rotating.
Signals INVALID-ARGUMENT, STALE-TARGET or an operational condition. Captured
pane order remains unchanged in earlier observations.
- [`same-entity-p`](/en/lisp/latest/reference/libtmux-same-entity-p/) (function): Compare captured identity, not captured field values. No I/O.
Context and generation must agree. Link comparison retains its expected window
and index. Attached clients compare equal only within their original capture.
- [`save-buffer`](/en/lisp/latest/reference/libtmux-save-buffer/) (function): Save a named or top buffer's bytes to literal PATH; return a COMMAND-OUTCOME.
Overwrite the file unless APPEND is true. Relative paths follow tmux's command
client cwd. Use SHOW-BUFFER for returned bytes. Success records tmux's reported
completion, not independently verified file contents or durability. In particular,
tmux 3.3a can suppress file-write errors. An uncertain write is never retried.
Signals INVALID-ARGUMENT or an operational condition.
- [`select-layout`](/en/lisp/latest/reference/libtmux-select-layout/) (function): Apply LAYOUT to physical WINDOW; return an outcome and optional replacement.
LAYOUT is :EVEN-HORIZONTAL, :EVEN-VERTICAL, :MAIN-HORIZONTAL, :MAIN-VERTICAL,
:TILED, or (:CUSTOM string) containing a tmux layout description. Legacy custom
text requires four ASCII hex digits, a comma and a nonempty body; JSON-object
layouts require a live tmux daemon at least 3.8. Header checks precede I/O;
the existing target preflight checks the daemon version before dispatch.
Text is literal; tmux validates its checksum, JSON and geometry. This unzooms
the window. Signals INVALID-ARGUMENT, UNSUPPORTED-CAPABILITY, STALE-TARGET or
an operational condition. Does not change earlier captured values.
- [`select-pane`](/en/lisp/latest/reference/libtmux-select-pane/) (function): Select PANE within its physical window; return a COMMAND-OUTCOME.
OBSERVE supplies a replacement pane through OUTCOME-VALUE. Captured getters
stay local and unchanged. Signals STALE-TARGET or an operational condition.
- [`select-window`](/en/lisp/latest/reference/libtmux-select-window/) (function): Select a captured window LINK within its session; return a COMMAND-OUTCOME.
The expected session/index/window mapping is checked before dispatch. OBSERVE
supplies a replacement link through OUTCOME-VALUE. A moved or replaced mapping
signals STALE-TARGET; external failures retain their command outcome.
- [`send-prefix`](/en/lisp/latest/reference/libtmux-send-prefix/) (function): Send the session's configured prefix key to PANE; return a COMMAND-OUTCOME.
SECOND selects prefix2. Tmux's active pane mode handles input; completion does
not establish application consumption. Signals STALE-TARGET or an operational
condition retaining its outcome.
- [`server-access`](/en/lisp/latest/reference/libtmux-server-access/) (function): Change PRINCIPAL's native daemon ACL entry; return a COMMAND-OUTCOME.
PRINCIPAL is a nonempty literal account name, resolved by the daemon's name
service, not a numeric UID/GID. GROUP-P selects a group and requires live tmux
3.8; older daemons signal UNSUPPORTED-CAPABILITY before payload dispatch.
- [`set-buffer`](/en/lisp/latest/reference/libtmux-set-buffer/) (function): Store literal DATA in a named or automatic buffer; return a COMMAND-OUTCOME.
DATA is a NUL-free string or an octet vector. Strings use tmux set-buffer;
octets use its load-buffer stdin path and preserve NUL and invalid UTF-8.
APPEND is available only for strings. Empty DATA is tmux's no-op and preserves
an existing buffer. NAME is literal; omission creates an automatic name.
New names reject backslashes, ASCII controls and DEL before I/O because tmux
versions otherwise rewrite or reject them. Spaces and Unicode are supported.
Signals INVALID-ARGUMENT or an operational condition.
- [`set-environment`](/en/lisp/latest/reference/libtmux-set-environment/) (function): Set one raw tmux environment entry and return its COMMAND-OUTCOME.
SCOPE is required: :GLOBAL rejects TARGET; :SESSION requires a captured session.
NAME must match [A-Za-z_][A-Za-z0-9_]*. VALUE is literal unless FORMAT-P
explicitly requests tmux format expansion. HIDDEN sets tmux's hidden flag.
This mutates one raw table, not an effective merged child environment. Never
retries or refreshes captured observations. See UNSET-ENVIRONMENT for deletion
and REMOVE-ENVIRONMENT for an explicit tombstone.
- [`set-hook`](/en/lisp/latest/reference/libtmux-set-hook/) (function): Install tmux COMMAND-SOURCE for one registered hook and return an outcome.
SCOPE/TARGET follow SET-OPTION. COMMAND-SOURCE is explicit tmux command
language, not Lisp code; this function neither reads nor executes it locally.
KEY selects one hook-array entry. APPEND applies to an unkeyed hook assignment;
tmux does not append command source within a keyed hook entry. The ordinary
install path never uses set-hook -R, but tmux may still run a registered native
after-hook such as `after-set-hook` as a consequence of this set-hook command.
Dynamic @ event sources require a live catalog that supports them. SET-OPTION
rejects registered hooks; use UNSET-HOOK to remove this state. Never retries.
- [`set-option`](/en/lisp/latest/reference/libtmux-set-option/) (function): Set one typed tmux option and return its COMMAND-OUTCOME.
SCOPE is required and names one explicit table: :SERVER, :GLOBAL-SESSION,
:SESSION, :GLOBAL-WINDOW, :WINDOW or :PANE. Local scopes require a captured
TARGET of the matching type; global scopes reject one. NAME is resolved in the
exact live daemon catalog. Native numbers, Booleans and choices are validated
before payload dispatch. User names must match @[A-Za-z0-9_.-]+ and remain
strings. KEY addresses a registered array element. FORMAT-P treats VALUE as an
explicit tmux format; otherwise VALUE is literal and typed. APPEND is supported
for strings, keyed string-array elements and unkeyed array assignment. An
unkeyed array VALUE uses that option's native tmux list grammar; use KEY when
VALUE must remain one literal element. ONLY-IF-UNSET requests tmux -o: write
only when the option, or the selected array key, is absent from the local table.
Inherited values permit a local write; present false and empty values refuse
replacement. Refusal retains normal condition/outcome evidence through
ERROR-OUTCOME. The condition applies to this command; later commands and hooks
remain independent. Use UNSET-OPTION to remove state and SET-HOOK for registered
hooks. Never retries or acquires a replacement capture.
- [`show-buffer`](/en/lisp/latest/reference/libtmux-show-buffer/) (function): Read a literal named buffer, or tmux's top buffer; return octets and an outcome.
Output is an owned octet vector with no text decoding or trimming. Uses an
ordinary unattached tmux client and requires normal completion with empty stderr.
Names select the buffer at dispatch, not an earlier incarnation. A post-launch
failure does not prove non-dispatch. Signals an operational condition retaining
its outcome and any partial bytes.
- [`show-environment-text`](/en/lisp/latest/reference/libtmux-show-environment-text/) (function): Inspect a raw environment table; return owned UTF-8 text and a COMMAND-OUTCOME.
Required SCOPE is :GLOBAL or :SESSION; a session needs a captured TARGET.
NAME is literal nonempty text without NUL or =, including names outside the
mutation identifier grammar. Omission lists the table. HIDDEN selects hidden
entries; NIL selects ordinary entries. A visibility mismatch can return empty
text, which does not prove absence. Empty values, removal markers and native
escaping remain printer syntax. Session output is not a merged child environment.
- [`show-hooks-text`](/en/lisp/latest/reference/libtmux-show-hooks-text/) (function): Inspect native hooks; return owned UTF-8 printer text and a COMMAND-OUTCOME.
SCOPE/TARGET follow SET-HOOK; :SERVER is unavailable because show-hooks has no
server-table flag. NAME is a literal native reference; omission lists hooks.
Tmux can infer a built-in's table from NAME. A named ordinary @ option can
also be printed; that success does not prove event registration.
- [`show-options`](/en/lisp/latest/reference/libtmux-show-options/) (function): Acquire decoded options; return owned record and native read-outcome vectors.
SCOPE and TARGET follow SET-OPTION. Omitted NAMES enumerates registered built-in
non-hook names in source order; explicit finite lists/vectors preserve requested
order and duplicates, including user names. At most 4096 names of at most 1 MiB
UTF-8 each are accepted, independently of RECORD-LIMIT. Explicit NIL/#() performs
no I/O after argument validation.
Each plist has :NAME, :SCOPE, :TARGET-ID, :VERSION, :TYPE, :ARRAY-P, :PRESENT-P,
:VALUE, :SOURCE-SCOPE, :SOURCE-TARGET-ID and :INHERITED-P. A present false flag
has NIL value and true presence. Arrays are vectors of (key-text . typed-value)
pairs, including sparse and supported string keys; empty arrays are present.
INCLUDE-INHERITED defaults true: use explicit ancestor tables only after local
absence and recheck every shadowing absence. Observations span an interval,
not a transaction. Read hooks can run again during bounded consistency retries.
One lease, token, deadline and aggregate byte/record budget covers all reads.
RECORD-LIMIT counts decoded rows/negative observations, including rechecks.
VALUE-LIMIT bounds each decoded UTF-8 value. Preparation and cleanup add wall time.
The ordinary printer must match its known schema; unrelated after-read output
signals a decoding failure. This assumes trusted native output, not per-leaf
origin authentication. Raw SHOW-OPTIONS-TEXT preserves unrestricted inspection.
Every requested name has a record even when absent. Read outcomes retain native
failures for expected missing names; this does not prove later hooks succeeded.
Records contain no operational handle; strings/containers own their storage.
- [`show-options-text`](/en/lisp/latest/reference/libtmux-show-options-text/) (function): Inspect an option table; return owned UTF-8 printer text and a COMMAND-OUTCOME.
Required SCOPE and captured TARGET follow SET-OPTION. They select native flags;
tmux can infer a built-in's table from NAME instead. NAME is a literal option
reference with native abbreviation/array syntax; omission lists the table.
INCLUDE-INHERITED uses -A, which does not promise inherited user @ options in a
whole-table listing. INCLUDE-HOOKS uses -H and VALUE-ONLY uses -v.
- [`split-pane`](/en/lisp/latest/reference/libtmux-split-pane/) (function): Split captured PANE and return a COMMAND-OUTCOME with the created pane.
DIRECTION is :HORIZONTAL (left/right) or :VERTICAL (top/bottom). SIZE is a
positive cell count; PERCENT is 1 through 100, mutually exclusive with SIZE.
BEFORE places the pane before its target; FULL-SIZE spans the whole window.
DETACHED defaults true. CWD, ENVIRONMENT, COMMAND and SHELL-COMMAND follow
NEW-WINDOW. Failed acquisition after successful creation is retained separately.
Signals STALE-TARGET or an operational condition; never retries the mutation.
- [`suspend-client`](/en/lisp/latest/reference/libtmux-suspend-client/) (function): Request suspension of captured terminal TARGET; return a COMMAND-OUTCOME.
Tmux asks the frontend to stop with SIGTSTP. Success acknowledges the request;
it does not prove process suspension. An already suspended frontend can be a
no-op. Its controlling application owns resumption. CLIENT must own TARGET.
Blocks under shared preflight/dispatch limits; returns no replacement. Stale or
foreign targets signal STALE-TARGET; other failures retain their outcome.
Preflight cannot exclude client replacement before dispatch. Never retries.
- [`swap-panes`](/en/lisp/latest/reference/libtmux-swap-panes/) (function): Swap two physical panes; return an outcome with replacements in a fresh vector.
The vector follows argument order. DETACHED defaults true; tmux still adjusts
active-pane references when panes change windows. PRESERVE-ZOOM restores zoom.
Signals STALE-TARGET or an operational condition. Earlier captures stay local
and unchanged; observation failure is retained separately.
- [`swap-windows`](/en/lisp/latest/reference/libtmux-swap-windows/) (function): Swap physical windows at two captured links; return a COMMAND-OUTCOME.
OBSERVE supplies a fresh vector of replacement links in argument order. SELECT
selects the affected indexes in their sessions; omission keeps current indexes.
Tmux group restrictions apply. Signals STALE-TARGET or an operational condition;
old links retain their original expected window IDs.
- [`switch-client`](/en/lisp/latest/reference/libtmux-switch-client/) (function): Switch captured terminal TARGET to SESSION and return a COMMAND-OUTCOME.
CLIENT is the connection owning both observations. UPDATE-ENVIRONMENT defaults
NIL, preserving the destination session environment; true applies tmux's
update-environment option using TARGET's environment. OBSERVE defaults true and
supplies a replacement attached-client through OUTCOME-VALUE. Earlier captures
stay unchanged; failed follow-up acquisition stays in OUTCOME-OBSERVATION-ERROR.
Blocks for preflight, dispatch and optional observation under shared limits.
Preflight checks the unique client name and PID/creation/tty fingerprint; tmux
does not atomically guard that fingerprint at dispatch. A changed or foreign
target signals STALE-TARGET. Operational failures retain their outcome; no
mutation is retried. Control clients are not supported by this operation.
- [`title`](/en/lisp/latest/reference/libtmux-title/) (function): Return a copied captured pane title and presence; empty is present. No I/O.
- [`unbind-key`](/en/lisp/latest/reference/libtmux-unbind-key/) (function): Remove exactly one KEY from TABLE and return a COMMAND-OUTCOME.
TABLE defaults to prefix. Both strings are literal. A missing key in an
existing table is a native no-op; an absent table is an error. Removing its last
binding can delete the table, so repeated removal need not succeed. No bulk
deletion, reset or retry is implicit. Blocks under shared preflight/dispatch
limits. Success acknowledges removal and hooks; it cannot undo earlier key
execution. Native errors and uncertain outcomes retain their diagnostics.
- [`unlink-window`](/en/lisp/latest/reference/libtmux-unlink-window/) (function): Remove the captured LINK and return a COMMAND-OUTCOME without a value.
Tmux refuses the last reference unless KILL-IF-LAST is explicit; group membership
affects that check. Removing a last link can destroy its window and session.
Signals STALE-TARGET or an operational condition. Does not refresh a deleted link.
- [`unset-environment`](/en/lisp/latest/reference/libtmux-unset-environment/) (function): Delete NAME from one raw tmux environment table and return its outcome.
SCOPE/TARGET follow SET-ENVIRONMENT. Absence remains tmux's native idempotent
unset behavior. This is distinct from REMOVE-ENVIRONMENT's tombstone; use
SET-ENVIRONMENT to store a present value.
- [`unset-hook`](/en/lisp/latest/reference/libtmux-unset-hook/) (function): Remove one registered hook or hook-array entry and return its outcome.
SCOPE/TARGET and KEY follow SET-HOOK. The ordinary path never uses set-hook -R,
but tmux may run a remaining native after-hook as a consequence of this
set-hook command. The operation does not retry and validates the exact live
catalog before payload dispatch.
- [`unset-option`](/en/lisp/latest/reference/libtmux-unset-option/) (function): Remove one local option or array entry and return its COMMAND-OUTCOME.
SCOPE/TARGET and KEY follow SET-OPTION. The exact live catalog validates the
name, table and array shape before payload dispatch. Tmux's native unset/default
behavior applies; inherited state is not silently materialized. See SET-OPTION
for setting and scope rules. Never retries.
- [`unsupported-capability`](/en/lisp/latest/reference/libtmux-unsupported-capability/) (exception): The live daemon does not support the requested operation contract.
- [`unsupported-configuration`](/en/lisp/latest/reference/libtmux-unsupported-configuration/) (exception): Daemon configuration overrides a required built-in command contract.
- [`unsupported-tmux`](/en/lisp/latest/reference/libtmux-unsupported-tmux/) (exception): The selected tmux does not meet the supported version floor.
- [`width`](/en/lisp/latest/reference/libtmux-width/) (function): Return the positive captured width and presence, without I/O.
- [`window-link`](/en/lisp/latest/reference/libtmux-window-link/) (class): A captured session/index locator with its expected physical window ID.
- [`window-links`](/en/lisp/latest/reference/libtmux-window-links/) (function): Return every captured window link in wire order as a fresh vector. No I/O.

### Other members

- [`cancellation-token`](/en/lisp/latest/reference/libtmux-cancellation-token/) (class): One-way cancellation state; idle tokens own no OS descriptors.
- [`cancelled-p`](/en/lisp/latest/reference/libtmux-cancelled-p/) (function): Return whether TOKEN has been cancelled, without external I/O.
- [`client-closed`](/en/lisp/latest/reference/libtmux-client-closed/) (exception): An external operation was attempted on a closing/closed client.
- [`client-open-p`](/en/lisp/latest/reference/libtmux-client-open-p/) (function): Return whether CLIENT's lifecycle is open; no tmux I/O.
An active operation may still cause CLIENT-BUSY when new work is attempted.
- [`command-failed`](/en/lisp/latest/reference/libtmux-command-failed/) (exception): The command failed; ERROR-OUTCOME retains diagnostics.
- [`configuration-error-name`](/en/lisp/latest/reference/libtmux-configuration-error-name/) (function): Return the owned active name at failure, or NIL before name resolution. No I/O.
- [`configuration-error-scope`](/en/lisp/latest/reference/libtmux-configuration-error-scope/) (function): Return the active native table scope at acquisition failure. No I/O.
This may be an ancestor table used for inherited lookup.
- [`configuration-partial-records`](/en/lisp/latest/reference/libtmux-configuration-partial-records/) (function): Return owned copies of records fully resolved before acquisition failed. No I/O.
Inspect CONFIGURATION-READ-OUTCOMES for valid individual observations from a
failing or incomplete name. No partial record proves a complete acquisition.
- [`configuration-read-failed`](/en/lisp/latest/reference/libtmux-configuration-read-failed/) (exception): A decoded acquisition failed, retaining prior records and native outcomes.
ERROR-CAUSE identifies the failure. ERROR-OUTCOME retains cause-associated or current
leaf evidence, possibly NIL before the associated read. Its status can be success
when decoding or diagnostics failed. No transport failure becomes absence.
No mutation is retried.
- [`configuration-read-outcomes`](/en/lisp/latest/reference/libtmux-configuration-read-outcomes/) (function): Return a fresh vector of all retained read outcomes, in acquisition order.
Outcome objects retain identity. OUTCOME-VALUE exposes any valid decoded leaf
observation, independently of the native outcome's success status. Preflight
failures can have no selected read outcome. No I/O.
- [`daemon`](/en/lisp/latest/reference/libtmux-daemon/) (class): An explicitly owned foreground tmux daemon and its supervisor.
Create it with START-DAEMON and release it with STOP-DAEMON or WITH-DAEMON.
Ordinary connection clients are separate resources; closing one leaves this
daemon alive. The owner retains failed cleanup work until an explicit retry.
- [`daemon-cleanup-failed`](/en/lisp/latest/reference/libtmux-daemon-cleanup-failed/) (exception): Owned daemon cleanup is incomplete and remains retryable.
ERROR-DAEMON retains the owner. Inspect DAEMON-CLEANUP-FAILURES and retry
STOP-DAEMON; no replacement daemon is started.
- [`daemon-cleanup-failures`](/en/lisp/latest/reference/libtmux-daemon-cleanup-failures/) (function): Return a fresh vector of retained secondary cleanup conditions. No I/O.
Conditions are shared diagnostics, newest first, bounded to sixteen entries.
- [`daemon-failure`](/en/lisp/latest/reference/libtmux-daemon-failure/) (function): Return DAEMON's retained primary failure condition, or NIL. No I/O.
This shared diagnostic can describe background failure after startup returned.
- [`daemon-program`](/en/lisp/latest/reference/libtmux-daemon-program/) (function): Return an owned copy of DAEMON's resolved tmux executable path. No I/O.
Pass it as OPEN-CLIENT's :PROGRAM when connecting through DAEMON-SOCKET-PATH.
- [`daemon-socket-path`](/en/lisp/latest/reference/libtmux-daemon-socket-path/) (function): Return an owned copy of DAEMON's private socket path, or NIL before allocation.
No I/O. An ordinary client may connect while the owner is READY. Closing that
client leaves the daemon alive; STOP-DAEMON releases the daemon itself.
- [`daemon-start-failed`](/en/lisp/latest/reference/libtmux-daemon-start-failed/) (exception): Managed startup failed; ERROR-CAUSE and ERROR-DAEMON retain evidence.
Startup attempts cleanup before propagating this condition. Incomplete cleanup
also remains discoverable through PENDING-DAEMON-CLEANUPS.
- [`daemon-state`](/en/lisp/latest/reference/libtmux-daemon-state/) (function): Return DAEMON's observed lifecycle state without I/O.
States are :STARTING, :READY, :STOPPING, :FAILED and :CLOSED. READY records
completed startup verification, not a promise of future process liveness.
- [`deadline-exceeded`](/en/lisp/latest/reference/libtmux-deadline-exceeded/) (exception): The command exceeded its absolute deadline.
- [`entity`](/en/lisp/latest/reference/libtmux-entity/) (class): An owned observation from one snapshot; construct through acquisition.
Private slot mutation is unsupported. Refresh returns another observation.
- [`entity-model`](/en/lisp/latest/reference/libtmux-entity-model/) (function): Return :SESSION, :WINDOW, :PANE, :WINDOW-LINK or :CLIENT. No I/O.
:CLIENT denotes an attached tmux client observation, not a connection scope.
- [`error-daemon`](/en/lisp/latest/reference/libtmux-error-daemon/) (function): Return the daemon owner retained by a startup or cleanup failure.
The owner may need STOP-DAEMON even when START-DAEMON did not return. No I/O.
- [`error-field`](/en/lisp/latest/reference/libtmux-error-field/) (function): Return the requested field key, including an unregistered key. No I/O.
An invalid caller value is retained as supplied; it need not be a keyword.
- [`error-message`](/en/lisp/latest/reference/libtmux-error-message/) (function): Return the failure's diagnostic string. No I/O; treat it as read-only.
- [`error-model`](/en/lisp/latest/reference/libtmux-error-model/) (function): Return the captured model keyword implicated in a field failure. No I/O.
- [`error-target`](/en/lisp/latest/reference/libtmux-error-target/) (function): Return the captured target associated with a dispatch refusal, or NIL. No I/O.
- [`libtmux-error`](/en/lisp/latest/reference/libtmux-libtmux-error/) (exception): A library failure with a message, original cause and outcome.
- [`outcome-cleanup-failures`](/en/lisp/latest/reference/libtmux-outcome-cleanup-failures/) (function): Return a fresh vector of conditions encountered while releasing the process.
- [`outcome-elapsed`](/en/lisp/latest/reference/libtmux-outcome-elapsed/) (function): Return elapsed monotonic seconds for this retained result. No I/O.
Raw RUN-COMMAND measures its subprocess operation. Named operations include
preflight, dispatch and follow-up acquisition in their retained outcome timing.
- [`outcome-status`](/en/lisp/latest/reference/libtmux-outcome-status/) (function): Return :SUCCEEDED, :FAILED, :UNKNOWN or :NOT-DISPATCHED. No I/O.
These describe retained evidence, not rollback. Observation failure is separate
from mutation success; inspect OUTCOME-OBSERVATION-ERROR and OUTCOME-VALUE.
- [`outcome-unknown`](/en/lisp/latest/reference/libtmux-outcome-unknown/) (exception): A dispatched operation did not establish its final outcome.
- [`output-limit-exceeded`](/en/lisp/latest/reference/libtmux-output-limit-exceeded/) (exception): Combined stdout/stderr exceeded the configured byte limit.
- [`pending-daemon-cleanups`](/en/lisp/latest/reference/libtmux-pending-daemon-cleanups/) (function): Return a fresh vector of owners with incomplete cleanup, without daemon I/O.
The library retains them even when startup leaves through a nonlocal exit.
Successful STOP-DAEMON removes an owner from this collection.
- [`provenance`](/en/lisp/latest/reference/libtmux-provenance/) (function): Return fresh captured provenance and acquisition bounds, without I/O.
- [`session`](/en/lisp/latest/reference/libtmux-session-function/) (function): Return the locally captured session of a link or attached client.
- [`show-environment`](/en/lisp/latest/reference/libtmux-show-environment/) (function): Acquire named raw environment entries; return owned record/outcome vectors.
SCOPE is :GLOBAL or :SESSION; session scope requires a captured TARGET. NAMES
is required; explicit NIL/#() performs no I/O. Native names are nonempty UTF-8
without NUL or =, including names outside the mutation identifier grammar.
Each plist has :NAME, :SCOPE, :TARGET-ID, :VERSION, :STATE and :VALUE. States are
:PRESENT, :REMOVED and :ABSENT. Empty strings remain present. Present/removal
records additionally carry explicit :HIDDEN-P; absent records claim no visibility.
Read ordinary visibility first, then hidden only after empty success. Contradictory
views retry under the original limits. This is not a merged child environment.
Shared limits, ordinary-output assumptions and failure evidence follow SHOW-OPTIONS.
- [`show-hooks`](/en/lisp/latest/reference/libtmux-show-hooks/) (function): Acquire owned hook records and native read outcomes, following SHOW-OPTIONS.
Omitted NAMES enumerates built-in hooks. Explicit dynamic @ names require a
supporting catalog and remain ordinary strings, without a registration claim.
Builtin command values are inert canonical tmux source. Inspection never requests
set-hook -R; ordinary after-read hooks still apply. :SERVER is unavailable.
No Lisp reader or evaluator parses source.
- [`show-option`](/en/lisp/latest/reference/libtmux-show-option/) (function): Acquire one decoded option; return VALUE, PRESENT-P and a read-outcome vector.
False returns NIL,T; absence returns NIL,NIL. KEY selects an entry only after
acquiring a whole named array. A missing key does not fall through a present
local array. Mutable key text is copied before I/O and bounded to 1 MiB UTF-8.
Keys normalize under the exact live catalog before payload reads.
Scopes, limits, inheritance, ownership and failure evidence follow SHOW-OPTIONS.
- [`snapshot`](/en/lisp/latest/reference/libtmux-snapshot/) (class): A finite captured graph assembled over a recorded acquisition interval.
It contains owned observations, not a transactional view of a changing daemon.
Public accessors are local and return fresh mutable values.
- [`start-daemon`](/en/lisp/latest/reference/libtmux-start-daemon/) (function): Start an owned empty-config daemon on a fresh private socket and await readiness.
Uses the qualified SBCL/Linux backend and explicit /dev/null configuration.
ENVIRONMENT is a finite list/vector of distinct NAME=VALUE strings; omission
copies the caller environment, and NIL selects an empty input environment.
Tmux selectors, socket activation and launcher controls are removed. Caller
locale is preserved; Bash shell metadata is not byte-transparent. Environment
values and the native executable remain trusted application configuration.
WORKING-DIRECTORY defaults to the captured current directory. The owner creates
a fresh directory under TEMPORARY-DIRECTORY (default UIOP's temporary directory).
Its canonical ancestors must be owned by this user or root; writable ancestors
must have the sticky bit. No existing daemon or endpoint is adopted.
TIMEOUT is one startup deadline after input preparation, including version and
readiness IPC. OUTPUT-LIMIT must be at least two bytes: half bounds daemon
lifetime diagnostics; the remainder bounds version/readiness output. Cleanup
adds bounded waits; synchronous setup and scheduling can extend caller wall time.
CANCEL-TOKEN affects startup only; after READY, STOP-DAEMON owns cancellation.
Signals DAEMON-START-FAILED with the original cause and owner on startup failure.
- [`stop-daemon`](/en/lisp/latest/reference/libtmux-stop-daemon/) (function): Stop and reap DAEMON's owned child, then remove its checked socket and directory.
Idempotent after success; returns no values. Never targets a daemon through a
reusable PID or socket command. A 0.75-second admission wait and a separate
0.75-second worker join precede any retried job cleanup (up to 0.5 seconds).
Synchronous OS calls and scheduling can extend wall time. Failed cleanup signals
DAEMON-CLEANUP-FAILED and retains the owner for retry. Closing an ordinary client
does not call this function. Terminating the daemon does not establish exit of
every pane descendant.
- [`tmux-version`](/en/lisp/latest/reference/libtmux-tmux-version/) (function): Return a fresh copy of the release string observed when CLIENT opened.
- [`unsupported-platform`](/en/lisp/latest/reference/libtmux-unsupported-platform/) (exception): The selected runtime lacks a qualified backend or required facility.
ERROR-FEATURE identifies the requirement; ERROR-CAUSE retains a failed probe
when available. OPEN-CLIENT checks the profile before resolving PROGRAM.
- [`window`](/en/lisp/latest/reference/libtmux-window-function/) (function): Return the locally captured physical window of a pane or link.
- [`with-daemon`](/en/lisp/latest/reference/libtmux-with-daemon/) (function): Bind a newly started daemon and stop the original owner on every exit.
Accepts START-DAEMON keyword options and body declarations. Preserves multiple
values and the primary nonlocal exit. A cleanup failure after normal completion
signals; during an existing exit it is retained for explicit inspection/retry.

## Guides

Pages that discuss `libtmux`.

### Guides

- [Getting started](/en/lisp/latest/guides/getting-started/)
- [Native queries](/en/lisp/latest/guides/queries/)

### Workspace

- [Workspace guide](/en/lisp/latest/workspace/source-guide/)