Go 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 version-cache coordination; only the documented concurrent operations are safe to share.

SessionID is tmux's stable session identifier, including its $ sigil. The zero value 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.

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

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

Window is one window in a workspace.

PaneDirection selects where a tiled pane is created or moved on tmux 3.2a 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.

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

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

Pane is one pane in a window. YAML accepts either a bare command string or a mapping, so "echo hello" and {shell_command: echo hello} are equivalent.

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.

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.

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

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.

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. On tmux 3.6 or later, destroying its initial session moves the clients to another session when one exists; the retained Session value keeps its original identity.

Command is one command to run in a pane. YAML accepts either a bare string or a mapping, so "echo hi" and {cmd: echo hi, sleep_before: 2} are both commands.

NotificationStream owns one observation-only control client attached to a session. It yields tmux notifications in wire order and must be closed. Before tmux 3.6, destroying the attached session follows that session's detach-on-destroy policy and may end the stream.

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.

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.

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

OpStatus reports what became of one operation in a plan.

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.

Workspace is one tmuxp-style session description.

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.

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.

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.2a or later.

RespawnRequest configures restarting a window's or pane's process on tmux 3.2a or later. 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.

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.

SessionKillRequest configures kill-session on tmux 3.2a 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 tmux 3.2a or later. Its zero value is invalid because Target is required.

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.

LinkWindowRequest configures linking a window into another session on tmux 3.2a or later. 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.2a 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.2a 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.2a 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 tmux 3.2a or later.

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

SplitPaneRequest configures tiled pane creation on tmux 3.2a 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.

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.2a 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.

SwapPaneRequest configures swapping with an exact or adjacent pane on tmux 3.2a or later. 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.2a 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.

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 -V 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 ErrSnapshotNotFound 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.

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

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.

TerminalOverrideValueKind identifies one closed terminal capability value form.

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.

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.

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

WarningKind identifies one closed class of nonfatal library warning.

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.2a or later. Its zero value leaves the mark unchanged.

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

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.

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.

WarningHandler receives warnings synchronously on the caller goroutine:

Bool accepts YAML booleans and tmuxp's quoted spellings. It is exported so callers can construct optional *Bool fields.