Go API reference

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.

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.

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.

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 .

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

ControlClient is one attached tmux control-mode process. Create one with Server.OpenControl . Concurrent Cmd, Wait, and close calls are supported; exactly one caller may execute NextNotification at a time.

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

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.

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.

Ref addresses an existing object or one an earlier Plan step will create. This permits forward construction without tmux I/O. The zero Ref addresses nothing and makes a targeted operation fail validation.

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.