API reference

Server is an immutable handle to one tmux configuration. Its zero value is invalid. Copying a configured Server preserves its configuration and shares its mutex-guarded version cache and checked daemon identity, so a Server and the values derived from it are safe for concurrent method calls (see the package documentation).

ServerOptionValues is an immutable materialized view of known server option values; its zero value is empty and it does not refresh. Obtain it with Server.Options. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Server.RawOption for caller-named or undecoded values.

NewServer validates and snapshots one tmux configuration without starting tmux. Empty socket selectors use the endpoint the frozen environment selects, as ServerOptions describes.

NewServerFromEnv returns a server configured from TMUX without starting tmux. It snapshots the process environment once. A nonnil environment supplies discovery values and overrides that snapshot for later tmux processes; an empty map therefore has no TMUX discovery value. Names follow the platform's environment rules and are case-insensitive on Windows.

Session is one materialized tmux session record. It is normally returned by Server.Snapshot, Server.Session, or Session.Refresh. A zero Session is not a usable tmux target.

SessionID is tmux's stable session identifier, including its $ sigil. The zero value is not a usable tmux target.

SessionOptionValues is an immutable materialized view of known session option values; its zero value is empty and it does not refresh. Obtain it with Session.Options or GlobalSessionScope.Options. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Session.RawOption or GlobalSessionScope.RawOption for caller-named or undecoded values.

GlobalSessionScope is an immutable handle for global session options and hooks. Its zero value is invalid because it contains a zero Server.

SessionFromEnv returns the canonical session containing the environment's pane. Nil reads the process environment; a nonnil empty map does not.

ValidateSessionName reports whether name can be used as a tmux session name. Empty names, the target delimiters '.' and ':', control characters and invalid UTF-8 are rejected.

Window is one materialized (session, index, window) winlink record. It is normally returned by Server.Snapshot, Server.Window, or Window.Refresh. A zero Window is not a usable tmux target.

WindowID is tmux's stable window identifier, including its @ sigil. It does not distinguish linked-session views; the zero value is not a usable target.

WindowSize is a typed value for the "window-size" tmux option. Its zero value is invalid.

WindowOptionValues is an immutable materialized view of known window option values; its zero value is empty and it does not refresh. Obtain it with Window.Options or GlobalWindowScope.Options. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Window.RawOption or GlobalWindowScope.RawOption for caller-named or undecoded values.

GlobalWindowScope is an immutable handle for global window options and hooks. Its zero value is invalid because it contains a zero Server.

NewWindowDirection selects placement relative to the target winlink on every supported tmux. Its zero value lets Session.NewWindow with nil Index use the next free index, while Window.NewWindow keeps the receiver's exact occupied target.

RotateWindowDirection selects rotate-window's direction on tmux 3.3a or later. Its zero value uses tmux's default rotation.

WindowResizeDirection selects one directional resize operation on tmux 3.3a or later. Its zero value selects no directional adjustment.

NewWindowDirectionAfter places the new winlink after the target.

NewWindowDirectionBefore places the new winlink before the target.

NewWindowDirectionDefault uses the next free index with Session.NewWindow when Index is nil; Window.NewWindow instead keeps the receiver's exact occupied target.

RotateWindowDefault uses tmux's default rotation.

RotateWindowDown rotates pane positions toward higher indexes.

RotateWindowUp rotates pane positions toward lower indexes.

WindowResizeDirectionDown adjusts the window downward.

WindowResizeDirectionLeft adjusts the window leftward.

WindowResizeDirectionNone selects no directional adjustment.

WindowResizeDirectionRight adjusts the window rightward.

WindowResizeDirectionUp adjusts the window upward.

WindowSizeLargest selects "largest".

WindowSizeLatest selects "latest".

WindowSizeManual selects "manual".

WindowSizeSmallest selects "smallest".

WindowFromEnv returns the window containing the pane identified by the environment. Nil reads the process environment; a nonnil empty map does not.

Pane is one materialized pane record within a specific winlink. It is normally returned by Server.Snapshot, Server.Pane, or Pane.Refresh. A zero Pane is not a usable tmux target.

PaneDirection selects where a tiled pane is created or moved on tmux 3.3a or later. Its zero value places the pane below the target.

PaneID is tmux's stable pane identifier, including its % sigil. It does not distinguish linked-session views; the zero value is not a usable target.

PaneBorderIndicators is a typed value for the "pane-border-indicators" tmux option. Its zero value is invalid.

PaneBorderLines is a typed value for the "pane-border-lines" tmux option. Its zero value is invalid.

PaneBorderStatus is a typed value for the "pane-border-status" tmux option. Its zero value is invalid.

PaneScrollbars is a typed value for the "pane-scrollbars" tmux option. Its zero value is invalid.

PaneScrollbarsPosition is a typed value for the "pane-scrollbars-position" tmux option. Its zero value is invalid.

PaneOptionValues is an immutable materialized view of known pane option values; its zero value is empty and it does not refresh. Obtain it with Pane.Options. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Pane.RawOption for caller-named or undecoded values.

PaneResizeDirection selects a directional Pane.Resize. Its zero value selects no directional adjustment.

PaneSize is an opaque absolute cell count or percentage for Pane.Resize. Its zero value omits the dimension. [PaneCells](0) and [PanePercent](0) are explicit sizes, not zero PaneSize values.

PaneEndReason says how a pane ended during Pane.WaitForText.

PaneTextWait is the result of Pane.WaitForText. It is returned with every error, holding what the last read saw.

PaneText is what a pane wrote after an observation's baseline, as the text a person would read: escape sequences removed, UTF-8 joined across writes, and each carriage return or backspace that would overwrite text starting a new line, so nothing the program wrote is hidden.

SwapPaneDirection selects an adjacent pane for swap-pane on tmux 3.3a or later. Its zero value selects no adjacent pane.

PaneSelectDirection selects a pane relative to the command target on tmux 3.3a or later. Its zero value selects no relative direction.

PaneBorderIndicatorsArrows selects "arrows".

PaneBorderIndicatorsBoth selects "both".

PaneBorderIndicatorsColour selects "colour".

PaneBorderIndicatorsOff selects "off".

PaneBorderLinesDouble selects "double".

PaneBorderLinesHeavy selects "heavy".

PaneBorderLinesNumber selects "number".

PaneBorderLinesSimple selects "simple".

PaneBorderLinesSingle selects "single".

PaneBorderLinesSpaces selects "spaces".

PaneBorderStatusBottom selects "bottom".

PaneBorderStatusOff selects "off".

PaneBorderStatusTop selects "top".

PaneDirectionAbove places the pane above the target.

PaneDirectionBelow places the pane below the target.

PaneDirectionLeft places the pane to the left of the target.

PaneDirectionRight places the pane to the right of the target.

PaneExited is a pane whose program exited and which remain-on-exit kept on screen.

PaneGone is a pane that no longer exists while its server does.

PaneResizeDirectionDown selects tmux's downward adjustment.

PaneResizeDirectionLeft selects tmux's leftward adjustment.

PaneResizeDirectionNone omits a directional resize.

PaneResizeDirectionRight selects tmux's rightward adjustment.

PaneResizeDirectionUp selects tmux's upward adjustment.

PaneScrollbarsModal selects "modal".

PaneScrollbarsOff selects "off".

PaneScrollbarsOn selects "on".

PaneScrollbarsPositionLeft selects "left".

PaneScrollbarsPositionRight selects "right".

PaneSelectDirectionDown selects the pane below the target.

PaneSelectDirectionLast selects the previously active pane.

PaneSelectDirectionLeft selects the pane to the left of the target.

PaneSelectDirectionNone selects no relative pane.

PaneSelectDirectionRight selects the pane to the right of the target.

PaneSelectDirectionUp selects the pane above the target.

ServerGone is a server that is not running, or that exited during the wait.

SwapPaneDirectionDown swaps with the next pane in index order.

SwapPaneDirectionNone selects no adjacent pane.

SwapPaneDirectionUp swaps with the previous pane in index order.

PaneCells returns an explicit pane size measured in cells. Resize validates that cells is nonnegative; zero remains an explicit request.

PaneFromEnv returns the pane identified by TMUX and TMUX_PANE. Nil reads the process environment; a nonnil empty map does not. Environment names are case-insensitive on Windows. It resolves the live hierarchy later through identity-checked tmux queries.

PanePercent returns an explicit percentage of the window size. Resize validates that percent is between 0 and 100 inclusive; zero remains an explicit request.

Client is one materialized tmux client record. It is normally returned by Server.Snapshot, Server.Client, or Client.Refresh. A zero Client is not a usable tmux target.

ClientAttachment is one immutable view of a client's live attachment. Session, Window, and Pane return values from the same observational Snapshot.

ClientName is tmux's stable client name, normally its terminal path. The zero value is not a usable tmux target.

ServerHookValues is an immutable materialized view of known global session-scope hook values; its zero value is empty and it does not refresh. Obtain it with GlobalSessionScope.Hooks. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use GlobalSessionScope.RawHook for caller-named or undecoded values.

SessionHookValues is an immutable materialized view of known session hook values; its zero value is empty and it does not refresh. Obtain it with Session.Hooks. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Session.RawHook for caller-named or undecoded values.

WindowHookValues is an immutable materialized view of known window hook values; its zero value is empty and it does not refresh. Obtain it with Window.Hooks or GlobalWindowScope.Hooks. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Window.RawHook or GlobalWindowScope.RawHook for caller-named or undecoded values.

