tmux

package
v0.0.20 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package tmux is a thin wrapper over the tmux CLI used to host agent sessions: it creates and kills sessions, captures pane contents and scrollback, resizes windows, and reads/writes the @amux_* activity tags that coordinate detection and reattach across amux instances. tmux exit code 1 ("not found") is treated as an empty/absent result, not an error.

Index

Constants

View Source 
const (
	TagLastOutputAt   = "@amux_last_output_at"
	TagLastInputAt    = "@amux_last_input_at"
	TagSessionOwner   = "@amux_session_owner"
	TagSessionLeaseAt = "@amux_session_lease_ms"
	// TagAgentState publishes the semantic per-session agent state
	// ("idle"/"working"/"done", see activity.AgentState.String()) computed by
	// the activity scan's hysteresis. Written best-effort on state transitions
	// only (see app_tmux_activity_result.go); read-only telemetry for external
	// orchestrators.
	TagAgentState = "@amux_agent_state"
)

Variables

This section is empty.

Functions

func AllSessionStates added in v0.0.15 

func AllSessionStates(opts Options) (map[string]SessionState, error)

AllSessionStates returns the SessionState for every tmux session on the server in a single subprocess call. It runs: 

tmux list-panes -a -F "#{session_name}\t#{pane_dead}"

Sessions that appear in output have Exists=true. Any session with at least one pane where pane_dead is "0" gets HasLivePane=true. If there are no sessions at all (exit code 1), an empty map is returned.

func CapturePane 

func CapturePane(sessionName string, opts Options) ([]byte, error)

CapturePane captures the scrollback history of a tmux pane (excluding the visible screen area) with ANSI escape codes preserved. Returns nil if the session has no scrollback or does not exist.

func CapturePaneTail 

func CapturePaneTail(sessionName string, lines int, opts Options) (string, bool)

CapturePaneTail captures the last N lines of a session's active pane. Returns the content and a success flag. Returns ("", false) on error (e.g., session doesn't exist or capture times out).

func ContentHash 

func ContentHash(content string) [16]byte

ContentHash returns a fast hash of the content for change detection.

func EnsureAvailable 

func EnsureAvailable() error

func GlobalOptionValue added in v0.0.15 

func GlobalOptionValue(key string, opts Options) (string, error)

GlobalOptionValue returns a tmux global option value for the given key. Missing options return an empty value with nil error, while connection failures (for example, no running server) are returned as errors. Unlike SetGlobalOptionValue, read paths do not suppress generic command errors because callers rely on these failures for ownership/coordination fallback decisions.

func GlobalOptionValues added in v0.0.15 

func GlobalOptionValues(keys []string, opts Options) (map[string]string, error)

GlobalOptionValues returns tmux global option values for the given keys in a single tmux command invocation.

func InstallHint 

func InstallHint() string

func IsNoServerError added in v0.0.15 

func IsNoServerError(err error) bool

IsNoServerError reports whether err indicates that no tmux server is currently running for the selected socket/server name.

func KillSession 

func KillSession(sessionName string, opts Options) error

func KillSessionsMatchingTags 

func KillSessionsMatchingTags(tags map[string]string, opts Options) (bool, error)

KillSessionsMatchingTags kills sessions that match all provided tags.

func KillSessionsWithPrefix 

func KillSessionsWithPrefix(prefix string, opts Options) error

KillSessionsWithPrefix kills all sessions with a matching name prefix.

func KillSessionsWithPrefixMissingTag added in v0.0.20 

func KillSessionsWithPrefixMissingTag(prefix, tag string, opts Options) error

KillSessionsWithPrefixMissingTag kills sessions with a matching name prefix only when the given session option is empty. This is used for legacy amux sessions created before @amux_instance existed; modern sessions owned by other app instances are left alone.

func KillWorkspaceSessions 

func KillWorkspaceSessions(wsID string, opts Options) error

KillWorkspaceSessions kills all sessions for a workspace ID.

func ListSessions 

func ListSessions(opts Options) ([]string, error)

ListSessions returns all tmux session names for the configured server.

func ListSessionsMatchingTags 

func ListSessionsMatchingTags(tags map[string]string, opts Options) ([]string, error)

ListSessionsMatchingTags returns sessions matching all provided tags.

func NewClientCommand added in v0.0.14 

func NewClientCommand(sessionName string, p ClientCommandParams) string

NewClientCommand builds the shell command string that creates (or reattaches to) a tmux session with the given name and parameters.

func ResizePaneToSize added in v0.0.19 

func ResizePaneToSize(sessionName string, cols, rows int, opts Options) error

ResizePaneToSize updates a managed session's window size to the given cell dimensions before any new client attaches. This is used to capture an authoritative snapshot at the size a reattached client will render.

func SessionActiveWithin added in v0.0.19 

func SessionActiveWithin(sessionName string, window time.Duration, opts Options) (bool, error)

SessionActiveWithin reports whether any window in the session had tmux activity within the provided time window.

func SessionClientCount added in v0.0.19 

func SessionClientCount(sessionName string, opts Options) (int, error)

SessionClientCount reports how many tmux clients are currently attached to a session.

func SessionCreatedAt 

func SessionCreatedAt(sessionName string, opts Options) (int64, error)

SessionCreatedAt returns the tmux session creation timestamp (unix seconds).

func SessionHasClients 

func SessionHasClients(sessionName string, opts Options) (bool, error)

SessionHasClients reports whether the tmux session has any attached clients.

func SessionLatestActivity added in v0.0.19 

func SessionLatestActivity(sessionName string, opts Options) (time.Time, bool, error)

