Go API

struct libtmux-go latest

Server

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

Source and package

Qualified name: tmux.Server
Package: tmux
Distribution: github.com/libtmux/libtmux-go/tmux
Source: tmux/server.go
Other languages: Perlclass Erlangmodule PowerShellcmdlet Juliastruct Elixirstruct Haskell Common Lisp PythonRubyLuaTypeScriptRustJavaC#C++SwiftKotlinScalaOCamltypealias F#module Clojurefunction

struct tmux.Server struct [source] ¶

Description#

NewServer resolves the executable, socket, and environment once and does not start tmux; creating the first session starts the daemon. A plain Server starts a tmux process for each command it sends, so discarding one leaves the daemon running; Server.Kill stops it. A Server from Connection.Server sends its commands over that connection's control lanes instead. Operations on the zero Server return ErrInvalidServer.

What is on here

Operations on one session, window, or pane live on Session, Window, and Pane, such as Session.NewWindow, Window.SplitPane, Pane.SendKeys, and Pane.Capture. This type holds what belongs to the server as a whole, in the groups below.

Connecting: Build a handle from a ServerOptions or from the TMUX variable; neither starts tmux. Of the two liveness checks, one answers false for an absent server and the other makes an absent server an error. A version minimum fails with ErrVersionTooLow, and a control-mode client, or a session created together with its Connection, needs tmux 3.7.; Build

NewServer
NewServerFromEnv

Liveness

IsAlive
CheckAlive

Version

Version
RefreshVersion
RequireVersion

Control mode

OpenControl
OpenNotifications
NewSessionConnection
ConnectionBound

Built from

SocketPath
SocketSelection
ConfigFile
Executable
ProcessEnvironment

Copies

WithSocketPath
WithProcessEnvironmentValue

Identity

Equal
String
Finding one thing: A lookup that finds nothing returns an error matching ErrNotFound, or ErrNoServer when no server is running. The existence check returns a bool instead, and a missing server counts as no session.; By ID

Session
Window
Pane

By name

SessionByName
Client

Exists

HasSession
Listing everything: Each listing returns one kind of record, and the window and pane listings cover every window link. Failures, including ErrNoServer, stay errors, so an outage does not read as an empty server. A Snapshot reads the sessions, windows, panes, and clients together, as sequential commands rather than one atomic transaction.; Records

Sessions
Windows
Panes
Clients

Together

Snapshot

Raw lines

ListClients
Querying things and getting around: The search methods pass a TmuxFilter to tmux, which drops the rows that do not match before any record exists. To filter in Go instead, apply a SessionFilter, WindowFilter, PaneFilter, or ClientFilter to a slice with tmuxq.Matching, or pass a predicate to tmuxq.Where, tmuxq.First, or tmuxq.ExactlyOne, which fails unless exactly one value matches. Records from a snapshot, and from the listings above, know their neighbors without querying tmux, but a record from a search, a lookup, or Server.NewSession carries no relations and reports false; the Resolve methods read live state for any record.; Search from the server

SearchSessions
SearchWindows
SearchPanes
SearchClients

Search below one record

Session.SearchWindows
Session.SearchPanes
Window.SearchPanes

Look up in a snapshot

Snapshot.SessionByID
Snapshot.WindowByID
Snapshot.PaneByID
Snapshot.ClientByName

Down

Session.Windows
Session.Panes
Window.Panes

Up

Pane.Window
Pane.Session
Window.Session

Across

Session.ActiveWindow
Session.ActivePane
Window.ActivePane
Client.AttachedSession

Live

Pane.ResolveWindow
Pane.ResolveSession
Window.ResolveSession
Session.ResolveActiveWindow
Session.ResolveActivePane
Window.ResolveActivePane
Changing things: A new session is detached and never changes client focus; the first one starts the daemon. A kill takes everything inside with it: one stops the daemon with all its sessions, windows, panes, and clients, and the other ends the session a tmux target selects, leaving pattern and prefix matching to tmux. Start starts the daemon without a session, so with tmux's exit-empty default it can exit before the next command.; NewSession
Kill
KillSession
Start
Options and hooks: Options read back as a typed ServerOptionValues, or one raw value by name, and a write by name reaches an option the typed setters do not cover. Each known option has a typed setter that ServerOptionValues pairs with its accessor, and an array option such as command-alias is replaced whole by a setter whose result reports the writes confirmed. The defaults that sessions and windows inherit, and the global hooks, sit on two scope handles rather than on Server itself.; Read

