tmux

Documentation

Overview

Package tmux wraps the tmux CLI for session/window/pane management. All commands target the dedicated pmux socket: tmux -L pmux.

Index

• Constants
• Variables
• type Client
  • func NewClient(socket string) *Client
  • func (c *Client) AttachPane(paneID string, cols, rows int) (*PaneBridge, error)
  • func (c *Client) CapturePane(paneID string) (string, error)
  • func (c *Client) CreateSession(name string, command string) (string, error)
  • func (c *Client) CursorState(paneID string) (PaneCursorState, error)
  • func (c *Client) IsServerRunning() bool
  • func (c *Client) KillSession(session string) error
  • func (c *Client) ListAll() ([]Session, error)
  • func (c *Client) ListPanes(windowTarget string) ([]Pane, error)
  • func (c *Client) ListSessions() ([]Session, error)
  • func (c *Client) ListWindows(sessionID string) ([]Window, error)
  • func (c *Client) PaneDimensions(paneID string) (int, int, error)
  • func (c *Client) PaneExists(paneID string) bool
  • func (c *Client) ResizePane(paneID string, cols, rows int) error
  • func (c *Client) ResizeWindow(windowTarget string, cols, rows int) error
  • func (c *Client) ResizeWindowAuto(windowTarget string) error
  • func (c *Client) SendKeys(paneID string, data []byte) error
  • func (c *Client) SetGlobalEnv(key, value string) error
  • func (c *Client) Version() (string, error)
  • func (c *Client) WindowForPane(paneID string) (string, error)
• type Pane
• type PaneBridge
  • func (pb *PaneBridge) Close() error
  • func (pb *PaneBridge) InitialContent() string
  • func (pb *PaneBridge) PaneID() string
  • func (pb *PaneBridge) Read(buf []byte) (int, error)
  • func (pb *PaneBridge) Resize(cols, rows int) error
  • func (pb *PaneBridge) Write(data []byte) (int, error)
• type PaneCursorState
• type PaneSize
• type PaneSizeTracker
  • func NewPaneSizeTracker(client *Client) *PaneSizeTracker
  • func (t *PaneSizeTracker) RestoreIfLast(paneID string) error
  • func (t *PaneSizeTracker) TrackAndResize(paneID string, cols, rows int) error
• type Session
• type TitleFilter
  • func NewTitleFilter() *TitleFilter
  • func (f *TitleFilter) Filter(data []byte) []byte
  • func (f *TitleFilter) Reset()
• type Window

Constants

const DefaultSocket = "pmux"

DefaultSocket is the tmux socket name used by pmux.

Variables

var ErrInvalidTarget = errors.New("invalid tmux target")

ErrInvalidTarget is returned when a tmux target ID contains invalid characters.

var ValidTmuxTarget = regexp.MustCompile(`^[a-zA-Z0-9_.$@:%\-]+$`)

ValidTmuxTarget matches tmux pane/session/window IDs like %0, $1, @2, $1:@2.%3, session-name, etc. Rejects shell metacharacters.

Types

type Client

type Client struct {
	Socket  string // Socket name (default: "pmux")
	TmuxBin string // Path to tmux binary (default: "tmux")
}

Client wraps the tmux CLI, targeting the dedicated pmux socket.

func NewClient

func NewClient(socket string) *Client

NewClient creates a tmux client targeting the given socket. It resolves the tmux binary to an absolute path so the client works correctly inside launchd/systemd services where PATH is minimal.

func (*Client) AttachPane

func (c *Client) AttachPane(paneID string, cols, rows int) (*PaneBridge, error)

AttachPane creates a bidirectional stream to a tmux pane. Output is captured via pipe-pane and input is sent via send-keys. If cols and rows are positive, the pane's window is resized to those dimensions.

func (*Client) CapturePane

func (c *Client) CapturePane(paneID string) (string, error)

CapturePane captures the current content of a tmux pane. The -e flag preserves escape sequences and -p prints to stdout.

