tmux

package
v1.54.1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package tmux is a thin domain client around the tmux CLI.

Index

Constants

This section is empty.

Variables

View Source 
var RequiredTools = []string{"tmux"}

RequiredTools lists external binaries tmux relies on.

Functions

func Target 

func Target(name string) string

Target returns the canonical pane target for a session.

Types

type Client 

type Client struct{}

Client wraps the tmux CLI.

func New 

func New() *Client

New returns a tmux Client.

func (*Client) ApplyPaneThemes 

func (c *Client) ApplyPaneThemes(themes []PaneTheme) error

ApplyPaneThemes styles panes and injects the optional reports in one tmux invocation, so a theme change costs a single process spawn regardless of session count. tmux aborts the command chain on the first error (e.g. a session that just died), remaining panes keep their old style then; the caller is expected to re-apply on the next occasion.

func (*Client) CapturePane 

func (c *Client) CapturePane(name string, lines int) (string, error)

CapturePane returns what the pane shows plus the last lines of its scrollback. Read only in the strict sense: capture-pane never attaches, so the pane keeps the size the client that owns it gave it. Going through the terminal hub instead would resize the pane to the reader's window.

func (*Client) ClearTabGroup 

func (c *Client) ClearTabGroup(names []string) error

ClearTabGroup removes the split view group options from the sessions, in one tmux invocation.

func (*Client) Kill 

func (c *Client) Kill(name string) error

Kill terminates a session.

func (*Client) ListPanes 

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

ListPanes returns the unique first-pane entries for every session.

func (*Client) NewSession 

func (c *Client) NewSession(name, workdir, shellCmd string, env map[string]string) error

NewSession spawns a detached tmux session. The command runs under an interactive login bash so the full profile chain including ~/.bashrc applies, matching a command typed into a normal shell. An empty shellCmd starts the interactive bash itself.

func (*Client) PaneForeground 

func (c *Client) PaneForeground(name string) (PaneForeground, error)

PaneForeground returns one session's foreground process state.

func (*Client) PaneForegrounds 

func (c *Client) PaneForegrounds() map[string]PaneForeground

PaneForegrounds returns every session's foreground process (first pane only), from a single list-panes call.

func (*Client) PasteLiteral 

func (c *Client) PasteLiteral(name, text string) error

PasteLiteral pastes literal text through a temporary tmux buffer.

func (*Client) Rename 

func (c *Client) Rename(oldName, newName string) error

Rename changes the tmux session name.

func (*Client) SendKey 

func (c *Client) SendKey(name, key string) error

SendKey sends one named key (e.g. "Enter", "Up").

func (*Client) SendLiteral 

func (c *Client) SendLiteral(name, text string) error

SendLiteral sends literal text without key interpretation.

func (*Client) SendRaw 

func (c *Client) SendRaw(name string, data []byte) error

SendRaw injects an exact byte sequence into a pane via send-keys -H (each byte as a hex key code). Unlike SendKey/SendLiteral it does no interpretation, so it carries whatever a browser terminal's onData emits verbatim: printable UTF-8 (including composed accents), control bytes, and escape sequences.

func (*Client) SetHistoryLimit 

func (c *Client) SetHistoryLimit(name string, historyLimit int) error

SetHistoryLimit configures how much scrollback tmux keeps for snapshots.

func (*Client) SetOption 

func (c *Client) SetOption(name, option, value string) error

SetOption sets a tmux option (e.g. a user option "@name") on a session.

func (*Client) SetPaneStyle 

func (c *Client) SetPaneStyle(name, style string) error

SetPaneStyle sets a pane's default colors (style like "bg=#111827,fg=#f9fafb"). tmux answers a pane program's OSC 11 background query from this style, so it is how a session signals light or dark to TUIs while only the control mode client is attached, which never answers such queries itself.

func (*Client) SetTabGroup 

func (c *Client) SetTabGroup(members []TabGroupMember, group, groupName string) error

SetTabGroup writes a split view group onto its member sessions, first member is group position 1. The optional display name rides along when non-empty, a column of 0 takes the column option off the session. All assignments go into one tmux invocation.

func (*Client) SetTabGroupColumn 

func (c *Client) SetTabGroupColumn(name string, col int) error

SetTabGroupColumn writes one member's column, used when a pane created into a split names a column that was never written down.

func (*Client) SetTabGroupEntry 