Options
RawOption

Write by name

SetOption
AppendOption
UnsetOption

Typed setters, for example

SetEscapeTime
SetExitEmpty
SetBufferLimit

Array setters, for example

SetCommandAlias
SetTerminalFeatures

Scopes

GlobalSessionScope
GlobalWindowScope

Session-scope hooks

GlobalSessionScope.Hooks
GlobalSessionScope.SetHook
GlobalSessionScope.AppendHook
GlobalSessionScope.UnsetHook
GlobalSessionScope.RunHook

Window-scope hooks

GlobalWindowScope.Hooks
GlobalWindowScope.SetHook
GlobalWindowScope.AppendHook
GlobalWindowScope.UnsetHook
GlobalWindowScope.RunHook
Everything else tmux keeps: Paste buffers read as lines or as exact bytes and load from a string, a file, or a stream; the stream forms return ErrConnectionRequiresProcess on a handle bound to a Connection, which loads and saves by path instead. A shell command's captured output needs tmux 3.5, and before tmux 3.8 abandoning a wait-for lock costs its channel one unlock. Layout validation checks each layout and its pane count before any mutation.; Buffers

ListBuffers
ShowBuffer
ShowBufferBytes
SetBuffer
LoadBuffer
LoadBufferFrom
SaveBuffer
SaveBufferTo
DeleteBuffer

Keys

BindKey
UnbindKey
ListKeys

Environment

ShowEnvironment
GetEnvironment
SetEnvironment
UnsetEnvironment
RemoveEnvironment

Configuration and layouts

SourceFile
ValidateLayouts

Shell

RunShell
IfShell

Channels

WaitFor

Messages and formats

ShowMessages
DisplayMessage

Prompt history

ShowPromptHistory
ClearPromptHistory

Commands and access

ListCommands
ServerAccess
Things that need a terminal: Menus, prompts, and confirmations draw on an attached client, and tmux refuses them without one. Attaching hands the caller's own terminal to a session and blocks until it detaches. Switching, detaching, locking, suspending, and refreshing a client act on a client, named or tmux's current one, and fail without one. Locking the server instead locks every attached client.; Draw

DisplayMenu
CommandPrompt
ConfirmBefore

Attach

AttachSession

Act on a client

SwitchClient
DetachClient
DetachAllClients
LockClient
SuspendClient
RefreshClient

Every client

LockServer

Anything tmux can do that is not here is reachable through Server.Cmd, which runs raw tmux arguments and returns a CommandResult; a completed nonzero exit is a result, not an error.

Examples#

Open a private server and create a session on it. Find that session, then read the server once and walk from a pane up to its window and session without another tmux command. A search asks tmux to filter instead. The temporary server is stopped even when an operation fails. Use Go 1.26 or newer and tmux 3.3a or newer on a Unix system, with tmux and cat on PATH. In a new directory, create a module and add the library from the Go module proxy:

$ go mod init example.com/libtmux-api && \
  go get github.com/libtmux/libtmux-go@latest

Save this complete example as example_test.go. It creates a private temporary socket and stops its server before removing the directory. Cleanup failure fails the example and retains the socket directory. View source

package tmux_test

import (
	"context"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
)