PaneHookValues is an immutable materialized view of known pane hook values; its zero value is empty and it does not refresh. Obtain it with Pane.Hooks. OptionValue.Get reports presence and OptionValue.Origin reports inheritance. Use Pane.RawHook for caller-named or undecoded values.

AllowPassthrough is a typed value for the "allow-passthrough" tmux option. Its zero value is invalid.

CopyModeLineNumbers is a typed value for the "copy-mode-line-numbers" tmux option. Its zero value is invalid.

DestroyUnattached is a typed value for the "destroy-unattached" tmux option. Its zero value is invalid.

DetachOnDestroy is a typed value for the "detach-on-destroy" tmux option. Its zero value is invalid.

ExtendedKeys is a typed value for the "extended-keys" tmux option. Its zero value is invalid.

GetClipboard is a typed value for the "get-clipboard" tmux option. Its zero value is invalid.

MenuBorderLines is a typed value for the "menu-border-lines" tmux option. Its zero value is invalid.

MessageLine is a typed value for the "message-line" tmux option. Its zero value is invalid.

ModeKeys is a typed value for the "mode-keys" tmux option. Its zero value is invalid.

PopupBorderLines is a typed value for the "popup-border-lines" tmux option. Its zero value is invalid.

RemainOnExit is a typed value for the "remain-on-exit" tmux option. Its zero value is invalid.

SetClipboard is a typed value for the "set-clipboard" tmux option. Its zero value is invalid.

Status is a typed value for the "status" tmux option. Its zero value is invalid.

StatusJustify is a typed value for the "status-justify" tmux option. Its zero value is invalid.

StatusKeys is a typed value for the "status-keys" tmux option. Its zero value is invalid.

StatusPosition is a typed value for the "status-position" tmux option. Its zero value is invalid.

VisualActivity is a typed value for the "visual-activity" tmux option. Its zero value is invalid.

VisualBell is a typed value for the "visual-bell" tmux option. Its zero value is invalid.

VisualSilence is a typed value for the "visual-silence" tmux option. Its zero value is invalid.

OptionOrigin identifies where a present option value was resolved. The declared values form the complete set of valid origins.

OptionValue preserves option presence and resolution origin. Its zero value is absent. Copies of reference-bearing T values are shallow.

AllowPassthroughAll selects "all".

AllowPassthroughOff selects "off".

AllowPassthroughOn selects "on".

CopyModeLineNumbersAbsolute selects "absolute".

CopyModeLineNumbersDefault selects "default".

CopyModeLineNumbersHybrid selects "hybrid".

CopyModeLineNumbersOff selects "off".

CopyModeLineNumbersRelative selects "relative".

DestroyUnattachedKeepGroup selects "keep-group".

DestroyUnattachedKeepLast selects "keep-last".

DestroyUnattachedOff selects "off".

DestroyUnattachedOn selects "on".

DetachOnDestroyNext selects "next".

DetachOnDestroyNoDetached selects "no-detached".

DetachOnDestroyOff selects "off".

DetachOnDestroyOn selects "on".

DetachOnDestroyPrevious selects "previous".

ExtendedKeysAlways selects "always".

ExtendedKeysOff selects "off".

ExtendedKeysOn selects "on".

GetClipboardBoth selects "both".

GetClipboardBuffer selects "buffer".

GetClipboardOff selects "off".

GetClipboardRequest selects "request".

MenuBorderLinesDouble selects "double".

MenuBorderLinesHeavy selects "heavy".

MenuBorderLinesNone selects "none".

MenuBorderLinesPadded selects "padded".

MenuBorderLinesRounded selects "rounded".

MenuBorderLinesSimple selects "simple".

MenuBorderLinesSingle selects "single".

MessageLine0 selects "0".

MessageLine1 selects "1".

MessageLine2 selects "2".

MessageLine3 selects "3".

MessageLine4 selects "4".

ModeKeysEmacs selects "emacs".

ModeKeysVi selects "vi".

OptionOriginInherited identifies a value inherited from a parent scope.

OptionOriginLocal identifies a value set directly at the queried scope.

PopupBorderLinesDouble selects "double".

PopupBorderLinesHeavy selects "heavy".

PopupBorderLinesNone selects "none".

PopupBorderLinesPadded selects "padded".

PopupBorderLinesRounded selects "rounded".

PopupBorderLinesSimple selects "simple".

PopupBorderLinesSingle selects "single".

RemainOnExitFailed selects "failed".

RemainOnExitKey selects "key".

RemainOnExitOff selects "off".

RemainOnExitOn selects "on".

SetClipboardExternal selects "external".

SetClipboardOff selects "off".

SetClipboardOn selects "on".

Status2 selects "2".

Status3 selects "3".

Status4 selects "4".

Status5 selects "5".

StatusJustifyAbsoluteCentre selects "absolute-centre".

StatusJustifyCentre selects "centre".

StatusJustifyLeft selects "left".

StatusJustifyRight selects "right".

StatusKeysEmacs selects "emacs".

StatusKeysVi selects "vi".

StatusOff selects "off".

StatusOn selects "on".

StatusPositionBottom selects "bottom".

StatusPositionTop selects "top".

VisualActivityBoth selects "both".

VisualActivityOff selects "off".

VisualActivityOn selects "on".

VisualBellBoth selects "both".

VisualBellOff selects "off".

VisualBellOn selects "on".

VisualSilenceBoth selects "both".

VisualSilenceOff selects "off".

VisualSilenceOn selects "on".

PrefixKey selects the primary or secondary tmux prefix key. Its zero value selects the primary prefix.

PrefixPrimary selects tmux's primary prefix key.

PrefixSecondary selects tmux's secondary prefix key.

EnvironmentValue is one tmux environment value or removal marker. Its zero value is an ordinary empty value, not a removal marker.

TerminalFeature is one terminal pattern and its enabled features.

TerminalFeatures is an immutable parsed terminal-features option. Its zero value is an empty collection: Len is zero, Lookup reports false, and Entries returns a nonnil empty slice.

TerminalOverrideValue is a flag, arbitrary-precision integer, or string. Its zero value has no recognized kind: IsFlag is false, Integer and Text report false, and it represents no parsed capability assignment.

TerminalCapability is one parsed terminal override capability.

TerminalOverride is the immutable capability set for one terminal pattern. Its zero value is an empty immutable collection: Len is zero, Lookup reports false, and Entries returns a nonnil empty slice.

TerminalOverrideEntry is one terminal pattern and its parsed capabilities.

TerminalOverrides is an immutable parsed terminal-overrides option. Its zero value is an empty immutable collection: Len is zero, Lookup reports false, and Entries returns a nonnil empty slice.

Version is a parsed tmux version that preserves its original token. Obtain a value with ParseVersion, Server.Version, or Snapshot.Version. Its zero value has no feature level and is useful only as an absent version. Parsed OpenBSD base-system tokens also have no feature level until Server.Version probes the configured binary's commands.

MinimumConnectionVersion qualifies owned control initialization. Ordinary subprocess operations retain MinimumSupportedVersion.

MinimumSupportedVersion is the oldest tmux release supported by this package.

ModulePath is the Go module this package belongs to. It is the module path rather than the package path, because that is what Go build metadata records.

PackageVersion returns the release version recorded in Go build metadata. Development builds and binaries without module metadata return "", false.

ParseVersion parses a raw tmux version token. It returns a VersionError matching ErrInvalidVersion when the token cannot be parsed.

CommandAlias is one parsed command-alias entry.

CommandAliases is an immutable parsed command-alias option. Its zero value is an empty collection: Len is zero, Lookup reports false, and Entries returns a nonnil empty slice.

Connection owns terminal control-mode transport to the exact daemon that materialized its session. Values obtained from Server or Session retain the connection. Closing is terminal: they neither reconnect nor fall back to a subprocess. Its lanes are attached tmux clients; closing the last client can trigger tmux's destroy-unattached or exit-unattached policy. Destroying its initial session moves the clients to another session when one exists; the retained Session value keeps its original identity.

CommandTransport names how one tmux command reached tmux.

CommandTrace records one completed attempt to run a tmux command. It carries neither the argument vector nor tmux's output, both of which may hold passwords, tokens, or pane contents; CommandError is where a caller that accepts that reads them.

CommandObserver receives one CommandTrace per tmux command a Server and the values derived from it run:

Running is a command started by Session.Start: a real process, already under way, in a pane of its own. Running.Pane exposes that pane so its output can be streamed with Pane.OpenObservation or typed into with Pane.Writer while the command runs; Running.Wait and Running.Kill wait for and stop it. A line printed with nothing separating it from the command's own exit can race tmux's control-mode notification of it and never reach PaneObservation.Reader; RunResult.Lines from Wait, a plain screen capture rather than that notification stream, always has it.

CommandTransportConnection carried the command over a control-mode connection opened earlier.

CommandTransportProcess ran the command as its own tmux process.

ControlClient is one attached tmux control-mode process. Create one with Server.OpenControl. Concurrent Cmd, Wait, close, and NextNotification calls are supported; concurrent notification reads are serialized.

ControlNotification is an immutable parsed tmux control-mode notification. Its zero value has an empty kind and no arguments. Values returned by ParseControlNotification own copied arguments and are safe to retain.