func (*Client) CreateSession

func (c *Client) CreateSession(name string, command string) (string, error)

CreateSession creates a new detached tmux session. Returns the session ID (e.g. "$0").

func (*Client) CursorState

func (c *Client) CursorState(paneID string) (PaneCursorState, error)

CursorState queries the cursor position and terminal mode flags of a pane. cursor_flag (DECTCEM) requires tmux 3.2+; if unavailable, CursorVisible defaults to true. This is used to synchronize xterm.js mode state on mobile attach, since pipe-pane only captures output after it starts — mode-setting sequences sent earlier (alt screen, cursor hide) are lost.

func (*Client) IsServerRunning

func (c *Client) IsServerRunning() bool

IsServerRunning checks if the tmux server on the pmux socket is alive. Uses a 5-second timeout to prevent blocking the monitoring loop if tmux hangs.

func (*Client) KillSession

func (c *Client) KillSession(session string) error

KillSession kills a tmux session by ID or name.

func (*Client) ListAll

func (c *Client) ListAll() ([]Session, error)

ListAll returns the full session tree (sessions → windows → panes).

func (*Client) ListPanes

func (c *Client) ListPanes(windowTarget string) ([]Pane, error)

ListPanes returns all panes for a given window target (e.g. "$1:@0").

func (*Client) ListSessions

func (c *Client) ListSessions() ([]Session, error)

ListSessions returns all sessions on the pmux socket.

func (*Client) ListWindows

func (c *Client) ListWindows(sessionID string) ([]Window, error)

ListWindows returns all windows for a given session.

func (*Client) PaneDimensions

func (c *Client) PaneDimensions(paneID string) (int, int, error)

PaneDimensions returns the current (cols, rows) of a pane.

func (*Client) PaneExists

func (c *Client) PaneExists(paneID string) bool

PaneExists returns true if a pane with the given ID exists in the tmux server.

func (*Client) ResizePane

func (c *Client) ResizePane(paneID string, cols, rows int) error

ResizePane resizes a specific pane to the given dimensions. For multi-pane windows, only the target pane is resized and other panes in the same window adjust to fill remaining space. For single-pane windows, the containing window is resized instead (since the pane fills the window and resize-pane alone cannot shrink it).

func (*Client) ResizeWindow

func (c *Client) ResizeWindow(windowTarget string, cols, rows int) error

ResizeWindow resizes a tmux window to the given dimensions.

func (*Client) ResizeWindowAuto

func (c *Client) ResizeWindowAuto(windowTarget string) error

ResizeWindowAuto tells tmux to auto-adjust a window to fit the currently attached clients. Uses the -A flag of resize-window.

func (*Client) SendKeys

func (c *Client) SendKeys(paneID string, data []byte) error

SendKeys sends literal input to a tmux pane using the -l flag. Null bytes are stripped because execve truncates argv strings at \x00, which would silently discard trailing input.

func (*Client) SetGlobalEnv

func (c *Client) SetGlobalEnv(key, value string) error

SetGlobalEnv sets a variable in the tmux server's global environment. New panes and windows inherit global environment variables.

func (*Client) Version

func (c *Client) Version() (string, error)

Version returns the tmux version string.

func (*Client) WindowForPane

func (c *Client) WindowForPane(paneID string) (string, error)

WindowForPane returns the "session_id:window_id" target for a pane.

type Pane

type Pane struct {
	ID             string
	Index          int
	Active         bool
	Size           PaneSize
	Title          string
	CurrentCommand string
}

Pane represents a tmux pane within a window.

type PaneBridge

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

PaneBridge provides a bidirectional byte stream to a tmux pane. Output is streamed via tmux pipe-pane through a FIFO, and input is sent via tmux send-keys -l.

Internally, a relay goroutine copies from the FIFO into an os.Pipe. Callers read from the pipe's read end. This design ensures that Close() reliably unblocks any blocked Read() call — closing the pipe's write end causes the read end to return io.EOF immediately. The relay goroutine polls the FIFO with short timeouts so it can check the done channel and exit promptly when Close() is called.