// Open a private server and create a session on it. Find that session, then
// read the server once and walk from a pane up to its window and session
// without another tmux command. A search asks tmux to filter instead.
// The temporary server is stopped even when an operation fails.
func ExampleServer_complete() {
	run := func() (runErr error) {
		directory, err := os.MkdirTemp("", "libtmux-go-api-")
		if err != nil {
			return fmt.Errorf("create socket directory: %w", err)
		}
		server, err := tmux.NewServer(tmux.ServerOptions{
			SocketPath: filepath.Join(directory, "tmux.sock"),
			ConfigFile: "/dev/null",
		})
		if err != nil {
			return errors.Join(err, os.RemoveAll(directory))
		}
		defer func() {
			// Cleanup has its own deadline because the operation may have timed out.
			cleanup, cancel := context.WithTimeout(context.Background(), 5*time.Second)
			defer cancel()
			if err := server.Kill(cleanup); err != nil && !errors.Is(err, tmux.ErrNoServer) {
				runErr = errors.Join(runErr, fmt.Errorf("stop server at %s: %w", directory, err))
				return
			}
			runErr = errors.Join(runErr, os.RemoveAll(directory))
		}()
		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
		defer cancel()
		if _, err = server.NewSession(ctx, tmux.NewSessionRequest{
			Name: "work", WindowName: "editor", Command: "cat", Width: 100, Height: 30,
		}); err != nil {
			return fmt.Errorf("create session: %w", err)
		}
		found, err := server.HasSession(ctx, tmux.HasSessionRequest{Target: "work"})
		if err != nil {
			return fmt.Errorf("find session: %w", err)
		}
		fmt.Println("has work:", found)
		_, err = server.SessionByName(ctx, "missing")
		fmt.Println("missing is not found:", errors.Is(err, tmux.ErrNotFound))
		snapshot, err := server.Snapshot(ctx)
		if err != nil {
			return fmt.Errorf("snapshot: %w", err)
		}
		panes := snapshot.Panes()
		if len(panes) == 0 {
			return errors.New("snapshot holds no panes")
		}
		window, ok := panes[0].Window()
		if !ok {
			return errors.New("pane lost its window")
		}
		session, ok := window.Session()
		if !ok {
			return errors.New("window lost its session")
		}
		name, _ := session.Name()
		fmt.Println("panes:", len(panes), "session:", name)
		filter := tmux.TmuxFilter("#{==:#{session_name},work}")
		matched, err := server.SearchPanes(ctx, &filter)
		if err != nil {
			return fmt.Errorf("search panes: %w", err)
		}
		fmt.Println("matched:", len(matched))
		return nil
	}
	if err := run(); err != nil {
		panic(err)
	}
	// Output:
	// has work: true
	// missing is not found: true
	// panes: 1 session: work
	// matched: 1
}

Run the saved file. Go checks the Output comment and fails on different output or an operation or cleanup error:

$ go test -count=1 -v example_test.go

Members110#

Collections and queries12#

Sessions method Sessions materializes the server's sessions. Failures, including ErrNoServer, remain errors rather than empty results.
Windows method Windows materializes one record per winlink. Failures, including ErrNoServer, remain errors rather than empty results.
Panes method Panes materializes pane records for every winlink. Failures, including ErrNoServer, remain errors rather than empty results.
Clients method Clients materializes attached clients. Failures, including ErrNoServer, remain errors rather than empty results.
ListBuffers method ListBuffers returns an owned snapshot of live tmux buffer rows. A command or transport failure is returned rather than answered with no rows; context cancellation still returns its context error. The result is not a live collection.
ListCommands method ListCommands returns an owned snapshot of raw tmux command-description lines. A list failure is returned rather than answered with no rows. Like Server.ListKeys, it answers on a socket holding no server.
ListKeys method ListKeys returns an owned snapshot of raw tmux key-binding lines. Format requires tmux 3.7 and follows UnsupportedPolicy. tmux 3.7 through 3.7c send a table's sole matching binding to client status and leave stdout empty; this method preserves that upstream and Python behavior. Listing failures remain errors.
ListClients method ListClients returns an owned snapshot of raw tmux client-description lines, the text tmux itself prints. A list failure is returned rather than answered with no rows. Server.Clients answers the same question as typed Client records and is what most callers want.
Snapshot method Snapshot materializes sessions, winlinks, panes, and clients. Its sequential commands produce an observationally consistent result, not an atomic transaction. Failures remain errors rather than empty snapshots; cancellation may occur after earlier listings completed.
SearchPanes method SearchPanes returns a newly materialized snapshot projection of pane views selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.
SearchSessions method SearchSessions returns a newly materialized snapshot projection of sessions selected by tmux's live -f expression. A nil filter omits -f; a nonnil empty filter remains an explicit empty expression.
SearchWindows method SearchWindows returns a newly materialized snapshot projection of winlinks selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.

Common operations51#