SubscriptionChange is one evaluated format value reported by a subscription armed with NotificationStream.Subscribe. The scope fields tmux did not evaluate against are zero: a session-scoped subscription reports no window or pane, and a window-scoped one reports no pane.

PaneObservation is one visible pane baseline followed by the exact control notification stream after that baseline. That stream is the observation's whole control connection, so a caller wanting only this pane's output selects it by identifier. Create one with Pane.OpenObservation and close it when finished. Copies share notification reader ownership, terminal loss, and client lifetime; closing one closes them all.

NotificationStream owns one observation-only control client attached to a session. It yields tmux notifications in wire order and must be closed. Acquisition requires tmux 3.7 before any control client is started.

ParseControlNotification parses one newline-free tmux control-mode notification record. It requires exact control framing and a supported kind, returns errors compatible with ErrMalformedControlNotification or ErrUnknownControlNotification, and copies all caller-owned input before returning. It never returns a partial notification.

FormatValues is a read-only view of format expansions materialized with a Session, Window, Pane, or Client. Its methods do not query tmux. Projected cross-scope fields do not imply that the referenced record was materialized.

ExtendedKeysFormat is a typed value for the "extended-keys-format" tmux option. Its zero value is invalid.

ExtendedKeysFormatCSIU selects "csi-u".

ExtendedKeysFormatXTerm selects "xterm".

SessionFilter matches materialized Session values without tmux I/O. Its zero value matches every non-nil candidate. Criteria are ANDed; AnyOf adds an OR requirement and Not excludes. Field and relation criteria correspond to Session.ID, Session.Name, Session.Attached, Session.Windows, and Session.Panes. SessionFilter.Validate and methods that consume the filter reject invalid criteria with ErrInvalidFilter.

WindowFilter matches materialized Window values without tmux I/O. Its zero value matches every non-nil candidate. Criteria are ANDed; AnyOf adds an OR requirement and Not excludes. Field and relation criteria correspond to Window.SessionID, Window.ID, Window.Index, Window.Name, Window.Active, Window.Session, and Window.Panes. WindowFilter.Validate and methods that consume the filter reject invalid criteria with ErrInvalidFilter.

PaneFilter matches materialized Pane values without tmux I/O. Its zero value matches every non-nil candidate. Criteria are ANDed; AnyOf adds an OR requirement and Not excludes. Field and relation criteria correspond to Pane.SessionID, Pane.WindowID, Pane.ID, Pane.WindowIndex, Pane.Index, Pane.CurrentCommand, Pane.Active, Pane.Title, Pane.Session, and Pane.Window. PaneFilter.Validate and methods that consume the filter reject invalid criteria with ErrInvalidFilter.

ClientFilter matches materialized Client values without tmux I/O. Its zero value matches every non-nil candidate. Criteria are ANDed; AnyOf adds an OR requirement and Not excludes. Field and relation criteria correspond to Client.Name, Client.ReadOnly, Client.AttachedSession, Client.AttachedWindow, and Client.AttachedPane. ClientFilter.Validate and methods that consume the filter reject invalid criteria with ErrInvalidFilter.

WindowRel applies quantifiers to a materialized Window relation; its zero value is invalid. Some is existential, Every is universal and vacuously true for an empty relation, and None excludes; enabled quantifiers are conjunctive.

PaneRel applies quantifiers to a materialized Pane relation; its zero value is invalid. Some is existential, Every is universal and vacuously true for an empty relation, and None excludes; enabled quantifiers are conjunctive.

TmuxFilter is a raw tmux -f format expression. It is distinct from the generated local filter structs and is evaluated only by tmux. A nil filter omits -f; a nonnil empty filter sends an explicit empty expression.

Filter is anything that compiles itself into a predicate over T, which is what the tmux package's generated model filters do. It exists so a filter and a query can meet without this package naming a model.

FilterSchemaVersion identifies external metadata for the generated filter JSON wire schema. It is not embedded in JSON and is independent of the tmux Version.

ClientNameIs returns a ClientFilter that exactly matches the stable tmux client name from Client.Name. It sets no other criteria and does not validate value.

ClientReadOnlyIs returns a ClientFilter that exactly matches the materialized read-only state from Client.ReadOnly. It sets no other criteria and does not validate value.

ExactlyOne returns a shallow copy when exactly one source-ordered value is accepted by predicate. It examines values until source exhaustion confirms a sole match, or stops at the second match. It returns the zero value of T with ErrNoMatch for no matches or ErrMultipleMatches for multiple matches; callers can classify either error with errors.Is.

ExactlyOneSeq returns a shallow copy when exactly one source-ordered sequence value is accepted by predicate. It stops pulling at the second match. If input ends with no matches, it returns the zero value of T with ErrNoMatch; if it finds a second match, it returns the zero value of T with ErrMultipleMatches. Callers can classify either error with errors.Is. With an infinite input, ExactlyOneSeq returns only after a second match; it cannot confirm a no-match or exactly-one result without source exhaustion.

First returns a shallow copy of the first source-ordered value accepted by predicate and stops evaluating later values. If no value matches, it returns the zero value of T and false.

FirstSeq returns a shallow copy of the first source-ordered sequence value accepted by predicate and stops pulling later values. If no value matches, it returns the zero value of T and false. With an infinite input that never matches, FirstSeq does not return.

Matching returns a fresh slice of shallow copies for values that filter accepts, retaining their source order, and reports the one error a filter can have rather than leaving it for the caller to unpack first. It evaluates every input value, so a no-match result is an empty slice.

MatchingSeq returns a lazy sequence of shallow copies for values that filter accepts, retaining source order. The filter is compiled before iteration begins, so an invalid filter is an error here rather than a sequence that yields nothing.

PaneActiveIs returns a PaneFilter that exactly matches the materialized active state from Pane.Active. It sets no other criteria and does not validate value.

PaneCommandIs returns a PaneFilter that exactly matches the materialized current command from Pane.CurrentCommand. It sets no other criteria and does not validate value.

PaneIDIs returns a PaneFilter that exactly matches the stable tmux pane identifier from Pane.ID, including its % sigil. It sets no other criteria and does not validate value.

PaneIndexIs returns a PaneFilter that exactly matches the nonnegative pane index from Pane.Index. It sets no other criteria and does not validate value.

PaneSessionIDIs returns a PaneFilter that exactly matches the stable tmux session identifier from Pane.SessionID, including its $ sigil. It sets no other criteria and does not validate value.

PaneTitleIs returns a PaneFilter that exactly matches the materialized title from Pane.Title. It sets no other criteria and does not validate value.

PaneWindowIDIs returns a PaneFilter that exactly matches the stable tmux window identifier from Pane.WindowID, including its @ sigil. It sets no other criteria and does not validate value.

PaneWindowIndexIs returns a PaneFilter that exactly matches the nonnegative winlink index from Pane.WindowIndex. It sets no other criteria and does not validate value.

ParseClientLookup converts a lookup path into a concrete client filter. Paths traverse generated JSON relation names and separate segments with double underscores. The default operator is exact. Accepted suffixes are eq, exact, iexact, contains, icontains, startswith, istartswith, endswith, iendswith, in, nin, regex, and iregex; availability is field-specific. The eq suffix aliases exact, nin negates in, scalar operators require one value, and in and nin require one or more. Invalid paths, operators, values, or results wrap ErrInvalidFilter.

ParsePaneLookup converts a lookup path into a concrete pane filter. Paths traverse generated JSON relation names and separate segments with double underscores. The default operator is exact. Accepted suffixes are eq, exact, iexact, contains, icontains, startswith, istartswith, endswith, iendswith, in, nin, regex, and iregex; availability is field-specific. The eq suffix aliases exact, nin negates in, scalar operators require one value, and in and nin require one or more. Invalid paths, operators, values, or results wrap ErrInvalidFilter.

ParseSessionLookup converts a lookup path into a concrete session filter. Paths traverse generated JSON relation names and separate segments with double underscores. The default operator is exact. Accepted suffixes are eq, exact, iexact, contains, icontains, startswith, istartswith, endswith, iendswith, in, nin, regex, and iregex; availability is field-specific. The eq suffix aliases exact, nin negates in, scalar operators require one value, and in and nin require one or more. Invalid paths, operators, values, or results wrap ErrInvalidFilter.

ParseWindowLookup converts a lookup path into a concrete window filter. Paths traverse generated JSON relation names and separate segments with double underscores. The default operator is exact. Accepted suffixes are eq, exact, iexact, contains, icontains, startswith, istartswith, endswith, iendswith, in, nin, regex, and iregex; availability is field-specific. The eq suffix aliases exact, nin negates in, scalar operators require one value, and in and nin require one or more. Invalid paths, operators, values, or results wrap ErrInvalidFilter.

Ptr returns a distinct pointer to a shallow copy of value, including when T has zero size. Its nonzero holder prevents Go from coalescing zero-size addresses. Slices, maps, pointers, and other reference-bearing values still alias their referenced data. Ptr performs no validation or ownership transfer.

SessionAttachedIs returns a SessionFilter that exactly matches the materialized attachment state from Session.Attached. It sets no other criteria and does not validate value.

SessionIDIs returns a SessionFilter that exactly matches the stable tmux session identifier from Session.ID, including its $ sigil. It sets no other criteria and does not validate value.

SessionNameIs returns a SessionFilter that exactly matches the materialized session name from Session.Name. It sets no other criteria and does not validate value.

