Help us shape the future of Go! Take the 2026 Go Developer Survey

tmuxexec

package
v0.69.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package tmuxexec implements the tmux terminal multiplexer adapter.

Index

Constants

View Source 
const LaunchPendingOption = "@hive-launch-pending"

LaunchPendingOption marks resources that have not committed a Hive launch.

Variables

View Source 
var ErrCommandExited = errors.New("tmux window command exited during startup")

ErrCommandExited matches a CommandExitedError with errors.Is.

View Source 
var ErrInvalidLaunchPhase = fmt.Errorf("not a valid LaunchPhase, try [%s]", strings.Join(_LaunchPhaseNames, ", "))
View Source 
var ErrInvalidPaneLaunchState = fmt.Errorf("not a valid PaneLaunchState, try [%s]", strings.Join(_PaneLaunchStateNames, ", "))

Functions

func LaunchPhaseNames added in v0.63.0 

func LaunchPhaseNames() []string

LaunchPhaseNames returns a list of possible string values of LaunchPhase.

func PaneLaunchStateNames added in v0.63.0 

func PaneLaunchStateNames() []string

PaneLaunchStateNames returns a list of possible string values of PaneLaunchState.

Types

type CleanupError added in v0.63.0 

type CleanupError struct {
	Resources []string
	Err       error
}

CleanupError reports resources that could not be removed after a failed launch.

func (*CleanupError) Error added in v0.63.0 

func (e *CleanupError) Error() string

func (*CleanupError) Unwrap added in v0.63.0 

func (e *CleanupError) Unwrap() error

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client implements tmux operations over a Runner.

func New 

func New(log zerolog.Logger, runner Runner) *Client

New creates a tmux client.

func NewDefault 

func NewDefault(log zerolog.Logger) *Client

NewDefault creates a client that invokes the tmux executable.

func (*Client) AddWindows 

func (c *Client) AddWindows(ctx context.Context, target multiplexer.Target, windows []multiplexer.WindowSpec) error

AddWindows adds windows to an existing tmux session.

func (*Client) AttachOrSwitch 

func (c *Client) AttachOrSwitch(ctx context.Context, target multiplexer.Target, streams multiplexer.AttachStreams) error

AttachOrSwitch switches the active client inside tmux or attaches outside tmux. Window and pane selection is best-effort and ordered so the selected target is visible on entry: attach-session blocks until detach, so selection runs before it, while switch-client returns immediately, so selection runs after it.

func (*Client) Available 

func (c *Client) Available() bool

Available reports whether tmux is available.

func (*Client) CapturePane 

func (c *Client) CapturePane(ctx context.Context, target multiplexer.Target, opts multiplexer.CaptureOptions) (string, error)

CapturePane captures pane text.

func (*Client) CreateSession 

func (c *Client) CreateSession(ctx context.Context, spec multiplexer.SessionSpec) error

CreateSession creates a tmux session from a declarative specification.

func (*Client) CurrentSession 

func (c *Client) CurrentSession(ctx context.Context) (multiplexer.Target, error)

CurrentSession returns the current tmux session, or an empty target outside tmux.

func (*Client) HasSession 

func (c *Client) HasSession(ctx context.Context, target multiplexer.Target) (bool, error)

HasSession reports whether a tmux session exists.

func (*Client) InspectPane 

func (c *Client) InspectPane(ctx context.Context, target multiplexer.Target) (multiplexer.Pane, error)

InspectPane returns one resolved pane.

func (*Client) KillSession 

func (c *Client) KillSession(ctx context.Context, target multiplexer.Target) error

KillSession kills a tmux session.

func (*Client) KillWindow 

func (c *Client) KillWindow(ctx context.Context, target multiplexer.Target) error

KillWindow kills one qualified tmux window.

func (*Client) ListPanes 

func (c *Client) ListPanes(ctx context.Context) ([]multiplexer.Pane, error)

ListPanes returns every pane visible to the current tmux server. A row that does not parse costs only that pane, because callers treat an error as every pane gone. It is an error only when no row parses, as a format that tmux and this package disagree on would produce.