NewSession method NewSession creates a detached session, then returns a newly materialized Session. It never changes client focus. KillExisting is not rolled back; transport and context failures may be delivery-ambiguous.
Kill method Kill terminates the configured tmux server and all of its sessions, windows, panes, and clients. After a completed failed kill, a liveness probe makes repeated calls harmless when no daemon answers. Transport or context errors can be delivery-ambiguous; no rollback is attempted.
SourceFile method SourceFile loads or parses one tmux configuration file. The path expands ~ and ~/... for the current user and normalizes redundant separators and dot components without collapsing parent components. Named-user forms are rejected. Exact "-" is rejected because it requires process stdin; a relative path naming a file called "-" remains file data. It can mutate tmux configuration; completed stderr is an error, and cancellation does not prove that parsing or sourcing did not occur.
Options method Options returns a freshly decoded, caller-owned view of known server options, including inherited values. A read or transport failure is returned rather than answered with zero values; context errors propagate. Each returned accessor names the setter that writes it, so ServerOptionValues.BufferLimit pairs with Server.SetBufferLimit.
ShowBuffer method ShowBuffer returns one buffer using Python-compatible line reconstruction. The returned string is owned by the caller; nil Name selects tmux's most recent buffer. Completed stderr is an error.
SetBuffer method SetBuffer stores or appends exact string data without refreshing models. It mutates the selected paste buffer; completed stderr is reported as a redacted command error because Data may be secret. Cancellation does not prove that tmux did not store data.
DeleteBuffer method DeleteBuffer deletes a named buffer, or the most recent buffer when name is nil. Cancellation does not prove that tmux did not delete the buffer.
Cmd method Cmd executes raw tmux arguments and returns caller-owned result slices. A completed nonzero exit remains a result; validation and transport failures return errors. Cancellation cannot prove whether a mutation reached tmux.
SetOption method SetOption stores a server-scope option without refreshing existing models. It may validate a known option against the live version. Completed failures return secret-safe option errors; cancellation does not prove the mutation was not accepted by tmux.
ShowEnvironment method ShowEnvironment returns an owned server-global non-hidden tmux environment. Completed command failures return an empty map unless strict errors are enabled. Externally injected multiline entries return ErrMalformedEnvironment because tmux's multi-entry output does not frame continuation lines. Decode errors are compatible with ErrMalformedEnvironment and return no partial map.
SetEnvironment method SetEnvironment stores a value in the server's global tmux environment. ExpandFormat and Hidden select tmux flags; cancellation does not prove the value was not stored.
UnsetEnvironment method UnsetEnvironment deletes a value from the server's global tmux environment. Cancellation does not prove deletion did not occur.
WaitFor method WaitFor waits for, signals, locks, or unlocks a named tmux channel. It changes only that server-side channel state; cancellation can interrupt the client wait but cannot prove a preceding signal or lock did not take effect. See tmux.WaitForModeLock: before tmux 3.8, abandoning a lock wait costs that channel one unlock.
IsAlive method IsAlive reports whether a tmux server answers on the configured socket. Only an absent server reports false without an error: a socket that exists but cannot be reached, such as one the process may not read, is a question that could not be answered and is returned as an error. Use Server.CheckAlive where an absent server is itself the failure.
UnsetOption method UnsetOption unsets a server-scope option without refreshing existing models. UnsetPanes is invalid at server scope. Completed failures are secret-safe option errors; cancellation does not prove the unset was not accepted.
RunShell method RunShell executes a shell command through tmux and returns an owned stdout slice. Captured foreground shell jobs require tmux 3.5 before execution; older releases deliver that output to no client. A background request returns nil after tmux accepts the job. TargetPane delivers output to that pane on older supported daemons. AsTmuxCommand uses native tmux command semantics rather than promising captured shell-job output. Unsupported optional flags follow UnsupportedPolicy. A completed stderr result is an error; context cancellation can be observed with errors.Is but does not establish that tmux did not start the job.
Session method Session performs a canonical live lookup of id and returns a newly materialized record. Use Session.Refresh when beginning from a record.
Window method Window performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use Window.ResolveSession for that exact relationship.
Pane method Pane performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use Pane.ResolveWindow for that exact relationship.
RawOption method RawOption returns one exact server-scope option value. A successful string is caller-owned; ok reports presence. Targeted reads do not use list leniency, and completed failures return a secret-safe option error. An unindexed empty array is indistinguishable from an empty scalar; use Options for typed array presence.
LoadBuffer method LoadBuffer reads a file into a named or newly allocated buffer. Path follows Server.SourceFile's current-user expansion and lexical normalization. It mutates tmux's destination buffer. Exact "-" is rejected because it names tmux's stdin rather than a path; Server.LoadBufferFrom streams from an io.Reader, and this method is the one that runs over a Connection.
HasSession method HasSession reports whether Target selects a session. With Pattern false it compares session names exactly; with Pattern true, tmux may resolve IDs, client TTYs, unique prefixes, or globs. Pattern-mode completed nonzero exits are misses. Exact-name lookup treats ErrNoServer as a miss and returns other failures.
BindKey method BindKey binds Key to Command in a tmux key table. An empty Command creates a no-op binding. It mutates the table; cancellation does not prove that tmux did not bind Key.
UnbindKey method UnbindKey removes one key binding or every binding in a key table. Key and AllKeys must select exactly one target; cancellation does not prove removal did not occur.
Version method Version returns a materialized handle's daemon version or an unbound handle's cached executable version. Failed probes are not cached. A waiting caller can abandon an in-flight shared probe when ctx ends without canceling its owner.
AttachSession method AttachSession attaches the caller's terminal to a matching session and blocks until detach or context cancellation. Nil standard streams inherit the process streams; each stream must be a concrete terminal descriptor. The call retains caller-supplied files while attached and never owns or closes them. A completed nonzero exit returns CommandError; cancellation can end waiting but does not prove that attachment or detachment did not occur. On Unix, cancellation requests a tmux disconnect before bounded forced cleanup. If the daemon cannot respond, callers may need to restore their terminal state after the call returns.
RemoveEnvironment method RemoveEnvironment marks a variable for removal from new process environments.
SaveBuffer method SaveBuffer writes a named or most-recent buffer to a file. Path follows Server.SourceFile's current-user expansion and lexical normalization. It changes that file. Exact "-" is rejected because it names tmux's stdout rather than a path; Server.SaveBufferTo streams to an io.Writer, and this method is the one that runs over a Connection.
DetachClient method DetachClient detaches one client, or tmux's current client when no target is set. A completed stderr result is an error; cancellation does not prove delivery or detachment did not occur.
Start method Start starts the configured tmux server. It is idempotent when that server is already running. Completed stderr is an error; cancellation does not prove that a daemon was not started.
IfShell method IfShell executes ThenCommand when ShellCommand succeeds and ElseCommand, if present, when it fails. A completed stderr result is an error; cancellation can interrupt delivery without proving that tmux did not execute a branch.
ShowPromptHistory method ShowPromptHistory returns an owned snapshot of tmux prompt-history lines. It is available on every supported tmux. A tmux command or transport failure is returned rather than answered with no history.
ClearPromptHistory method ClearPromptHistory clears all tmux prompt history or one selected class. Version, transport, and completed-stderr failures are returned. It is available on every supported tmux.
LockServer method LockServer locks every attached client on the tmux server. Cancellation does not prove the server did not lock a client.
CheckAlive method CheckAlive returns a CommandError when the configured server is not alive. Cancellation and transport failures are returned directly. Use Server.IsAlive where an absent server is an answer rather than a failure.
ShowMessages method ShowMessages returns an owned snapshot of the tmux message log, terminal capabilities, job summary, or both terminal and job summaries. A zero TargetClient selects tmux's current client; a list failure is returned rather than answered with no rows.
CommandPrompt method CommandPrompt asks tmux to display a background command prompt and returns after tmux accepts it, not after input is submitted or Template runs. It is available on every supported tmux. Later flags follow UnsupportedPolicy. Completed stderr is an error; cancellation does not prove prompt delivery or later execution.
DisplayMessage method DisplayMessage displays or prints a server-scoped tmux message. Print returns an owned stdout slice even when tmux exits nonzero; completed stderr is delivered synchronously through tmux.WarningCommandStderr, not returned as a completed-error classification. Unsupported flags follow UnsupportedPolicy. Any warnings run on the caller goroutine before return. Cancellation does not prove display did not occur.
RefreshClient method RefreshClient redraws a client, or tmux's current client when no target is set. RequestClipboard requires tmux 3.6a and follows UnsupportedPolicy.
SwitchClient method SwitchClient switches tmux's current client to targetSession. TargetSession is a validated session name rather than a stable identity; cancellation does not prove the switch did not occur.
KillSession method KillSession terminates the session selected by tmux target syntax. Pattern and prefix matching are deliberately left to tmux. Completed nonzero exits without stderr are ignored. Transport and context errors are delivery-ambiguous.
ConfigFile method ConfigFile returns the configured tmux configuration path.
SocketPath method SocketPath returns the absolute socket path selected when the server was constructed. An invalid server returns an empty string.
GetEnvironment method GetEnvironment returns one non-hidden global environment entry. A missing or hidden variable reports ok false.
ConfirmBefore method ConfirmBefore asks tmux to display a background confirmation prompt and returns after tmux accepts it, not after the user answers or Command runs. It is available on every supported tmux. ConfirmKey and DefaultYes require tmux 3.4 and follow UnsupportedPolicy. Completed stderr is an error; cancellation does not prove prompt delivery or later command execution did not occur.
DisplayMenu method DisplayMenu displays a menu and waits until tmux closes it. The target client must own a TTY; control-mode clients cannot render menu overlays. It returns no selected value and does not establish whether an item command ran. Unsupported optional flags follow UnsupportedPolicy. Completed stderr is an error, and cancellation does not prove menu delivery or a selected command's effect.
DetachAllClients method DetachAllClients detaches every client except KeepClient or tmux's current client. Cancellation does not prove every client was detached.
LockClient method LockClient locks a client, or tmux's current client when targetClient is nil. Cancellation does not prove the target client was not locked.
SuspendClient method SuspendClient suspends a client, or tmux's current client when targetClient is nil. Cancellation does not prove suspension did not occur.
Equal method Equal reports whether both handles currently select the same socket path. It evaluates relative paths and environment-dependent named and default sockets against each handle's frozen binding.
GlobalSessionScope method GlobalSessionScope returns a handle that preserves s and its error policy.