Where returns a fresh slice of shallow copies for values accepted by predicate, retaining their source order. It evaluates every input value, so a no-match result is an empty slice.

WhereSeq returns a lazy sequence of shallow copies for values accepted by predicate, retaining source order. It does not pull values until the result is iterated. When its consumer stops, WhereSeq stops pulling from values. For an infinite input, it runs until its consumer stops.

WindowActiveIs returns a WindowFilter that exactly matches the materialized active state from Window.Active. It sets no other criteria and does not validate value.

WindowIDIs returns a WindowFilter that exactly matches the stable tmux window identifier from Window.ID, including its @ sigil. It sets no other criteria and does not validate value.

WindowIndexIs returns a WindowFilter that exactly matches the nonnegative winlink index from Window.Index. It sets no other criteria and does not validate value.

WindowNameIs returns a WindowFilter that exactly matches the materialized window name from Window.Name. It sets no other criteria and does not validate value.

WindowSessionIDIs returns a WindowFilter that exactly matches the stable tmux session identifier from Window.SessionID, including its $ sigil. It sets no other criteria and does not validate value.

CapturePosition selects a line relative to tmux's visible pane or history. Its zero value omits the boundary and lets tmux use the visible-screen default. Construct numeric positions with CaptureLine.

Snapshot is an immutable, observational view of one tmux server. It is normally returned by Server.Snapshot. Its zero value has a zero Version, a zero Server, non-nil empty collection slices, and not-found point lookups. Accessors never query tmux; returned slices are newly allocated and their contained records are shallow copies.

CaptureBoundary selects the start of history when used as Start and the end of the visible pane when used as End.

CaptureLine returns the canonical tmux representation of a capture line. Zero is the first visible line; negative values address history.

Ref addresses an existing object, the tmux server, or an object an earlier Plan step will create. This permits forward construction without tmux I/O.

Op is one tmux command a Plan has recorded but not run. Build one with a Plan method rather than directly; the zero value records nothing.

Dispatch is one tmux invocation and the operations it carries. A dispatch holding more than one operation is sent as a tmux command list.

Sequential sends every operation as its own tmux invocation. It is the simplest correct planner, and useful as a baseline: a plan produces the same results through it as through Folding, at one invocation per operation.

Folding groups each run of operations that neither answer nor create into one tmux command list, and sends the rest alone. It is what Plan.Run uses.

OpStatus reports what became of one operation in a plan.

OpComplete is an operation tmux ran successfully.

OpFailed is an operation tmux refused. Only an operation sent alone can receive this status.

OpIndeterminate is an operation dispatched without enough reply evidence to prove whether tmux applied or rejected it.

OpSkipped is an operation the plan did not dispatch because an earlier dispatch failed or became indeterminate.

Plan records ordered tmux commands for later execution. It groups commands that need no answer and lets later steps reference objects earlier steps create.

Planner groups a plan's operations into tmux invocations.

NewPlan returns an empty Plan.

SessionRef returns a selector-relative Ref addressing a session by ID, for a caller holding an identifier rather than a materialized record.

WindowRef returns a selector-relative Ref addressing a window by ID, for a caller holding an identifier rather than a materialized record.

PaneRef returns a selector-relative Ref addressing a pane by ID, for a caller holding an identifier rather than a materialized record.

ServerRef returns a Ref addressing the tmux server, for the operations that document a server scope, such as Plan.SetEnvironment and Plan.Cmd.

DisplayMessageRequest configures display-message options shared by server, window, and pane scope. A zero request displays tmux's default message and returns nil. Print returns an owned stdout slice instead of displaying only to a client status line. Nil pointer fields omit their flags while pointers to empty values are explicit; a zero TargetClient omits its flag.

SubscriptionRequest names a format for tmux to evaluate and report on this stream whenever its value changes. Its zero value is invalid because Name and Format are required. At most one of Window and Pane scopes the evaluation; neither evaluates against the stream's attached session, which tmux always uses for a session-scoped subscription and which cannot be selected.

SendKeysRequest configures tmux key input. Pointer values are copied before I/O and must not be mutated concurrently.

SendKeySequenceRequest configures ordered pane key delivery. Keys must contain at least one nonempty operand. SendKeySequence copies Keys before I/O; callers must not mutate it concurrently with the call.

ClearHistoryRequest configures pane history clearing. Its zero value clears scrollback without requesting hyperlink cleanup.

CopyModeRequest configures tmux copy mode. Its zero value enters copy mode on the receiver without scrolling. Fields may be combined. tmux resolves the receiver and optional SourcePane before processing Cancel, so a stale target can prevent reset. After resolution, Cancel takes precedence over other actions, though SourcePane validation and the PageDown version probe still occur first.

ChooseTreeRequest configures the interactive session and window chooser. Its zero value uses tmux defaults. Format and Filter are copied before execution and must not be mutated concurrently.

DisplayPopupRequest configures a popup overlay. Pointer and map values are copied before I/O and must not be mutated concurrently. Pointer fields distinguish omission from an explicit empty value, with the Command and StartDirectory behavior documented on those fields.

PasteBufferRequest configures one tmux paste-buffer operation. Its zero value pastes the top buffer, replaces linefeeds with tmux's default carriage-return separator, and uses the version's default control-character handling. Pointer values are copied before I/O and must not be mutated concurrently.

WaitForTextRequest configures Pane.WaitForText.

SetPlanOptionRequest names one tmux option write for Plan.SetOption. Its zero value is invalid, because Name is required.

PromptHistoryRequest selects one prompt-history class. A zero request selects every class.

SetBufferRequest configures storing data in a tmux paste buffer. Its zero value writes an empty most-recent buffer; nil Name selects that buffer while a pointer to an empty name is explicit.

SaveBufferRequest configures writing a tmux paste buffer to a file. Its zero value is invalid because Path is required; nil Name selects the most-recent buffer and a pointer to an empty name is explicit.

LoadBufferRequest configures loading a file into a tmux paste buffer. Its zero value is invalid because Path is required; nil Name lets tmux allocate a buffer and a pointer to an empty name is explicit.

ListBuffersRequest configures tmux's live paste-buffer listing. Its zero value requests tmux's default output; nil Format and Filter omit their flags, whereas pointers to empty strings are explicit expressions.

RunShellRequest configures a command executed by tmux's run-shell command. Its zero value is invalid because Command is required. Pointer fields distinguish omitted flags from explicit empty arguments; RunShell copies Delay, StartDirectory, and Args before invoking tmux.

WaitForRequest configures a wait, signal, lock, or unlock operation. Its zero value waits on the required nonempty Channel.

IfShellRequest configures conditional execution of a tmux command. Its zero value is invalid because ShellCommand and ThenCommand are required; nil ElseCommand omits the failure branch while a pointer to an empty string is explicit.

SourceFileRequest configures loading or parsing a tmux configuration file. Its zero value is invalid because Path is required; SourceFile expands only the current user's ~ forms and copies no caller-owned mutable input.

ConfirmBeforeRequest configures a background tmux confirmation prompt. Its zero value is invalid because Command is required. Nil pointer fields omit their flags while explicit empty strings are passed to tmux; ConfirmKey must be one printable ASCII character.

CommandPromptRequest configures a background tmux command prompt. Its zero value is invalid because Template is required; nil pointer fields omit flags while explicit empty values are passed to tmux.

DisplayMenuRequest configures one tmux popup menu. Position and style strings retain tmux's format and symbolic-position languages verbatim. Its zero value is invalid because Items is required. All pointer fields omit their flags when nil and retain explicit empty strings; DisplayMenu copies Items before calling tmux. TargetPane and TargetClient are independent but must be stable identities when present.

BindKeyRequest configures one tmux key binding. Its zero value is invalid because Key is required; nil KeyTable and Note omit their flags while pointers to empty strings are explicit.

UnbindKeyRequest selects one key or an entire key table to unbind. Exactly one of Key and AllKeys must be set.

ListKeysRequest configures raw key-binding output. Its zero value selects tmux's default table and format; nil fields omit flags while explicit empty pointers are passed to tmux.

ListCommandsRequest optionally limits output to one tmux command or alias. Nil CommandName lists all commands; a pointer to an empty name is explicit.

ShowMessagesRequest selects the target and server information to print. Terminals and Jobs are independent and may both be enabled.

SelectLayoutRequest selects one layout operation. Its zero value reapplies the last preset layout. Layout, Spread, Next, and Previous are mutually exclusive and are validated before execution; an empty Layout is omitted rather than passed explicitly. The request contains no retained caller-owned storage and is supported on tmux 3.3a or later.

RespawnRequest configures restarting a window's or pane's process on every supported tmux. Its zero value reuses the stored command and directory and requires the target process to be inactive. Nil pointer fields omit their options; nonnil pointers are explicit, including empty strings. There are no mutually exclusive fields. Arguments and environment entries are validated before execution.

ErrInvalidCaptureRequest identifies a capture request that cannot be represented safely as tmux arguments.

ErrInvalidRequest identifies lifecycle options rejected before execution.

ServerAccessRequest configures tmux server access control. Its zero value is invalid: List or exactly one nonempty Allow or Deny is required. Allow and Deny, and ReadOnly and Write, are mutually exclusive; nil pointers omit their selectors while explicit empty users are rejected. List selects the returned-list path, but compatible selector and mode flags are still sent to tmux rather than ignored.