func (c *Client) SetTabGroupEntry(name, group string, pos, col int, groupName string) error

SetTabGroupEntry writes one session's group membership: the startup terminal restore re-applies a recorded one, the create-into-a-split path writes a fresh one onto the session it just started.

func (*Client) SetTabGroupName 

func (c *Client) SetTabGroupName(names []string, groupName string) error

SetTabGroupName writes the group display name onto every member, empty removes it (the strip falls back to the joined member names).

func (*Client) SetTabPosition 

func (c *Client) SetTabPosition(name string, pos int) error

SetTabPosition writes one session's tab strip position, used by the startup terminal restore to re-apply a recorded order onto a recreated session.

func (*Client) SetTabPositions 

func (c *Client) SetTabPositions(names []string) error

SetTabPositions writes the tab strip order onto the sessions, first name is position 1. All assignments ride in one tmux invocation, so a reorder costs a single process spawn regardless of session count.

func (*Client) StopPipe 

func (c *Client) StopPipe(name string) error

StopPipe detaches any inherited pipe-pane logger (migration cleanup).

type Control 

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

Control is a tmux control-mode client (`tmux -C attach-session`) for one session. It feeds raw pane output into an in-memory ring and answers capture requests on the same ordered channel, so a snapshot and the byte offset that follows it are taken atomically — no pipe-pane log and no snapshot/stream seam where output can be lost or duplicated.

func StartControl 

func StartControl(name string) (*Control, error)

StartControl spawns the control-mode client and blocks until it is ready.

func (*Control) CaptureWindow 

func (c *Control) CaptureWindow(off, height int) ([]byte, int64, error)

CaptureWindow captures height lines of the pane starting off lines back in the scrollback (off 0 is the live screen), for history scrolling. It returns the frame and the stream offset that immediately follows it. The frame carries no cursor — a scrolled history view has none.

func (*Control) Close 

func (c *Control) Close() error

Close detaches the control client; the tmux session itself is untouched.

func (*Control) Delta 

func (c *Control) Delta(offset int64) ([]byte, int64, bool)

Delta returns the buffered bytes after offset and the new offset. reset is true when offset has fallen out of the ring and the caller must re-snapshot.

func (*Control) Exited 

func (c *Control) Exited() bool

Exited reports whether the control client has detached or the session ended.

func (*Control) HistorySize 

func (c *Control) HistorySize() (int, error)

HistorySize reports how many lines of scrollback sit above the visible pane.

func (*Control) Modes 

func (c *Control) Modes() PaneModes

Modes reads the pane's current terminal modes from tmux. The browser keeps xterm's own mouse reporting disabled (to preserve text selection), so it uses these to synthesize the wheel input each program expects.

func (*Control) Notify 

func (c *Control) Notify()

Notify wakes all waiters explicitly (e.g. after a resize changed the pane).

func (*Control) PaneForeground 

func (c *Control) PaneForeground(name string) (PaneForeground, error)

PaneForeground reports the pane's foreground process state over the control connection, so per-keystroke decisions (Shift+Enter) fork nothing.

func (*Control) PaneSize 

func (c *Control) PaneSize() (Size, error)

PaneSize reports the current pane dimensions.

func (*Control) Resize 

func (c *Control) Resize(cols, rows int) error

Resize drives the rendered pane size through this control client.

func (*Control) SendKey 

func (c *Control) SendKey(name, key string) error

SendKey sends one named key (e.g. "Enter", "Up") over this connection.

func (*Control) SendLiteral 

func (c *Control) SendLiteral(name, text string) error

SendLiteral sends literal text over this connection. It is encoded as hex (like SendRaw) so command-line quoting never enters into it.

func (*Control) SendRaw 

func (c *Control) SendRaw(name string, data []byte) error

SendRaw injects an exact byte sequence over this persistent connection, mirroring Client.SendRaw but with no fork per keystroke. Bytes go as hex key codes (send-keys -H) so control/escape bytes pass through verbatim.

func (*Control) Settle 

func (c *Control) Settle(startWait, quiet, maxWait time.Duration)

Settle waits for the repaint a resize triggers to begin and then go quiet, so a following Snapshot captures a finished frame instead of a half-drawn one. Phase one waits (up to startWait) for the program to start repainting; phase two waits for output to fall quiet, bounded by maxWait. A program that does not repaint on resize simply returns after startWait.

func (*Control) Snapshot 

