tmux

package
v1.7.2 Latest Latest
Warning

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

 Go to latest Published: Apr 9, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const LegacyTmuxPrefix = "claudesquad_"
View Source 
const ProgramAider = "aider"
View Source 
const ProgramClaude = "claude"
View Source 
const ProgramGemini = "gemini"
View Source 
const TmuxPrefix = "staplersquad_"

Variables

This section is empty.

Functions

func CleanupSessions 

func CleanupSessions(cmdExec executor.Executor) error

CleanupSessions kills all tmux sessions that start with "session-" on the default server

func CleanupSessionsOnServer 

func CleanupSessionsOnServer(cmdExec executor.Executor, serverSocket string) error

CleanupSessionsOnServer kills all tmux sessions that start with "session-" on a specific server serverSocket: socket name for server isolation, empty string for default server

func CreateKeepaliveSession added in v1.1.0 

func CreateKeepaliveSession(serverSocket string) error

CreateKeepaliveSession creates a hidden tmux session that keeps the server alive. The session runs an idle shell and is intentionally never cleaned up by stapler-squad. As long as this session exists, the tmux server cannot exit due to having no sessions.

func EnsureServerRunning added in v1.1.0 

func EnsureServerRunning(serverSocket string) error

EnsureServerRunning starts the tmux server if it is not already running. Uses exec.Command directly so it always runs regardless of circuit breaker state.

func NewTmuxSessionWithCleanup 

func NewTmuxSessionWithCleanup(name string, program string) (*TmuxSession, CleanupFunc)

NewTmuxSessionWithCleanup creates a new TmuxSession and returns it along with a cleanup function. Usage: session, cleanup := NewTmuxSessionWithCleanup(name, program); defer cleanup()

func NewTmuxSessionWithPrefixAndCleanup 

func NewTmuxSessionWithPrefixAndCleanup(name string, program string, prefix string) (*TmuxSession, CleanupFunc)

NewTmuxSessionWithPrefixAndCleanup creates a new TmuxSession with custom prefix and cleanup function. Usage: session, cleanup := NewTmuxSessionWithPrefixAndCleanup(name, program, prefix); defer cleanup()

func NewTmuxSessionWithServerSocketAndCleanup 

func NewTmuxSessionWithServerSocketAndCleanup(name string, program string, prefix string, serverSocket string) (*TmuxSession, CleanupFunc)

NewTmuxSessionWithServerSocketAndCleanup creates a TmuxSession with server isolation and cleanup. Usage: session, cleanup := NewTmuxSessionWithServerSocketAndCleanup(name, program, prefix, socket); defer cleanup()

func SetExitEmpty added in v1.1.0 

func SetExitEmpty(serverSocket string, enabled bool) error

SetExitEmpty sets the tmux server-level exit-empty option. When enabled=false, the server stays alive even when all sessions are closed. Requires the server to already be running.

func SetServerRecoveryCallback added in v1.1.0 

func SetServerRecoveryCallback(fn func())

SetServerRecoveryCallback registers a function called after successful server recovery. Thread-safe: the callback executes outside the recoveryMu lock, in a goroutine.

func ToStaplerSquadTmuxName 

func ToStaplerSquadTmuxName(str string) string

ToStaplerSquadTmuxName converts a string to a valid tmux session name with the default prefix

Types

type BannerFilter 

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

BannerFilter detects and filters tmux status line banners from terminal output

func NewBannerFilter 

func NewBannerFilter() *BannerFilter

NewBannerFilter creates a new banner filter with default tmux status patterns

func (*BannerFilter) FilterBanners 

func (bf *BannerFilter) FilterBanners(lines []string) ([]string, int)

FilterBanners removes tmux status banners from a slice of lines Returns the filtered lines and a count of how many banners were removed

func (*BannerFilter) FilterBannersFromText 

func (bf *BannerFilter) FilterBannersFromText(text string) (string, int)

FilterBannersFromText takes a multi-line string and removes banner lines Returns the filtered text and a count of banners removed

func (*BannerFilter) HasMeaningfulContent 

func (bf *BannerFilter) HasMeaningfulContent(text string) bool

HasMeaningfulContent returns true if the text has content beyond just banners The last line may be a tmux status bar, but only exclude it if it matches status bar patterns

func (*BannerFilter) IsBanner 

func (bf *BannerFilter) IsBanner(line string) bool

IsBanner returns true if the given line appears to be a tmux status banner

type CleanupFunc 

type CleanupFunc func() error

CleanupFunc represents a cleanup function that should be deferred

type MockCmdExec 

type MockCmdExec struct {
	RunFunc            func(cmd *exec.Cmd) error
	OutputFunc         func(cmd *exec.Cmd) ([]byte, error)
	CombinedOutputFunc func(cmd *exec.Cmd) ([]byte, error)
}

MockCmdExec provides mock functionality for executor.Executor interface

func (MockCmdExec) CombinedOutput 

func (m MockCmdExec) CombinedOutput(cmd *exec.Cmd) ([]byte, error)