ErrInvalidServerCommandRequest identifies a server command request that cannot be represented safely as tmux arguments.

SessionKillRequest configures kill-session on tmux 3.3a or later. Its zero value destroys the receiver session. AllExcept destroys other sessions instead, while ClearAlerts is non-destructive. AllExcept, ClearAlerts, and Group are mutually exclusive because tmux applies a hidden precedence when more than one mode is supplied; the package rejects those combinations before execution. Group's compatibility behavior is documented on that field.

AttachSessionRequest selects a session name or tmux target pattern and configures a blocking terminal attachment. An empty Target lets tmux choose.

HasSessionRequest selects exact or tmux-pattern session matching on every supported tmux. Its zero value is invalid because Target is required.

NewSessionRequest configures session creation. Server.NewSession creates a detached session; Server.NewSessionConnection also acquires an owned control connection. Its zero value uses tmux defaults. Width and Height are either zero or 1 through 65535; KillExisting requires Name. KillExisting may remove a session before a later creation failure.

KillWindowRequest selects a window for Session.KillWindow on tmux 3.3a or later. A zero request kills the receiver session's current window, and Index is scoped to that session. Target is unrestricted tmux target syntax and may select a window in another session. Target and Index are mutually exclusive and are checked before execution. Pointer values are read during the call and are not retained; callers must not mutate them concurrently. A nil pointer omits its selector, while a nonnil pointer is explicit even when Target points to an empty string.

FindWindowRequest configures the interactive window search chooser. Match is a tmux search operand, not a shell command. The zero value searches with an empty glob using tmux's default name, title, and visible-content scopes.

SelectWindowRequest selects one winlink in a Session on tmux 3.3a or later. Its zero value is invalid: exactly one of WindowID and Index is required. That mutual exclusion, stable-ID syntax, and a nonnegative Index are validated before execution. Index is read during the call and is not retained; nil omits it, a nonnil pointer is explicit, and callers must not mutate it concurrently.

NewWindowRequest configures window creation on tmux 3.3a or later. Its zero value uses inherited defaults; placement behavior depends on the receiver. Session.NewWindow uses tmux's next free index. Window.NewWindow instead targets the receiver's occupied index and normally returns a command error; KillExisting may replace it. Window.NewWindow rejects Index. SelectExisting may run name-expansion probes before creation.

LinkWindowRequest configures linking a window into another session on every supported tmux. Its zero value is invalid because TargetSession is required. Nil TargetIndex asks tmux for a destination index; a nonnil value is explicit and must be nonnegative. After and Before are mutually exclusive and are rejected before execution. TargetIndex is read during the call and is not retained; callers must not mutate it concurrently.

UnlinkWindowRequest configures unlinking one exact winlink on tmux 3.3a or later. Its zero value removes the link only when the stable window has another link. The request contains no retained caller-owned storage and has no invalid field combinations.

MoveWindowRequest configures moving one exact winlink on tmux 3.3a or later. Its zero value moves the receiver within its current session to a tmux-chosen index and lets the moved winlink become current. Nil TargetIndex asks tmux for that index; a nonnil value is explicit and must be nonnegative. After and Before are mutually exclusive. Renumber is a standalone mode mutually exclusive with TargetIndex, After, Before, NoSelect, and KillTarget. Invalid combinations are rejected before execution. TargetIndex is read during the call and is not retained; callers must not mutate it concurrently.

SwapWindowRequest configures swapping the receiver with one exact winlink on tmux 3.3a or later. Its zero value is invalid because Target must be a complete Window handle. The endpoints must be proven to share a daemon through connection state or the same nonempty SocketPath; matching socket names alone are insufficient. Validation completes before execution.

WindowSelectPaneRequest selects either one exact pane or one relative pane. Its zero value is invalid: exactly one of Target and Direction is required. Target must be a complete pane handle in the receiver's exact winlink and must be proven to share a daemon through connection state or the same nonempty SocketPath; matching socket names alone are insufficient. Invalid values are rejected before execution.

RotateWindowRequest configures rotate-window. Its zero value uses tmux's default rotation; enum validation happens before execution.

ResizeWindowRequest selects one directional, manual, expand, or shrink operation. Height and Width may be set together. A zero request asks tmux to reapply the current manual size. Direction requires a positive Adjustment; that pair, dimensions, Expand, and Shrink are mutually exclusive and are validated before execution. Zero Adjustment, Height, and Width omit their modes; nonzero values must be positive. The request is supported on every supported tmux.

PaneDisplayMessageRequest adds the pane-only update behavior to the common display-message options.

CapturePaneRequest configures pane capture. Its zero value captures the visible screen with tmux's default text handling. Version-gated flags follow UnsupportedPolicy. tmux.CaptureBoundary selects the start of history for Start and the end of the visible pane for End.

NewPaneRequest configures a floating pane and requires tmux 3.7 or later. Its zero value creates a detached floating pane with tmux's default size, position, styles, and command. Nil pointer fields omit their options; nonnil pointers are explicit, including empty style or message strings. Width and Height must be nonnegative. Empty and Command are mutually exclusive. Unsupported tmux versions return VersionTooLowError rather than omitting fields.

SplitPaneRequest configures tiled pane creation on tmux 3.3a or later. Its zero value creates a detached pane below the exact target with tmux's default size and command. Nil pointer fields omit their options; nonnil pointers are explicit, including empty style or message strings. Size and Percentage are mutually exclusive. Invalid values are rejected before tmux is mutated.

ResizePaneRequest selects one resize mode. Direction with Adjustment, dimensions, Zoom, Mouse, and TrimBelow are mutually exclusive modes; Height and Width may be set together. Its zero value sends a bare tmux resize-pane command rather than selecting a mode. When Direction is tmux.PaneResizeDirectionNone, Adjustment must be zero.

DisplayPanesRequest configures pane-number display for tmux's current client and does not inherit the Pane target. Duration is read during the call, not retained, and must not be mutated concurrently.

PipePaneRequest configures a pane pipe. Its flags may be combined. Command is copied before I/O and must not be mutated concurrently.

MovePaneRequest configures move-pane on tmux 3.3a or later. Its zero value is invalid: exactly one complete TargetPane or TargetWindow handle is required. Cross-object handles must be proven to share a daemon through connection state or the same nonempty SocketPath; matching socket names alone are insufficient. Size and Percentage are mutually exclusive. Invalid enum, target, size, and percentage values are rejected before execution.

JoinPaneRequest configures join-pane with the same target, cross-daemon, sizing, validation, and pointer-ownership rules as MovePaneRequest.

BreakPaneRequest configures break-pane on tmux 3.3a or later. Its zero value moves the receiver to a detached new window with tmux's default name. Exact tmux 3.7 requires an explicit Name for the repair in Pane.BreakPane. Name is validated before the version probe.

SwapPaneRequest configures swapping with an exact or adjacent pane on every supported tmux. Its zero value is invalid: exactly one complete Target or Direction is required. An explicit Target must differ from the receiver and must be proven to share a daemon through connection state or the same nonempty SocketPath; matching socket names alone are insufficient. Invalid choices are rejected before execution.

PaneSelectRequest configures select-pane for one exact receiver. Closed enums prevent conflicting direction, mark, and input flags. Its zero value selects the receiver. Mark rejects every other option. Input rejects Direction and KeepZoom because changing input does not select a pane. These combinations and enum ranges are validated before execution.

LastPaneRequest configures last-pane on tmux 3.3a or later. Its zero value selects the previously active pane. Input and KeepZoom are mutually exclusive and are validated before execution; an Input mode changes the previous pane's input state without selecting it.

RefreshClientRequest configures refreshing one tmux client. Its zero value refreshes tmux's current client; a zero TargetClient omits -t.

DetachClientRequest configures detaching one tmux client. Its zero value detaches tmux's current client; nil fields omit their flags while an empty ShellCommand pointer is explicit.

DetachAllClientsRequest configures detaching every client except one. Its zero value keeps tmux's current client; nil fields omit their flags.

ColorError reports an unsupported color mode. It matches ErrUnknownColor through errors.Is; callers can recover Mode with errors.As.

CommandError reports a completed failed high-level tmux operation. It matches ErrCommand through errors.Is; callers can recover its fields with errors.As. Generic library operations retain an owned copy of the completed command and output so tmux diagnostics remain available. Operations whose primary payload may contain secrets return an exit-code-only result instead. Callers must treat retained argv and output as potentially sensitive.

ComplexOptionDecodeError identifies one malformed sparse-array entry without retaining its raw value.

ControlNotificationError reports where a control-mode notification failed validation without retaining or disclosing the notification contents. Callers can use errors.Is with Category or errors.As to inspect its secret-safe location metadata. Category is ErrMalformedControlNotification or ErrUnknownControlNotification.

ControlNotificationOverflowError reports the backlog limit and the record that would have crossed it. The queued prefix remains available first.

ControlProtocolError reports a control-stream state violation without retaining or disclosing command output or notification contents. It matches ErrControlProtocol through errors.Is.

EnvironmentNameError reports a name that tmux cannot store.

EnvironmentValueError reports a value that cannot round-trip through show-environment. It intentionally does not retain or print the environment value.

EnvironmentDecodeError reports one malformed show-environment record. It never retains the record because environment output may contain secrets.

