API reference

Describe a tmux endpoint without contacting it. Supply exactly one socket selector. A description does not own a daemon or any sessions. Use from_env to opt into the ambient tmux endpoint.

Own one foreground tmux daemon and its private socket directory. server is the explicit endpoint. Call close to reap the daemon and remove its directory; use with_server when ownership can follow a callback's lifetime. This handle does not own unrelated processes launched by application code.

A captured endpoint and opaque daemon-generation observation, not a strict guard.

Match captured SessionSnapshot values without I/O. Omitted keywords are unconstrained. Explicit nothing requires nullable captured absence. All specified fields and related records are checked for coverage first.

Rename an exact object without expanding format text. tmux's name normalization rules still apply. Return the command result.

Remove the referenced tmux object and return its CommandResult . Identity checks are best effort; strict=true refuses execution. Failures after submission may have remote effects and are never retried.

Identify one session/index link and its expected physical window. Operations verify that the slot still contains this window before acting. Generation and link checks are best effort; subprocess commands cannot reserve the link.

Match captured WindowSnapshot values without I/O. Omitted keywords are unconstrained. Explicit nothing requires nullable captured absence. All specified fields and related records are checked for coverage first.

Match captured WindowLink values without I/O. Omitted keywords are unconstrained. Explicit nothing requires nullable captured absence. All specified fields and related records are checked for coverage first.

Rename an exact object without expanding format text. tmux's name normalization rules still apply. Return the command result.

Request absolute dimensions in cells; supply at least one dimension. tmux may constrain pane dimensions to fit adjacent panes. Window resizing selects tmux's manual window-size policy. Return the command result.

Restart the target's original command, or use explicit command argv or shell_command. Running processes are protected unless kill_running=true. Respawning a window reduces it to one pane; other pane references become stale. For shared windows, tmux chooses the session context used for the process environment. Return the command result without retry or rollback.

Remove the referenced tmux object and return its CommandResult . Identity checks are best effort; strict=true refuses execution. Failures after submission may have remote effects and are never retried.

A physical pane viewed through one captured session/window link.

Owned, octal-decoded bytes from one exact pane. age_ms retains tmux's optional extended-output age. Chunks are raw output, not screen images, text lines or command-completion evidence.

Match captured PaneSnapshot values without I/O. Omitted keywords are unconstrained. Explicit nothing requires nullable captured absence. All specified fields and related records are checked for coverage first.

Create a single-owner incremental UTF-8 decoder. decode! returns complete text and retains at most three copied bytes from an incomplete sequence. invalid=:error throws InvalidUTF8Error ; invalid=:replace emits U+FFFD for each maximal subpart described by Unicode 17, section 3.9.6.

Request absolute dimensions in cells; supply at least one dimension. tmux may constrain pane dimensions to fit adjacent panes. Window resizing selects tmux's manual window-size policy. Return the command result.

Restart the target's original command, or use explicit command argv or shell_command. Running processes are protected unless kill_running=true. Respawning a window reduces it to one pane; other pane references become stale. For shared windows, tmux chooses the session context used for the process environment. Return the command result without retry or rollback.

Remove the referenced tmux object and return its CommandResult . Identity checks are best effort; strict=true refuses execution. Failures after submission may have remote effects and are never retried.

An exact client name and observed connection incarnation; names may be reused.

Match captured ClientSnapshot values without I/O. Omitted keywords are unconstrained. Explicit nothing requires nullable captured absence. All specified fields and related records are checked for coverage first.

One sparse hook entry with tmux's canonical command body and inheritance marker.

An exact tmux paste-buffer name.

A configured environment entry; value=nothing marks removal from new processes.

Delete the configured entry, allowing global inheritance.

Mark the variable for removal from new process environments.

Own one finite command's literal arguments. Construction performs no I/O and does not interpret shell text or semicolon separators. Control execution still requires the transport's audited command grammar.

An explicit, task-safe cancellation signal. cancel! is idempotent. Cancelling an operation retires its local resources; it does not roll back tmux effects.

An owned cancellation callback registration; close unregisters and joins its callback.

Own a control client attached to a borrowed session. Closing the connection owns client processes, pipes and Julia tasks, never the session or daemon. Attach/detach still invokes configured hooks and can trigger tmux's destroy-unattached/exit-unattached settings. Aliases and hooks are trusted server configuration; they must not replace admitted command semantics.

A screen capture bracketed by reader cursors, with continuity == :reset. bytes owns the capture. before and after bracket acquisition; neither cursor proves an atomic boundary between this screen and raw pane output. Replaying from either cursor must not be used to reconstruct an exact screen.

A bounded, one-use wait signal whose tmux channel belongs to its connection.

A position bound to a server generation, optional pane, connection epoch, event kind and sequence. Obtain it with observation_cursor . Replay validates its scope and retained history; it is not a screen offset or a persistent cursor across connections.

A single-consumer, bounded event iterator. Use take!(stream; timeout, cancel) for an explicit deadline or for event in stream for connection-lifetime iteration. Close explicitly or use the producer's do-block form for deterministic cleanup. An unreachable stream is retired eventually; GC is not a cleanup deadline. Each fan-out subscriber owns its byte copies; overflow ends only that subscription.