func (*Client) OpenSession 

func (c *Client) OpenSession(ctx context.Context, spec multiplexer.SessionSpec, selection multiplexer.Target) (multiplexer.LaunchResult, error)

OpenSession creates a missing session or opens an existing one. For an existing session, selection names the window or pane to show on entry.

func (*Client) Paste 

func (c *Client) Paste(ctx context.Context, target multiplexer.Target, text []byte, opts multiplexer.PasteOptions) (retErr error)

Paste loads bytes into a private tmux buffer and pastes it into a pane.

func (*Client) RenameSession 

func (c *Client) RenameSession(ctx context.Context, target multiplexer.Target, newName string) error

RenameSession renames a tmux session. It succeeds when the old session is gone and the new one exists: Hive Desktop renames tmux itself before it asks the session service, which may run in the daemon, to rename the row.

func (*Client) ResolveTarget 

func (c *Client) ResolveTarget(ctx context.Context, raw string) (multiplexer.Pane, error)

ResolveTarget resolves a tmux target into a qualified pane.

func (*Client) SendKey 

func (c *Client) SendKey(ctx context.Context, target multiplexer.Target, key multiplexer.NamedKey) error

SendKey sends one validated tmux named-key token.

func (*Client) SendLiteral 

func (c *Client) SendLiteral(ctx context.Context, target multiplexer.Target, text string) error

SendLiteral sends text without interpreting it as key names.

type CommandExitedError added in v0.63.0 

type CommandExitedError struct {
	Session      string
	Window       string
	Pane         string
	Command      string
	Status       int
	Signal       string
	Lost         bool
	Output       string
	Truncated    bool
	CaptureError error
}

CommandExitedError reports a failed or lost pane during session startup. Output is a best-effort terminal excerpt, not a separate stderr stream. Its message leaves out the session name because a LaunchError, which names the session, always wraps it.

func (*CommandExitedError) Error added in v0.63.0 

func (e *CommandExitedError) Error() string

func (*CommandExitedError) Is added in v0.63.0 

func (e *CommandExitedError) Is(target error) bool

func (*CommandExitedError) NotFound added in v0.63.0 

func (e *CommandExitedError) NotFound() bool

NotFound reports the shell's command-not-found exit status.

type ExecRunnerOptions 

type ExecRunnerOptions struct {
	// Binary resolves the tmux executable for each command. Nil uses PATH.
	Binary func(context.Context) (string, error)
	// Environ returns the child environment. Nil inherits the process environment.
	Environ func(context.Context) []string
	// PrepareArgs can add server-selection arguments before execution.
	PrepareArgs func([]string) []string
}

ExecRunnerOptions configures an executable-backed Runner.

type LaunchError added in v0.63.0 

type LaunchError struct {
	Session string
	Phase   LaunchPhase
	// AddedWindows is true when the launch added windows to a session that
	// already existed, so the session itself did not fail.
	AddedWindows bool
	Err          error
}

LaunchError preserves the failed phase and all command and cleanup causes.

func (*LaunchError) Error added in v0.63.0 

func (e *LaunchError) Error() string

func (*LaunchError) Unwrap added in v0.63.0 

func (e *LaunchError) Unwrap() error

type LaunchPhase added in v0.63.0 

type LaunchPhase string

LaunchPhase identifies the phase of a bounded tmux launch. ENUM(allocating, launching, observing, finalizing, committed, rolling_back, failed, cleanup_incomplete) 