FormatDecodeError identifies a malformed escaped tmux format record. It matches ErrMalformedFormatOutput through errors.Is; callers can recover its location fields with errors.As. Library-created errors do not retain decoded record values, which may contain caller data.

FromEnvError reports which tmux discovery variable was missing or malformed. It never retains or prints the variable's value.

OptionDecodeError reports a malformed recognized record without retaining its value. It matches ErrMalformedOptionOutput through errors.Is; callers can recover Record and Reason with errors.As. Record is the zero-based physical output line.

OptionValueError reports a rejected typed option value without retaining or rendering that value. It matches ErrInvalidOptionValue and ErrOption.

OptionError reports a completed high-level option or hook failure. It matches ErrOption and a specific option sentinel through errors.Is; callers can recover its fields with errors.As. Library-created errors retain only Result.ExitCode. Error never renders command output because option values and hook commands may be secret; callers may construct exported values with other contents.

CaptureRequestError reports a CapturePaneRequest field that cannot be represented as a tmux capture-pane argument. It matches ErrInvalidCaptureRequest through errors.Is and is available through errors.As.

PlanError reports a plan this package refused before sending anything to tmux. It matches ErrPlan through errors.Is; callers can recover Step and Reason with errors.As.

VersionQueryError reports an unsuccessful tmux version probe. It matches ErrVersionQuery through errors.Is; callers can recover its fields with errors.As. Library-created errors retain only the exit code; command arguments and output are omitted, although callers may construct values with other contents.

VersionTooLowError reports the installed and required tmux feature levels. It matches ErrVersionTooLow through errors.Is; callers can recover its fields with errors.As.

SnapshotDecodeError identifies one malformed decoded list row. It matches ErrMalformedSnapshot through errors.Is; callers can recover its redacted location fields with errors.As.

SnapshotLookupError reports the cardinality of an unsuccessful point lookup. It matches ErrNotFound or ErrSnapshotAmbiguous through errors.Is; callers can recover its target and count with errors.As.

TargetError reports a malformed stable identifier before command execution. It matches ErrInvalidTarget through errors.Is; callers can recover Object and Target with errors.As.

MissingTargetError reports an operation attempted on a zero-value model identity. It matches ErrMissingTarget through errors.Is; callers can recover Object with errors.As.

VersionError reports a tmux version token that cannot be parsed. It matches ErrInvalidVersion through errors.Is; callers can recover Token with errors.As.

ErrAmbiguousOption identifies tmux's case-sensitive ambiguous-option diagnostic.

ErrCommand identifies a failed high-level tmux command. It is matched by errors.Is for CommandError.

ErrConnectionRequiresProcess identifies an operation refused because a terminal Connection cannot start a tmux process outside its owned lanes.

ErrControlClosed identifies an operation attempted after a control client began closing or lost its protocol stream. A notification read after either end matches it, so one errors.Is check covers a stream the caller closed and one tmux ended; ErrControlStreamLost tells the second apart.

ErrControlNotificationOverflow identifies a watcher that did not consume notifications before its bounded backlog filled. Reads return the notifications queued before the overflow and then this error; everything tmux sent after it is dropped, so the stream is no longer a faithful record even though the process is still running.

ErrControlProtocol identifies malformed tmux control-mode framing.

ErrControlReplyCount identifies a call to ControlClient.Cmd for a command that produced zero or multiple reply frames.

ErrControlStreamLost identifies a ControlClient.NextNotification stream that ended before the caller asked to close it, distinct from the clean end an explicit Close or CloseContext produces. Such an error also matches ErrControlClosed. It is most often the underlying tmux client process exiting because the server it was attached to did.

ErrDaemonReplaced identifies an operation refused because the tmux server instance that produced a materialized value no longer occupies its socket.

ErrDuplicateSparseIndex identifies repeated constructor indices.

ErrInvalidCommandOutput identifies malformed identity output from tmux.

ErrInvalidEnvironmentName identifies a name tmux cannot store.

ErrInvalidEnvironmentValue identifies a value the line-oriented read API cannot round-trip.

ErrInvalidFilter reports a malformed or impossible generated filter. Filter validation, lookup parsing, predicates, and JSON methods wrap this error.

ErrInvalidOption identifies tmux's case-sensitive invalid-option diagnostic.

ErrInvalidOptionValue identifies a typed option value outside its active tmux-version domain.

ErrInvalidSparseIndex identifies a negative or overflowing sparse index.

ErrInvalidTarget identifies a malformed stable tmux identifier. It is matched by errors.Is for TargetError.

ErrInvalidVersion identifies malformed tmux version tokens. It is matched by errors.Is for VersionError.

ErrInvalidWaitForText identifies a WaitForTextRequest that cannot be waited on. It is matched by errors.Is.

ErrMalformedComplexOption identifies an invalid entry in a parsed complex option.

ErrMalformedControlNotification identifies a structurally invalid control-mode notification.

ErrMalformedEnvironment identifies output that is not a tmux environment entry.

ErrMalformedFormatOutput identifies invalid escaped tmux format output. It is matched by errors.Is for FormatDecodeError.

ErrMalformedOptionOutput identifies a recognized option or hook record that cannot be decoded without ambiguity. It is matched by errors.Is for OptionDecodeError.

ErrMalformedSnapshot identifies invalid required fields in decoded rows. SnapshotDecodeError matches it through errors.Is.

ErrMissingSubcommand identifies an object command with no tmux subcommand.

ErrMissingTarget identifies an operation on a zero-value model identity.

ErrMultipleMatches identifies an ExactlyOne or ExactlyOneSeq query with more than one matching value. The queries stop when they find the second match. Cardinality errors can be checked with errors.Is.

ErrNoMatch identifies an ExactlyOne or ExactlyOneSeq query with no matching value. Cardinality errors can be checked with errors.Is.

ErrNotFound identifies an operation naming a tmux object that does not exist. A lookup that found nothing matches it, and so does a command tmux refused because the target it named was gone — the same condition reached from either direction. SnapshotLookupError and CommandError match it through errors.Is.

ErrNotInsideTmux identifies missing or malformed tmux discovery variables.

ErrOption identifies a failed high-level option or hook operation. It is matched by errors.Is for OptionError.

ErrOptionTarget identifies an option or hook operation whose target did not resolve, which is the failure an unknown name is most easily mistaken for. Classifying it discloses nothing that redaction protects: which kind of failure occurred is not one of the values or hook commands an option error withholds.

ErrOutcomeUnknown identifies a command whose write began but whose reply boundary was not observed. The operation may have changed tmux.

ErrOutcomeUnrecorded reports that a command's pane is dead while tmux has not recorded how the command ended, which it does by reaping the command's process. tmux is known to leave a pane in that state indefinitely, so this is reported rather than waited out, and rather than passed off as a zero exit status that would call a failed command successful.

ErrPlan identifies a plan that cannot run as recorded. It is matched by errors.Is for PlanError.

ErrPollCondition identifies a poll whose condition was nil. It is matched by errors.Is.

ErrSnapshotAmbiguous identifies a point lookup with multiple matching views. SnapshotLookupError matches it through errors.Is.

ErrUnknownColor identifies an unsupported tmux color mode. It is matched by errors.Is for ColorError.

ErrUnknownControlNotification identifies a well-framed notification kind outside the pinned control-mode vocabulary.

ErrUnknownOption identifies tmux's case-sensitive unknown-option diagnostic.

ErrVersionCheckFailed identifies a failure of the check that precedes every ordinary command, a refusal included: an ErrVersionTooLow from Cmd matches it too. The check is a read-only probe, so a command that fails with it was never sent, whatever else the error matches.

ErrVersionQuery identifies a tmux version probe that produced no usable version. It is matched by errors.Is for VersionQueryError.

ErrVersionTooLow identifies a tmux version below a required feature level. It is matched by errors.Is for VersionTooLowError.

ServerCommandRequestError reports a locally rejected server command request field. Callers can use errors.Is with ErrInvalidServerCommandRequest or errors.As to inspect it. Value is redacted only when that field's validator requests redaction.

ErrInvalidServer identifies an operation on an uninitialized Server.

ErrInvalidServerOptions identifies a value that fails ServerOptions validation. Executable lookup and working-directory failures retain their own error identities.

ErrNoServer identifies a command that no tmux server answered. A CommandError may match both ErrNoServer and ErrCommand. tmux cannot reliably distinguish an absent or unreachable server from one that exited during the command.

ErrSessionExists identifies a named session that was not replaced.

PaneEndedError reports that Pane.WaitForText stopped because the pane or its server ended first. The text read before then is in the returned PaneTextWait.

ErrPaneEnded identifies a wait that stopped because the pane or its server ended before the text appeared. It is matched by errors.Is for PaneEndedError.

ErrPaneObservationLost identifies a pane observation whose control client can no longer receive every byte after its baseline. Stream failures that wrap it also preserve their underlying cause.

ColorMode selects a tmux color-capability override for ServerOptions.

CommandResult contains one completed tmux invocation. Server.Cmd returns it even when tmux exits nonzero. Library operations clone its slices before returning it, so the caller owns Command, Stdout, RawStdout, and Stderr.

TerminalOverrideValueKind identifies one closed terminal capability value form.

ConnectionOptions configures the control-mode lanes owned by a Connection.

ControlCommandResult is one completed control-mode command frame. A failed tmux command remains result data through Failed; local, protocol, transport, and context failures are returned separately by Connection.Call, ControlClient.Cmd, and ControlClient.Call. All slices are owned by the caller.