func (MockCmdExec) Output 

func (m MockCmdExec) Output(cmd *exec.Cmd) ([]byte, error)

func (MockCmdExec) Run 

func (m MockCmdExec) Run(cmd *exec.Cmd) error

type Pty 

type Pty struct{}

Pty starts a "real" pseudo-terminal (PTY) using the creack/pty package.

func (Pty) Close 

func (pt Pty) Close()

func (Pty) Start 

func (pt Pty) Start(cmd *exec.Cmd) (*os.File, *exec.Cmd, error)

type PtyFactory 

type PtyFactory interface {
	Start(cmd *exec.Cmd) (*os.File, *exec.Cmd, error)
	Close()
}

func MakePtyFactory 

func MakePtyFactory() PtyFactory

type TmuxSession 

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

TmuxSession represents a managed tmux session

func NewTmuxSession 

func NewTmuxSession(name string, program string) *TmuxSession

NewTmuxSession creates a new TmuxSession with the given name and program. The executor is wrapped with a CircuitBreakerExecutor for resilience.

func NewTmuxSessionFromExisting 

func NewTmuxSessionFromExisting(exactSessionName string) *TmuxSession

NewTmuxSessionFromExisting creates a TmuxSession that wraps an existing tmux session by its exact name. Unlike other constructors, this does NOT add any prefix to the session name - it uses the name exactly as provided. This is used for external sessions discovered via mux socket monitoring that already have tmux sessions.

The session must already exist in tmux. Call AttachToExisting() after creation to establish the PTY connection.

func NewTmuxSessionWithDeps 

func NewTmuxSessionWithDeps(name string, program string, ptyFactory PtyFactory, cmdExec executor.Executor) *TmuxSession

NewTmuxSessionWithDeps creates a new TmuxSession with provided dependencies for testing.

func NewTmuxSessionWithPrefix 

func NewTmuxSessionWithPrefix(name string, program string, prefix string) *TmuxSession

NewTmuxSessionWithPrefix creates a new TmuxSession with a custom prefix for process isolation. The executor is wrapped with a CircuitBreakerExecutor for resilience.

func NewTmuxSessionWithServerSocket 

func NewTmuxSessionWithServerSocket(name string, program string, prefix string, serverSocket string) *TmuxSession

NewTmuxSessionWithServerSocket creates a new TmuxSession with complete server isolation. This uses the tmux -L flag to create a completely separate tmux server, providing true isolation from other tmux sessions. Use this for testing or when you need complete separation from production tmux sessions.

serverSocket: unique socket name (e.g., "test", "teatest_123", "isolated") prefix: session name prefix (e.g., "staplersquad_test_")

func (*TmuxSession) Attach 

func (t *TmuxSession) Attach() (chan struct{}, error)

func (*TmuxSession) AttachToExisting 

func (t *TmuxSession) AttachToExisting() error

AttachToExisting connects to an already-running tmux session and establishes the PTY connection. This is similar to RestoreWithWorkDir but assumes the session definitely exists. Returns an error if the session doesn't exist or PTY connection fails.

func (*TmuxSession) CapturePaneContent 

func (t *TmuxSession) CapturePaneContent() (string, error)

CapturePaneContent captures the content of the tmux pane

func (*TmuxSession) CapturePaneContentRaw 

func (t *TmuxSession) CapturePaneContentRaw() (string, error)

CapturePaneContentRaw captures the pane content with ANSI codes preserved and WITHOUT joining wrapped lines. This is essential for hybrid streaming where we need to preserve exact cursor positioning. The -J flag (join wrapped lines) strips cursor positioning codes, breaking TUI rendering.

func (*TmuxSession) CapturePaneContentWithOptions 

func (t *TmuxSession) CapturePaneContentWithOptions(start, end string) (string, error)

CapturePaneContentWithOptions captures the pane content with additional options start and end specify the starting and ending line numbers (use "-" for the start/end of history)

func (*TmuxSession) Close 

func (t *TmuxSession) Close() error

Close terminates the tmux session and cleans up resources

func (*TmuxSession) Detach 

func (t *TmuxSession) Detach()

Detach disconnects from the current tmux session. It panics if detaching fails. At the moment, there's no way to recover from a failed detach.

func (*TmuxSession) DetachSafely 

func (t *TmuxSession) DetachSafely() error

DetachSafely disconnects from the current tmux session without panicking

func (*TmuxSession) DoesSessionExist 

func (t *TmuxSession) DoesSessionExist() bool

func (*TmuxSession) DoesSessionExistNoCache 

func (t *TmuxSession) DoesSessionExistNoCache() bool

DoesSessionExistNoCache checks if session exists WITHOUT using cache. This is used for critical validation before session creation to ensure we have the most up-to-date information about session existence.

func (*TmuxSession) FilterBanners 

func (t *TmuxSession) FilterBanners(content string) (filteredContent string, bannersRemoved int)