func (*PaneBridge) Close

func (pb *PaneBridge) Close() error

Close detaches from the pane, disabling pipe-pane and cleaning up the FIFO, relay pipe, and temp directory. Any blocked Read call will return io.EOF because the pipe write end is closed.

func (*PaneBridge) InitialContent

func (pb *PaneBridge) InitialContent() string

InitialContent returns the pane content captured at attach time. This represents the screen state before pipe-pane started streaming.

func (*PaneBridge) PaneID

func (pb *PaneBridge) PaneID() string

PaneID returns the ID of the pane this bridge is attached to.

func (*PaneBridge) Read

func (pb *PaneBridge) Read(buf []byte) (int, error)

Read reads output bytes from the pane. Blocks until data is available. Returns io.EOF when the bridge is closed. Implements io.Reader.

func (*PaneBridge) Resize

func (pb *PaneBridge) Resize(cols, rows int) error

Resize changes the pane dimensions. Only the target pane is resized; other panes in the same window adjust to fill remaining space.

func (*PaneBridge) Write

func (pb *PaneBridge) Write(data []byte) (int, error)

Write sends input to the pane via tmux send-keys. Implements io.Writer.

type PaneCursorState

type PaneCursorState struct {
	CursorX       int  // 0-based column
	CursorY       int  // 0-based row
	AlternateOn   bool // pane is using the alternate screen buffer
	CursorVisible bool // DECTCEM state (true = cursor shown)
}

PaneCursorState holds the cursor position and terminal mode state of a pane.

type PaneSize

type PaneSize struct {
	Cols int
	Rows int
}

PaneSize holds terminal dimensions.

type PaneSizeTracker

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

PaneSizeTracker tracks mobile attach counts per pane and restores original pane dimensions when the last mobile client detaches.

func NewPaneSizeTracker

func NewPaneSizeTracker(client *Client) *PaneSizeTracker

NewPaneSizeTracker creates a tracker that uses the given tmux client.

func (*PaneSizeTracker) RestoreIfLast

func (t *PaneSizeTracker) RestoreIfLast(paneID string) error

RestoreIfLast decrements the attach count and restores the pane to its original dimensions when the last mobile client detaches. Returns nil if the pane was already cleaned up or no longer exists.

func (*PaneSizeTracker) TrackAndResize

func (t *PaneSizeTracker) TrackAndResize(paneID string, cols, rows int) error

TrackAndResize resizes the target pane to the given mobile dimensions and increments the attach count. On first attach, the original pane dimensions are saved for later restoration. The count is only incremented on success so that RestoreIfLast never operates on a phantom attach.

type Session

type Session struct {
	ID             string
	Name           string
	CreatedAt      int64
	LastActivityAt int64
	Attached       bool
	Windows        []Window
}

Session represents a tmux session.

type TitleFilter

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

TitleFilter strips tmux/screen-specific ESC k ... ESC \ (set window title) escape sequences from terminal output. These sequences are not part of the ANSI standard and are not recognized by xterm.js, which renders the title text as visible output.

The filter is stateful to handle sequences that span chunk boundaries. All other escape sequences (CSI, OSC, etc.) pass through unmodified.

func NewTitleFilter

func NewTitleFilter() *TitleFilter

NewTitleFilter returns a TitleFilter in passthrough state.

func (*TitleFilter) Filter

func (f *TitleFilter) Filter(data []byte) []byte

Filter processes a chunk of terminal output, stripping ESC k ... ESC \ title sequences. Returns filtered data.

The returned slice is valid only until the next call to Filter.

func (*TitleFilter) Reset

func (f *TitleFilter) Reset()

Reset clears internal state, returning to passthrough mode. Any partially buffered title sequence is discarded.

type Window

type Window struct {
	ID     string
	Name   string
	Index  int
	Active bool
	Panes  []Pane
}

Window represents a tmux window within a session.