const (
	// LaunchPhaseAllocating is a LaunchPhase of type allocating.
	LaunchPhaseAllocating LaunchPhase = "allocating"
	// LaunchPhaseLaunching is a LaunchPhase of type launching.
	LaunchPhaseLaunching LaunchPhase = "launching"
	// LaunchPhaseObserving is a LaunchPhase of type observing.
	LaunchPhaseObserving LaunchPhase = "observing"
	// LaunchPhaseFinalizing is a LaunchPhase of type finalizing.
	LaunchPhaseFinalizing LaunchPhase = "finalizing"
	// LaunchPhaseCommitted is a LaunchPhase of type committed.
	LaunchPhaseCommitted LaunchPhase = "committed"
	// LaunchPhaseRollingBack is a LaunchPhase of type rolling_back.
	LaunchPhaseRollingBack LaunchPhase = "rolling_back"
	// LaunchPhaseFailed is a LaunchPhase of type failed.
	LaunchPhaseFailed LaunchPhase = "failed"
	// LaunchPhaseCleanupIncomplete is a LaunchPhase of type cleanup_incomplete.
	LaunchPhaseCleanupIncomplete LaunchPhase = "cleanup_incomplete"
)

func ParseLaunchPhase added in v0.63.0 

func ParseLaunchPhase(name string) (LaunchPhase, error)

ParseLaunchPhase attempts to convert a string to a LaunchPhase.

func (*LaunchPhase) AppendText added in v0.63.0 

func (x *LaunchPhase) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (LaunchPhase) IsValid added in v0.63.0 

func (x LaunchPhase) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (LaunchPhase) MarshalText added in v0.63.0 

func (x LaunchPhase) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (LaunchPhase) String added in v0.63.0 

func (x LaunchPhase) String() string

String implements the Stringer interface.

func (*LaunchPhase) UnmarshalText added in v0.63.0 

func (x *LaunchPhase) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type PaneLaunchState added in v0.63.0 

type PaneLaunchState string

PaneLaunchState identifies a pane's observed startup outcome. ENUM(allocated, spawned, running, completed, exit_pending, failed, lost) 

const (
	// PaneLaunchStateAllocated is a PaneLaunchState of type allocated.
	PaneLaunchStateAllocated PaneLaunchState = "allocated"
	// PaneLaunchStateSpawned is a PaneLaunchState of type spawned.
	PaneLaunchStateSpawned PaneLaunchState = "spawned"
	// PaneLaunchStateRunning is a PaneLaunchState of type running.
	PaneLaunchStateRunning PaneLaunchState = "running"
	// PaneLaunchStateCompleted is a PaneLaunchState of type completed.
	PaneLaunchStateCompleted PaneLaunchState = "completed"
	// PaneLaunchStateExitPending is a PaneLaunchState of type exit_pending.
	PaneLaunchStateExitPending PaneLaunchState = "exit_pending"
	// PaneLaunchStateFailed is a PaneLaunchState of type failed.
	PaneLaunchStateFailed PaneLaunchState = "failed"
	// PaneLaunchStateLost is a PaneLaunchState of type lost.
	PaneLaunchStateLost PaneLaunchState = "lost"
)

func ParsePaneLaunchState added in v0.63.0 

func ParsePaneLaunchState(name string) (PaneLaunchState, error)

ParsePaneLaunchState attempts to convert a string to a PaneLaunchState.

func (*PaneLaunchState) AppendText added in v0.63.0 

func (x *PaneLaunchState) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (PaneLaunchState) IsValid added in v0.63.0 

func (x PaneLaunchState) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (PaneLaunchState) MarshalText added in v0.63.0 

func (x PaneLaunchState) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (PaneLaunchState) String added in v0.63.0 

func (x PaneLaunchState) String() string

String implements the Stringer interface.

func (*PaneLaunchState) UnmarshalText added in v0.63.0 

func (x *PaneLaunchState) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type Runner 

type Runner interface {
	Available() bool
	Capture(ctx context.Context, args ...string) (stdout, stderr []byte, err error)
	Input(ctx context.Context, input io.Reader, args ...string) (stdout, stderr []byte, err error)
	Interactive(ctx context.Context, streams multiplexer.AttachStreams, args ...string) error
}

Runner executes tmux operations in captured, input-bearing, or interactive mode.

func NewExecRunner 

func NewExecRunner(options ExecRunnerOptions) Runner

NewExecRunner creates a Runner that invokes a configurable tmux executable.

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.