FilterBanners removes tmux status banners from terminal output. This is useful for processing terminal output while excluding tmux status lines.

func (*TmuxSession) GetCursorPosition 

func (t *TmuxSession) GetCursorPosition() (x, y int, err error)

GetCursorPosition returns the current cursor position in the tmux pane. Returns cursor X (column) and Y (row) coordinates, both 0-based.

func (*TmuxSession) GetPTY 

func (t *TmuxSession) GetPTY() (*os.File, error)

GetPTY returns the PTY file descriptor for reading terminal output. This provides direct access to the PTY master for terminal streaming. Returns an error if the PTY is not initialized.

func (*TmuxSession) GetPaneDimensions 

func (t *TmuxSession) GetPaneDimensions() (width, height int, err error)

GetPaneDimensions returns the current dimensions of the tmux pane. Returns width (columns) and height (rows).

func (*TmuxSession) GetPanePID 

func (t *TmuxSession) GetPanePID() (int32, error)

GetPanePID returns the PID of the foreground process in the pane. This is used by HistoryLinker to correlate open files with session records.

func (*TmuxSession) HasMeaningfulContent 

func (t *TmuxSession) HasMeaningfulContent(content string) bool

HasMeaningfulContent checks if the terminal output contains meaningful content (excluding tmux status banners). This is used to determine if the session has produced actual output versus just tmux status line updates.

func (*TmuxSession) HasUpdated 

func (t *TmuxSession) HasUpdated() (updated bool, hasPrompt bool)

HasUpdated checks if the tmux pane content has changed since the last tick. It also returns true if the tmux pane has a prompt for aider or claude code.

func (*TmuxSession) RefreshClient 

func (t *TmuxSession) RefreshClient() error

RefreshClient sends a refresh signal to the tmux client, forcing the process running inside to redraw at current dimensions. This is critical after resizing to update cursor positions and line wrapping.

func (*TmuxSession) Restore 

func (t *TmuxSession) Restore() error

Restore attaches to an existing session and restores the window size

func (*TmuxSession) RestoreWithWorkDir 

func (t *TmuxSession) RestoreWithWorkDir(workDir string) error

func (*TmuxSession) SendKeys 

func (t *TmuxSession) SendKeys(keys string) (int, error)

func (*TmuxSession) SetDetachedSize 

func (t *TmuxSession) SetDetachedSize(width, height int) error

SetDetachedSize set the width and height of the session while detached. This makes the tmux output conform to the specified shape.

func (*TmuxSession) SetWindowSize 

func (t *TmuxSession) SetWindowSize(cols, rows int) error

SetWindowSize allows external callers (like web UI) to set terminal dimensions. This is particularly useful for web terminal integration where the browser controls the size. This method executes the resize immediately by calling both PTY and tmux resize commands.

func (*TmuxSession) Start 

func (t *TmuxSession) Start(workDir string) error

Start creates and starts a new tmux session, then attaches to it. Program is the command to run in the session (ex. claude). workdir is the git worktree directory.

func (*TmuxSession) StartControlMode 

func (t *TmuxSession) StartControlMode() error

StartControlMode begins streaming terminal output via tmux control mode (-C flag). This is the proper way to get real-time terminal output from tmux, replacing pipe-pane + FIFO. Control mode provides structured notifications (%output, %session-changed, etc.) via stdout.

Benefits over pipe-pane: - No FIFO complexity or EOF issues - Direct protocol communication with tmux - Structured, parseable output format - Real-time notifications (no polling) - Native tmux feature (not a hack)

See: https://github.com/tmux/tmux/wiki/Control-Mode

func (*TmuxSession) StartWithCleanup 

func (t *TmuxSession) StartWithCleanup(workDir string) (CleanupFunc, error)

StartWithCleanup creates and starts a new tmux session and returns a cleanup function. Usage: cleanup, err := session.StartWithCleanup(workDir); if err == nil { defer cleanup() }

func (*TmuxSession) StopControlMode 

func (t *TmuxSession) StopControlMode() error

StopControlMode stops the control mode streaming and cleans up resources.

func (*TmuxSession) SubscribeToControlModeUpdates 

func (t *TmuxSession) SubscribeToControlModeUpdates() (string, chan []byte)

SubscribeToControlModeUpdates registers a new subscriber for real-time terminal output. Returns a subscriber ID and a channel that receives terminal output bytes. The channel has a buffer of 100 messages to handle burst traffic.

func (*TmuxSession) TapDAndEnter 

func (t *TmuxSession) TapDAndEnter() error

TapDAndEnter sends 'D' followed by an enter keystroke to the tmux pane.

func (*TmuxSession) TapEnter 

func (t *TmuxSession) TapEnter() error

TapEnter sends an enter keystroke to the tmux pane.

func (*TmuxSession) UnsubscribeFromControlModeUpdates 

func (t *TmuxSession) UnsubscribeFromControlModeUpdates(subscriberID string)

UnsubscribeFromControlModeUpdates removes a subscriber and closes its channel.

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.