Other members47#

AppendOption method AppendOption appends to a server-scope option without refreshing existing models. Completed failures are secret-safe option errors; cancellation does not prove the append was not accepted.
Client method Client performs a canonical live lookup of name and returns a new record.
ConnectionBound method ConnectionBound reports whether this handle retains terminal transport owned by a Connection. A bound handle never reconnects or falls back to a tmux subprocess after that connection closes.
Executable method Executable returns the absolute tmux executable path resolved when the server was constructed. An invalid server returns an empty string.
GlobalWindowScope method GlobalWindowScope returns a handle that preserves s and its error policy.
LoadBufferFrom method LoadBufferFrom streams source into a named or newly allocated tmux paste buffer, reading it to completion without holding its contents in memory. It carries any bytes, including NUL, and is bounded by neither argv nor tmux's command-message limit, which is what Server.SetBuffer is bounded by.
NewSessionConnection method NewSessionConnection creates a session and an owned connection on tmux 3.7 or newer. With a live daemon, its creating control client is the first lane. Cold startup first creates a detached session, then pins and attaches to its qualified socket. An attachment failure can return that partial session. Cleanup closes owned clients; tmux policy decides whether the session lives. KillExisting is rejected because removal cannot be rolled back after a later connection failure.
OpenControl method OpenControl starts a control-mode client attached to session. The startup context bounds process start, attach framing, and client registration but does not own the returned client's lifetime. Session must belong to the same configured server selector. Acquisition requires tmux 3.7 and a filesystem that can hard-link the selected Unix socket into a private directory.
OpenNotifications method OpenNotifications starts an owned observation-only stream attached to session. Session must belong to the same configured server selector. A connection-bound server returns ErrConnectionRequiresProcess.
ProcessEnvironment method ProcessEnvironment returns the normalized environment explicitly supplied through ServerOptions. Nil means the server inherited a private process snapshot. The returned slice is owned by the caller; an invalid server returns nil.
RefreshVersion method RefreshVersion returns a materialized handle's daemon version or invalidates an unbound handle's executable cache and probes again. Canceling ctx stops this call's wait; it does not establish whether the executable received a probe.
RequireVersion method RequireVersion returns a VersionTooLowError matching ErrVersionTooLow when the selected daemon, or an executable creating it, is older than minimum.
SaveBufferTo method SaveBufferTo streams a named or most-recent tmux paste buffer into destination without holding its contents in memory. It writes any bytes, including NUL, and preserves them exactly where Server.ShowBuffer reconstructs lines.
SearchClients method SearchClients returns a newly materialized snapshot projection of clients selected by tmux's live -f expression. A nil filter omits -f and requests the unfiltered listing on every supported tmux version. A nonnil filter, including an empty expression, requires tmux 3.4 or newer and otherwise returns VersionTooLowError.
ServerAccess method ServerAccess changes or lists the server access-control entries. It is available on every supported tmux. List returns an owned snapshot, and reports a completed or transport failure rather than answering with no entries; mutation completed stderr is an error.
SessionByName method SessionByName performs a live lookup of the session tmux knows by name and returns a newly materialized record. A name no session holds reports ErrNotFound.
SetBackspace method SetBackspace stores the "backspace" server option as string. Read it with ServerOptionValues.Backspace from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetBufferLimit method SetBufferLimit stores the "buffer-limit" server option as int64. Read it with ServerOptionValues.BufferLimit from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetClipboard method SetClipboard stores the "set-clipboard" server option as SetClipboard. Read it with ServerOptionValues.SetClipboard from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetCodepointWidths method SetCodepointWidths replaces the complete "codepoint-widths" server option array with SparseArraystring, preserving holes and empty values (tmux 3.6 or later). Read it with ServerOptionValues.CodepointWidths from Server.Options; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
SetCommandAlias method SetCommandAlias replaces the complete "command-alias" server option array with SparseArraystring, preserving holes and empty values. Read it with ServerOptionValues.CommandAlias from Server.Options; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
SetCopyCommand method SetCopyCommand stores the "copy-command" server option as string. Read it with ServerOptionValues.CopyCommand from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetDefaultClientCommand method SetDefaultClientCommand stores the "default-client-command" server option as string (tmux 3.6 or later). Read it with ServerOptionValues.DefaultClientCommand from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetDefaultTerminal method SetDefaultTerminal stores the "default-terminal" server option as string. Read it with ServerOptionValues.DefaultTerminal from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetEditor method SetEditor stores the "editor" server option as string. Read it with ServerOptionValues.Editor from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetEscapeTime method SetEscapeTime stores the "escape-time" server option as time.Duration. Read it with ServerOptionValues.EscapeTime from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetExitEmpty method SetExitEmpty stores the "exit-empty" server option as bool. Read it with ServerOptionValues.ExitEmpty from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetExitUnattached method SetExitUnattached stores the "exit-unattached" server option as bool. Read it with ServerOptionValues.ExitUnattached from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetExtendedKeys method SetExtendedKeys stores the "extended-keys" server option as ExtendedKeys. Read it with ServerOptionValues.ExtendedKeys from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetExtendedKeysFormat method SetExtendedKeysFormat stores the "extended-keys-format" server option as ExtendedKeysFormat (tmux 3.5 or later). Read it with ServerOptionValues.ExtendedKeysFormat from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetFocusEvents method SetFocusEvents stores the "focus-events" server option as bool. Read it with ServerOptionValues.FocusEvents from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetGetClipboard method SetGetClipboard stores the "get-clipboard" server option as GetClipboard (tmux 3.7 or later). Read it with ServerOptionValues.GetClipboard from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetHistoryFile method SetHistoryFile stores the "history-file" server option as string. Read it with ServerOptionValues.HistoryFile from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetInputBufferSize method SetInputBufferSize stores the "input-buffer-size" server option as int64 (tmux 3.6 or later). Read it with ServerOptionValues.InputBufferSize from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetMessageLimit method SetMessageLimit stores the "message-limit" server option as int64. Read it with ServerOptionValues.MessageLimit from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetPrefixTimeout method SetPrefixTimeout stores the "prefix-timeout" server option as time.Duration (tmux 3.5 or later). Read it with ServerOptionValues.PrefixTimeout from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetPromptHistoryLimit method SetPromptHistoryLimit stores the "prompt-history-limit" server option as int64. Read it with ServerOptionValues.PromptHistoryLimit from Server.Options; Server.UnsetOption restores inheritance or the global default.
SetTerminalFeatures method SetTerminalFeatures replaces the complete "terminal-features" server option array with SparseArraystring, preserving holes and empty values. Read it with ServerOptionValues.TerminalFeatures from Server.Options; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
SetTerminalOverrides method SetTerminalOverrides replaces the complete "terminal-overrides" server option array with SparseArraystring, preserving holes and empty values. Read it with ServerOptionValues.TerminalOverrides from Server.Options; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
SetUserKeys method SetUserKeys replaces the complete "user-keys" server option array with SparseArraystring, preserving holes and empty values. Read it with ServerOptionValues.UserKeys from Server.Options; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
SetVariationSelectorAlwaysWide method SetVariationSelectorAlwaysWide stores the "variation-selector-always-wide" server option as bool (tmux 3.6 or later). Read it with ServerOptionValues.VariationSelectorAlwaysWide from Server.Options; Server.UnsetOption restores inheritance or the global default.
ShowBufferBytes method ShowBufferBytes returns one buffer as exact caller-owned tmux stdout bytes. Unlike Server.ShowBuffer, it preserves invalid UTF-8, delimiters, and trailing newlines. Nil Name selects tmux's most recent buffer. Completed stderr returns a redacted command error and a nil byte slice.
SocketSelection method SocketSelection returns the socket NewServer selected, snapshotted with the environment and working directory: an explicit socket, else LIBTMUX_SOCKET_PATH, else LIBTMUX_SOCKET, else the server tmux chooses itself from TMUX or its default socket. It does not start tmux or require the selected socket to exist.
String method String returns a concise representation of the server selector.
ValidateLayouts method ValidateLayouts checks every layout and its required pane count before any mutation. Nil and empty sequences succeed without I/O unless ctx is canceled. Empty layout strings are ignored. Other entries require at least one pane; classic trees must contain enough leaves. tmux validates JSON contents and geometry when applying the layout.
WithProcessEnvironmentValue method WithProcessEnvironmentValue returns a server whose tmux subprocesses receive name=value while preserving the receiver's frozen executable, configuration, and exact socket endpoint. It does not expose an inherited environment snapshot through Server.ProcessEnvironment. The result shares daemon-scoped coordination with the receiver. A connection-bound receiver is rejected.
WithSocketPath method WithSocketPath returns a server using path and the receiver's frozen executable, environment, working directory, and server-option policy. Empty clears explicit socket selectors and leaves endpoint selection to tmux. The result has fresh daemon-scoped coordination. A connection-bound receiver is rejected because its transport belongs to the original daemon.