SetEnvironmentOptions controls tmux's value expansion and visibility flags. Its zero value stores Value literally and exposes it to child processes.

SetHooksOptions controls a bulk hook replacement. Its zero value preserves existing indices before applying the supplied sparse values.

SetHooksResult reports only side effects confirmed before return.

NotificationOptions configures which notifications a stream receives. The zero value retains notifications other than pane output.

ActivityAction is a typed value for the "activity-action" tmux option. Its zero value is invalid.

BellAction is a typed value for the "bell-action" tmux option. Its zero value is invalid.

ClockModeStyle is a typed value for the "clock-mode-style" tmux option. Its zero value is invalid.

CursorStyle is a typed value for the "cursor-style" tmux option. Its zero value is invalid.

PromptCommandCursorStyle is a typed value for the "prompt-command-cursor-style" tmux option. Its zero value is invalid.

PromptCursorStyle is a typed value for the "prompt-cursor-style" tmux option. Its zero value is invalid.

SilenceAction is a typed value for the "silence-action" tmux option. Its zero value is invalid.

ControlNotificationKind identifies a tmux control-mode notification record. Its zero value is unknown and is not emitted by tmux. ParseControlNotification returns known values for the pinned wire vocabulary and rejects unknown notification records.

SetOptionOptions controls set-option mutation flags. Its zero value sends no optional mutation flags.

UnsetOptionOptions controls set-option unset behavior. Its zero value unsets only the selected option.

SetArrayResult reports confirmed progress from a typed sparse-array replacement. AppliedIndices is caller-owned and is non-nil whenever mutation was attempted.

PlanResult reports what running a Plan did, one entry per recorded operation, in the order they were recorded.

OpResult is what one operation in a Plan produced.

LoadBufferFromOptions configures streaming data into a tmux paste buffer. Its zero value lets tmux allocate a buffer; nil Name selects that allocation and a pointer to an empty name is explicit.

SaveBufferToOptions configures streaming a tmux paste buffer's contents out. Its zero value selects tmux's most-recent buffer; a pointer to an empty name is explicit.

WaitForMode selects one wait-for operation. The zero value waits until the channel is signaled.

RunOptions configures Session.Run and Session.Start. Its zero value runs the command in a window tmux names, in the session's default directory and environment, and removes that window once the command has finished.

RunResult reports how a command finished and what its terminal showed.

WarningKind identifies one closed class of nonfatal library warning.

ActivityActionAny selects "any".

ActivityActionCurrent selects "current".

ActivityActionNone selects "none".

ActivityActionOther selects "other".

BellActionAny selects "any".

BellActionCurrent selects "current".

BellActionNone selects "none".

BellActionOther selects "other".

ClockModeStyle12 selects "12".

ClockModeStyle12WithSeconds selects "12-with-seconds".

ClockModeStyle24 selects "24".

ClockModeStyle24WithSeconds selects "24-with-seconds".

Color256 requests tmux's 256-color capability mode.

ColorDefault preserves tmux's detected color capability.

ControlNotificationClientDetached identifies the %client-detached notification. Its wire grammar is %client-detached <client>. ParseControlNotification returns its arguments as client tail.

ControlNotificationClientSessionChanged identifies the %client-session-changed notification. Its wire grammar is %client-session-changed <client> <session ID> <session name>. ParseControlNotification returns its arguments as client, session ID, session name tail.

ControlNotificationConfigError identifies the %config-error notification, available since tmux 3.4. Its wire grammar is %config-error <text>. ParseControlNotification returns its arguments as text tail.

ControlNotificationContinue identifies the %continue notification. Its wire grammar is %continue <pane ID>. ParseControlNotification returns its arguments as pane ID.

ControlNotificationExit identifies the %exit notification. Its wire grammar is %exit or %exit <reason>. ParseControlNotification returns its arguments as reason tail.

ControlNotificationExtendedOutput identifies the %extended-output notification. Its wire grammar is %extended-output <pane ID> <age> { zero or more <reserved argument> } : <data>. ParseControlNotification returns its arguments as the prefix arguments, then zero or more reserved arguments, then the data tail; the prefix arguments are pane ID, age. Its tail may be empty.

ControlNotificationLayoutChange identifies the %layout-change notification. Its wire grammar is %layout-change <window ID> <layout> <visible layout> <flags>. ParseControlNotification returns its arguments as window ID, layout, visible layout, flags tail. Its tail may be empty.

ControlNotificationMessage identifies the %message notification, available since tmux 3.4. Its wire grammar is %message <text>. ParseControlNotification returns its arguments as text tail. Its tail may be empty.

ControlNotificationOutput identifies the %output notification. Its wire grammar is %output <pane ID> <data>. ParseControlNotification returns its arguments as pane ID, data tail. Its tail may be empty.

ControlNotificationPaneModeChanged identifies the %pane-mode-changed notification. Its wire grammar is %pane-mode-changed <pane ID>. ParseControlNotification returns its arguments as pane ID.

ControlNotificationPasteBufferChanged identifies the %paste-buffer-changed notification, available since tmux 3.4. Its wire grammar is %paste-buffer-changed <name>. ParseControlNotification returns its arguments as name tail.

ControlNotificationPasteBufferDeleted identifies the %paste-buffer-deleted notification, available since tmux 3.4. Its wire grammar is %paste-buffer-deleted <name>. ParseControlNotification returns its arguments as name tail.

ControlNotificationPause identifies the %pause notification. Its wire grammar is %pause <pane ID>. ParseControlNotification returns its arguments as pane ID.

ControlNotificationSessionChanged identifies the %session-changed notification. Its wire grammar is %session-changed <session ID> <session name>. ParseControlNotification returns its arguments as session ID, session name tail.

ControlNotificationSessionRenamed identifies the %session-renamed notification. Its wire grammar is %session-renamed <session ID> <session name>. ParseControlNotification returns its arguments as session ID, session name tail.

ControlNotificationSessionsChanged identifies the %sessions-changed notification. Its wire grammar is %sessions-changed. ParseControlNotification returns its arguments as no arguments.

ControlNotificationSessionWindowChanged identifies the %session-window-changed notification. Its wire grammar is %session-window-changed <session ID> <window ID>. ParseControlNotification returns its arguments as session ID, window ID.

ControlNotificationSubscriptionChanged identifies the %subscription-changed notification. Its wire grammar is %subscription-changed <name> <session ID> <window ID> <window index> <pane ID> { zero or more <reserved argument> } : <value>. ParseControlNotification returns its arguments as the prefix arguments, then zero or more reserved arguments, then the value tail; the prefix arguments are name, session ID, window ID, window index, pane ID. Its tail may be empty.

ControlNotificationUnlinkedWindowAdd identifies the %unlinked-window-add notification. Its wire grammar is %unlinked-window-add <window ID>. ParseControlNotification returns its arguments as window ID.

ControlNotificationUnlinkedWindowClose identifies the %unlinked-window-close notification. Its wire grammar is %unlinked-window-close <window ID>. ParseControlNotification returns its arguments as window ID.

ControlNotificationUnlinkedWindowRenamed identifies the %unlinked-window-renamed notification. Its wire grammar is %unlinked-window-renamed <window ID> <name>. ParseControlNotification returns its arguments as window ID, name tail.

ControlNotificationWindowAdd identifies the %window-add notification. Its wire grammar is %window-add <window ID>. ParseControlNotification returns its arguments as window ID.

ControlNotificationWindowClose identifies the %window-close notification. Its wire grammar is %window-close <window ID>. ParseControlNotification returns its arguments as window ID.

ControlNotificationWindowPaneChanged identifies the %window-pane-changed notification. Its wire grammar is %window-pane-changed <window ID> <pane ID>. ParseControlNotification returns its arguments as window ID, pane ID.

ControlNotificationWindowRenamed identifies the %window-renamed notification. Its wire grammar is %window-renamed <window ID> <name>. ParseControlNotification returns its arguments as window ID, name tail.

CursorStyleBar selects "bar".

CursorStyleBlinkingBar selects "blinking-bar".

CursorStyleBlinkingBlock selects "blinking-block".

CursorStyleBlinkingUnderline selects "blinking-underline".

CursorStyleBlock selects "block".

CursorStyleDefault selects "default".

CursorStyleUnderline selects "underline".

PromptCommandCursorStyleBar selects "bar".

PromptCommandCursorStyleBlinkingBar selects "blinking-bar".

PromptCommandCursorStyleBlinkingBlock selects "blinking-block".

PromptCommandCursorStyleBlinkingUnderline selects "blinking-underline".

PromptCommandCursorStyleBlock selects "block".

PromptCommandCursorStyleDefault selects "default".

PromptCommandCursorStyleUnderline selects "underline".

PromptCursorStyleBar selects "bar".

PromptCursorStyleBlinkingBar selects "blinking-bar".

PromptCursorStyleBlinkingBlock selects "blinking-block".

PromptCursorStyleBlinkingUnderline selects "blinking-underline".

PromptCursorStyleBlock selects "block".

PromptCursorStyleDefault selects "default".

PromptCursorStyleUnderline selects "underline".

SilenceActionAny selects "any".

SilenceActionCurrent selects "current".

SilenceActionNone selects "none".

SilenceActionOther selects "other".

TerminalOverrideValueFlag identifies a capability without an assigned value.