Describe one literal tmux format identifier with a String , Int or Bool decoder. Names match [a-z][a-z0-9_]*; any such name is accepted, including variables outside the snapshot field catalog. Construction does not prove that the connected tmux supports the variable or supplies it in a given context. Expressions, option names and command substitutions require RawFormat .

Unverified candidate names from tmux's unescaped format listing. result retains bounded raw command evidence. availability is :unverified and complete is false; candidate names do not prove variable support.

One explicit format observation. :present means a nonempty expansion, not a version-support guarantee. Empty expansions have availability=:unverified: tmux cannot distinguish an empty value from an unknown or unavailable variable. raw always retains the decoded text. Empty strings retain value=""; numeric and Boolean observations use value=nothing until their value is verified.

One sampled format field, with session and window-link context. bytes retains the field codec's escaped value; window_index is tmux's contextual index. Optional window/pane references distinguish session-level updates. Pane values may repeat for multiple links; their context is preserved rather than deduplicated.

An explicit executable tmux format expression. In particular, #() can start shell commands on the tmux host. It is never inferred from a field name or evaluated during construction. tmux controls expansion, job scheduling and cached command-substitution results; rendering does not wait for those jobs.

A validated local predicate; portable criteria never contain caller callbacks.

Named local filter operators. Import as import LibTmux.Filters as F.

Read-only scalar rows over one captured selection. Construct with project_rows . Column names and types survive empty selections. Retaining this projection retains its source snapshot. No operation refreshes data.

Read-only, ordered membership copied from items. Filtering preserves its element type, order, duplicates and snapshot provenance. A small selection may retain its entire snapshot. collect, map and similar return ordinary mutable arrays. Elements supplied by callers are not recursively frozen.

Bound the complete inert document before constructing predicates. Nodes count objects, arrays, keys and scalars; bytes count UTF-8 strings and keys together. Limits also apply when encoding local criteria. They do not limit later graph traversal, which depends on the supplied snapshot.

An inert object retaining key pairs, including duplicates, until validation. External codecs must preserve duplicate keys or reject them during parsing. An ordinary Dict cannot reveal keys discarded before decode_where runs.

Membership in a copied, immutable tuple of scalar operands.

Read criteria JSON after using JSON loads the optional codec extension. Input byte, nesting and token bounds are checked before JSON materialization; duplicate keys and invalid JSON raise WireCriteriaError .

Write criteria JSON after using JSON loads the optional codec extension.

Privately owned captured records and membership coverage. Acquiring a new snapshot never refreshes an existing one. Its acquisition interval describes process-relative monotonic seconds, not UTC or a tmux transaction. Obtain collections with panes , windows , sessions , clients , windowlinks , and paneoccurrences .

A capture decoding failure with its cause and an owned copy of source bytes.

An owned control buffer could not be retired; buffer identifies the possible remote resource.

Local resources closed, but retirement of submitted backend work was not proved.

An admitted control command failed; result retains its owned reply bytes and guard.

A terminal control-lane failure; sent distinguishes possible remote effects from non-submission.

An exact control target did not resolve; no fallback observation is returned.

A creation command completed, but its reply could not establish the result. result retains the command output and exit evidence; cause explains the invalid reply or changed identity. sent is always true: remote effects may have occurred. The library neither retries creation nor removes its results.

A nonempty format value failed its requested decoder; command bytes remain in result .

Malformed UTF-8 at the one-based byte offset of a stream subsequence.

An exact-cardinality criterion matched at least two items; the remaining source may not be counted.

An exact-cardinality criterion matched no items in its source.

An observation gap or invalid replay position; cursor is the last accepted position.

Captured data cannot answer a requested field or relation; this is not a no-match result.

A criterion outside a named sibling profile's verified portable subset.

A criteria document error with a stable code and structural location.

Cleanup finished with forced termination, incomplete diagnostics, or lost directory ownership.

Startup failed after the owned daemon was spawned; result retains its exit evidence.

An ordered, read-only finite collection of independently executed command outcomes.

Owned output bytes and exit evidence from one completed tmux client.

Owned reply bytes and guard for an admitted control command. run_command returns after its completion fence; grouped outcomes expose completion separately when cancellation leaves only a partial response.

An explicit semicolon group's outcomes and aggregate response. retired means its completion fence was observed. opaque means the transport could not attribute the aggregate response to individual commands. A group is not a transaction; successful effects before an error remain applied.

A known tmux notification. name is its protocol name as a symbol; bytes owns the complete record without its final LF. No UTF-8 conversion is implied.

A notification, raw pane-output chunk or sampled format value with an observation cursor.

One input-indexed outcome. status is :completed, :failed, :skipped, or :unknown. acknowledged records a response; completed records queue completion for an audited synchronous command. result and error retain the evidence. Background application work is never inferred complete.

A typed entity identity bound to a captured daemon generation.

A validated tmux numeric ID whose type fixes its entity kind.