Guides#

Pages that discuss Server.

Concepts: Server, session, window, pane
Guides: Attaching to tmux
Ports: Go MCP API
Go workspace builder API

In other ports#

A tmux server

Equivalents of A tmux server in other languages
Language	Equivalent
Python	`libtmux.Server`
Ruby	`LibTmux::Server`
Lua	`libtmux.Server`
PowerShell	`LibTmux\New-TmuxServer` This cmdlet constructs a shared .NET `LibTmux.Server` handle without contacting tmux.
Julia	`LibTmux.Server` `Server` describes an endpoint without contacting tmux. Read its hierarchy with `snapshot`.
Erlang	`tmux_server` `open/1` observes an existing daemon and starts an endpoint owner. Domain rows remain immutable values.
Elixir	`LibTmux.Server` `Server` describes an existing server by executable and socket. It neither connects nor reserves the server’s identity.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript	`server.Server`
Rust	`server.Server`
Java	`io.github.libtmux.Server`
Clojure	`libtmux.core/open!` Opens a closeable Java server client for an explicit endpoint. Acquisitions return persistent maps with explicit Java references for effects.
Kotlin	`io.github.libtmux.kotlin.Server`
Scala	`io.github.libtmux.scaladsl.Server`
C#	`LibTmux.Server`
F#	`LibTmux.FSharp.Server` This F# module provides functions over the shared .NET `LibTmux.Server` type.
C++	`libtmux::Server`
Swift	`Server`
OCaml	`Libtmux_unix.Client.t` A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources.
Perl	`LibTmux::Server` Construction records connection settings without tmux I/O. Optional LibTmux::Async::Server returns standard Future results for operations.

No equivalent is recorded in Common Lisp.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Server

Description#

Examples#

Members110#

Collections and queries12#

Common operations51#

Other members47#

Guides#

In other ports#

Description#

Examples#

Members110#

Collections and queries12#

Common operations51#

Other members47#

Guides#

In other ports#

Related types#