func (c *Control) Snapshot() ([]byte, int64, error)

Snapshot captures the current screen and the stream offset that immediately follows it. Bytes after the offset are delivered as deltas, so nothing is lost or shown twice across the snapshot boundary.

func (*Control) Updated 

func (c *Control) Updated() <-chan struct{}

Updated returns a channel that is closed on the next output or on exit. Subscribe (call Updated) before reading state, then select on the result, so no wake is missed between a read and the wait.

type OSCFilter 

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

OSCFilter strips OSC escape sequences (e.g. terminal title updates) from a byte stream. Unlike a stateless strip it carries its state across chunks, so sequences split at arbitrary read boundaries cannot leak through.

func (*OSCFilter) Filter 

func (f *OSCFilter) Filter(chunk []byte) []byte

Filter returns chunk with OSC sequences removed, holding back an unterminated sequence (or trailing lone ESC) until the next chunk.

func (*OSCFilter) FilterMarks 

func (f *OSCFilter) FilterMarks(chunk []byte) ([]byte, []string)

FilterMarks behaves like Filter and additionally returns the payloads of every OSC sequence completed within this chunk (state carries across chunks, so split sequences still yield one complete payload).

func (*OSCFilter) Reset 

func (f *OSCFilter) Reset()

Reset clears carried state; call it whenever the stream restarts.

type Pane 

type Pane struct {
	Name      string
	PID       string
	StartedAt string // unix epoch seconds, raw
	ShellName string // @dc_shell_name option; non-empty marks a shell session
	Workdir   string // @dc_shell_dir option; the shell's start directory, if any
	Coder     string // @dc_coder option; non-empty marks a coder pane and names its coder
	CoderName string // @dc_coder_name option; the coder's display name at launch
	CoderDir  string // @dc_coder_dir option; the coder's start directory
	TabPos    string // @dc_tab_pos option; the session's tab strip position, raw
	TabGroup  string // @dc_tab_group option; non-empty puts the session into a split view group
	TabGPos   string // @dc_tab_gpos option; the session's position inside its group, raw
	TabGName  string // @dc_tab_gname option; the group's display name, duplicated on every member
	TabGCol   string // @dc_tab_gcol option; the column the member's pane renders in, raw
}

Pane is one tmux session entry as reported by `tmux list-panes`.

func (Pane) StartTime 

func (p Pane) StartTime() time.Time

StartTime parses the pane's raw session_created stamp; zero when invalid.

func (Pane) TabGroupColumn 

func (p Pane) TabGroupColumn() int

TabGroupColumn parses the column the member's pane renders in; 0 when unset or invalid, which renders the member as a column of its own.

func (Pane) TabGroupPosition 

func (p Pane) TabGroupPosition() int

TabGroupPosition parses the pane's position inside its split view group; 0 when unset or invalid, which sorts the member after every positioned one.

func (Pane) TabPosition 

func (p Pane) TabPosition() int

TabPosition parses the pane's tab strip position; 0 when unset or invalid, which sorts the session after every positioned one.

type PaneForeground 

type PaneForeground struct {
	Command   string
	AltScreen bool
}

PaneForeground describes a session's foreground process state. AltScreen separates a full screen TUI (claude's interactive mode) from plain command runs like `claude -p` that share the process name.

type PaneModes 

type PaneModes struct {
	MouseTracking bool // mouse reporting on (wheel -> mouse events, e.g. claude)
	MouseSGR      bool // SGR mouse encoding (mode 1006)
	AltScreen     bool // alternate screen active (full-screen TUI -> cursor keys)
	AppCursor     bool // application cursor keys (DECCKM: ESC O A/B vs ESC [ A/B)
}

PaneModes are terminal modes the browser needs to reproduce wheel scrolling the way the program expects. They matter most when attaching to an already running program, whose mode-set sequences are not part of a screen snapshot, so the browser can't learn them by replaying the stream.

type PaneTheme 

type PaneTheme struct {
	Name   string
	Style  string
	Report []byte
}

PaneTheme describes one pane's theme application for ApplyPaneThemes.

type Size 

type Size struct {
	Cols int
	Rows int
}

Size is a tmux pane dimension in cells.

type TabGroupMember 

type TabGroupMember struct {
	Name string
	Col  int
}

TabGroupMember is one session's place in a split view group: the tmux session name and the column its pane renders in, 0 for a column of its own.

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.