SessionLatestActivity reports the most recent tmux window_activity timestamp for a session without applying any second-resolution slack.

func SessionName 

func SessionName(parts ...string) string

func SessionNamesWithClients added in v0.0.15 

func SessionNamesWithClients(opts Options) (map[string]bool, error)

SessionNamesWithClients returns the set of session names that currently have at least one attached client.

func SessionPaneID added in v0.0.19 

func SessionPaneID(sessionName string, opts Options) (string, error)

SessionPaneID reports the active pane ID for a session using only tmux metadata. Returns an empty string if the session does not exist.

func SessionPaneSize added in v0.0.19 

func SessionPaneSize(sessionName string, opts Options) (int, int, bool, error)

SessionPaneSize reports the current size of a session's active pane using only tmux metadata. The returned size is independent of whether the pane is eligible for authoritative full-pane snapshots.

func SessionPaneSnapshotInfo added in v0.0.19 

func SessionPaneSnapshotInfo(sessionName string, opts Options) (int, int, bool, error)

SessionPaneSnapshotInfo reports whether a session's active pane is eligible for an authoritative full-pane snapshot, along with its current size. This uses only pane metadata and does not capture pane history.

func SessionTagValue 

func SessionTagValue(sessionName, key string, opts Options) (string, error)

SessionTagValue returns a session option value for the given tag key.

func SetGlobalOptionValue added in v0.0.15 

func SetGlobalOptionValue(key, value string, opts Options) error

SetGlobalOptionValue sets a tmux global option value.

func SetGlobalOptionValues added in v0.0.15 

func SetGlobalOptionValues(values []OptionValue, opts Options) error

SetGlobalOptionValues sets multiple tmux global options in a single tmux command.

func SetMonitorActivityOn 

func SetMonitorActivityOn(opts Options) error

SetMonitorActivityOn enables tmux monitor-activity globally. Called once at startup and when the tmux server name changes, rather than on every activity scan.

func SetSessionTagValue added in v0.0.12 

func SetSessionTagValue(sessionName, key, value string, opts Options) error

SetSessionTagValue sets a tmux session option for the given session. Returns nil if the session no longer exists (killed between create and tag).

func SetSessionTagValues added in v0.0.15 

func SetSessionTagValues(sessionName string, tags []OptionValue, opts Options) error

SetSessionTagValues sets multiple tmux session options for the given session in a single tmux command invocation. Returns nil if the session no longer exists (killed between create and tag).

func SetStatusOff 

func SetStatusOff(opts Options) error

SetStatusOff disables the tmux status line globally for the server.

Types

type ClientCommandParams added in v0.0.14 

type ClientCommandParams struct {
	WorkDir        string
	Command        string
	Options        Options
	Tags           SessionTags
	DetachExisting bool // Detach other clients attached to this session.
}

ClientCommandParams holds the parameters for building a tmux client command.

type OptionValue added in v0.0.15 

type OptionValue struct {
	Key   string
	Value string
}

OptionValue represents a tmux option key/value pair.

type Options 

type Options struct {
	ServerName      string
	ConfigPath      string
	HideStatus      bool
	DisableMouse    bool
	DefaultTerminal string
	CommandTimeout  time.Duration
}

func DefaultOptions 

func DefaultOptions() Options

type PaneModeState added in v0.0.19 

type PaneModeState struct {
	HasState          bool
	AltScreen         bool
	OriginMode        bool
	CursorHidden      bool
	ScrollTop         int
	ScrollBottom      int
	HasAltSavedCursor bool
	AltSavedCursorX   int
	AltSavedCursorY   int
}

PaneModeState describes the VT mode state tmux reports for a captured pane.

type PaneSnapshot added in v0.0.19 

type PaneSnapshot struct {
	Data      []byte
	Cols      int
	Rows      int
	CursorX   int
	CursorY   int
	HasCursor bool
	ModeState PaneModeState
}

PaneSnapshot contains a full-pane capture plus optional cursor metadata from tmux.

func CapturePaneSnapshot added in v0.0.19 

func CapturePaneSnapshot(sessionName string, opts Options) (PaneSnapshot, error)

CapturePaneSnapshot captures the full tmux pane state (scrollback plus the current visible screen) with ANSI escape codes preserved, along with the pane cursor position when tmux reports it.

type SessionActivity 

type SessionActivity struct {
	Name        string
	WorkspaceID string
	TabID       string
	Type        string
	Tagged      bool
}

func ActiveAgentSessionsByActivity 

func ActiveAgentSessionsByActivity(window time.Duration, opts Options) ([]SessionActivity, error)

ActiveAgentSessionsByActivity returns tagged agent sessions with recent tmux activity. Activity is derived from tmux's window_activity timestamp. Note: monitor-activity is set once at startup and per-session at creation via SetMonitorActivityOn, not on every scan.

type SessionState 

type SessionState struct {
	Exists      bool
	HasLivePane bool
}

func SessionStateFor 

func SessionStateFor(sessionName string, opts Options) (SessionState, error)

type SessionTagValues 

type SessionTagValues struct {
	Name string
	Tags map[string]string
}

SessionTagValues stores tag values for a tmux session.

func SessionsWithTags 

func SessionsWithTags(match map[string]string, keys []string, opts Options) ([]SessionTagValues, error)

SessionsWithTags returns sessions matching the provided tags, plus values for requested tag keys.

type SessionTags 

type SessionTags struct {
	WorkspaceID  string
	TabID        string
	Type         string
	Assistant    string
	CreatedAt    int64 // Unix seconds for fresh create/restart; may be zero for reattach.
	InstanceID   string
	SessionOwner string
	LeaseAtMS    int64
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.