TerminalOverrideValueInteger identifies an unsigned decimal integer.

TerminalOverrideValueText identifies an assigned non-integer string.

WaitForModeLock acquires Channel's tmux mutex, queuing behind another locker if it is already held.

WaitForModeSignal signals Channel and wakes waiters.

WaitForModeUnlock releases Channel's tmux mutex.

WaitForModeWait waits until another client signals Channel.

WarningCommandStderr reports stderr from a completed command whose Python API treats the diagnostic as nonfatal.

WarningUnsupportedFeature reports a requested feature omitted because the connected tmux binary is too old.

ServerOptions configures a Server without starting tmux. NewServer snapshots the effective environment, working directory, and executable; callers retain ownership of every supplied value.

AttachSessionOptions configures terminal ownership and attach behavior shared by server- and session-scoped attachment. Nil StartDirectory omits its flag and a nonnil empty string is explicit; ClientFlags is copied. The Stdin, Stdout, and Stderr pointers are retained for the attach call and are never owned or closed by this package.

WindowSwapResult contains both original stable window identities in their post-swap exact winlink views. Its zero value contains no usable endpoints.

PaneSwapResult contains original stable pane identities in their post-swap exact linked-pane views. Its zero value contains no usable endpoints. Target is zero for a directional swap because tmux does not report the adjacent pane identity.

PaneMarkMode changes tmux's server-wide marked pane on tmux 3.3a or later. Its zero value leaves the mark unchanged.

PaneInputMode changes whether a pane accepts input on tmux 3.3a or later. Its zero value leaves input state unchanged.

PaneInputDisable disables input without selecting the target pane.

PaneInputEnable enables input without selecting the target pane.

PaneInputUnchanged leaves the target pane's input state unchanged.

PaneMarkClear clears the server-wide marked pane without selecting the target.

PaneMarkSet makes the target the server-wide marked pane without selecting it.

PaneMarkUnchanged leaves the server-wide marked pane unchanged.

ControlMode is an attached tmux control client for real-tmux tests. It owns one stdout reader and a temporary-file spool, which preserves unread protocol output until ControlMode.Close releases it. Instances come from NewControlMode; do not construct them directly or read concurrently.

ServerOptions configures a harness-owned tmux.Server. All inputs are copied before filesystem or process operations, so callers retain ownership.

PTYProcess is a test subprocess that owns an isolated controlling terminal and a memory-backed transcript. It comes from StartPTYProcess. Output may be read concurrently through PTYProcess.Output; writes are serialized.

ScriptedCommand is one answer a scripted tmux gives. The first matching entry wins, and an invocation nothing matches exits 1 saying so.

MaximumTestedVersion is the newest numbered tmux feature level covered by this package's tests, and the level ParseVersion gives a bare master build.

ShellPrompt is the prompt drawn when ServerOptions.FixedShell is enabled.

SuiteRootTagVariable names the environment variable that tags a suite's temporary root. go test runs packages in parallel and every suite among them creates a root beside the others, so a test spawning a child suite sets this to tell its child's root from theirs.

TemporaryNamePrefix prefixes names generated by NewSession and NewWindow.

Main runs the one-call package lifecycle for tmuxtest. It prepares short temporary paths, redirects suiteEnvironment into them, clears the variables that select a server outside them, runs m, cleans registered servers, restores the environment, and returns the final status. It returns 2 without running m when the environment would still reach a server outside the suite.

NewControlMode starts a ControlMode attached to session and registers cleanup with t. It requires an explicitly configured process environment and validates that session belongs to server. The client pins the server's frozen effective socket path. Validation or startup failures call testing.TB.Fatal. Releases below tmux 3.7 skip this positive fixture before control startup. ctx bounds startup and registration only, not the returned client's lifetime.

NewServer starts an isolated tmux.Server with a session named "work". Startup uses ctx and the harness timeout, whichever ends first. It registers bounded cleanup with t; setup failures call testing.TB.Fatal. The context does not govern later server cleanup or daemon lifetime.

NewServerWithOptions prepares an isolated harness-owned tmux.Server from options. Initial startup uses ctx and the harness timeout, whichever ends first. The daemon starts only when ServerOptions.InitialSession is non-nil or a later tmux command starts it. It registers bounded cleanup with t; setup failures call testing.TB.Fatal. The context does not govern later cleanup or daemon lifetime.

NewSession creates a test-owned tmux.Session and registers cleanup against its stable ID. An empty tmux.NewSessionRequest.Name receives a collision-checked temporary name. The request and referenced values are copied before tmux is called, and setup failures call testing.TB.Fatal. Cleanup belongs to t rather than ctx and continues to target the session if it is renamed.

NewWindow creates a test-owned tmux.Window and registers cleanup against its stable ID. A nil tmux.NewWindowRequest.Name receives a collision-checked temporary name; an empty non-nil name remains explicit. The request and referenced values are copied before tmux is called, and setup failures call testing.TB.Fatal. Cleanup belongs to t rather than ctx and follows the window if it is moved.

RequireVersion skips a feature's positive test when the selected daemon, or the executable that would start it, is older than minimum. Other version-check failures fail the test. Refusal tests should call the operation directly.

RunInPane creates an isolated pane, waits for its startup-file-free POSIX shell, and submits command with Type. It does not wait for command to start or finish. Resources belong to t; setup failures call testing.TB.Fatal. Use NewServerWithOptions for custom topology or configuration.

Screen returns the pane's visible lines, top to bottom, with tmux's trailing blank lines removed.

ScriptedTmux writes an executable that answers tmux invocations from script and returns its absolute path, for tmux.ServerOptions.Binary. It is how a test drives code that uses this package without a tmux to drive:

StartPTYProcess starts binary with a harness-owned controlling terminal and registers bounded cleanup with t. Its start context owns the child lifetime: canceling ctx terminates the child. Arguments and environment are copied. A nil environment inherits the current process environment; a non-nil empty environment remains empty. binary runs directly without a shell. The PTY backend is supported on Linux only; unsupported platforms call testing.TB.Fatal. Setup failures also call testing.TB.Fatal.

Type sends command to the pane and submits it, as a person at the keyboard would.

TypeAndWait sends command to the pane and blocks until it has finished.

WaitFor checks condition serially and immediately, then after each interval, until it succeeds, returns an error, or ctx ends. It validates interval, condition, and ctx in that order: interval must be positive, condition must be non-nil, and an already-ended context prevents every check. Condition errors and context errors are returned unchanged. A running condition receives ctx and must observe it itself; WaitFor cannot interrupt the condition.

WaitForLine blocks until some line of the pane's screen is exactly line. The echo of a typed command is a line too; see WaitForText.

WaitForScreen blocks until the pane's screen satisfies match.

WaitForShellReady blocks until the pane first shows output. With ServerOptions.FixedShell, that expected first output is the harness prompt and serves as readiness evidence; custom shell startup output may not.

WaitForText blocks until some line of the pane's screen contains text.

TreeSortOrder selects one initial tmux choose-tree ordering. Its zero value leaves tmux's configured ordering unchanged.

PromptType selects one closed tmux prompt-history class. The zero value selects all prompt types.

MenuItem is one display-menu entry. Its zero value is a separator. A named item always contributes its name, key, and command to tmux, including empty key or command strings.

SocketSource names what chose the socket a Server uses.

SocketSelection describes the Unix filesystem endpoint selected by a Server. It does not report whether a server is listening there or whether tmux would accept the named-socket directory's ownership and permissions.

SparseEntry is one indexed SparseArray value.

SparseArray stores values at sorted, nonnegative indices. Its zero value is an empty array. Constructors and functional updates own their entry slices; copies of reference-bearing T values remain shallow.

UnsupportedPolicy selects what a request does when it needs an optional tmux capability the running server does not have.

Warning describes one nonfatal compatibility decision delivered to a WarningHandler.

WarningHandler receives warnings synchronously on the caller goroutine:

DegradeUnsupported omits the capability, runs the reduced command, and reports the decision to ServerOptions.WarningHandler as a WarningUnsupportedFeature.

FailUnsupported refuses a request naming a capability the running tmux does not have, with a VersionTooLowError naming the subcommand and the capability. It is the zero value.

PromptTypeAll selects every prompt-history class and omits -T.

PromptTypeCommand selects command-prompt history.

PromptTypeSearch selects search-prompt history.

PromptTypeTarget selects target-prompt history.

PromptTypeWindowTarget selects window-target-prompt history.

SocketSourceEnvironmentName means LIBTMUX_SOCKET chose the socket.

SocketSourceEnvironmentPath means LIBTMUX_SOCKET_PATH chose the socket.

SocketSourceExplicit means the caller named the socket, through ServerOptions, Server.WithSocketPath, or NewServerFromEnv.

SocketSourceTmux means nothing chose a socket, so tmux chooses the server: the one TMUX names, otherwise its default socket.

TreeSortDefault leaves the configured choose-tree ordering unchanged.

TreeSortIndex orders tree entries by index.

TreeSortName orders tree entries by name.

TreeSortSize orders tree entries by size.

TreeSortTime orders tree entries by activity time.

NewSparseArray builds an array from entries, sorting them by index. It returns errors matching ErrInvalidSparseIndex or ErrDuplicateSparseIndex for negative, overflowing, or duplicate indices.

Poll checks condition immediately and then after each interval, until it reports true, returns an error, or ctx ends.