tmuxctl

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package tmuxctl wraps tmux subprocess calls used by tmux-webui. It mirrors stations/tmux-webui/tmux_manager.py and the relevant primitives in libs/tmux-lib/tmux_lib/primitives.py.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client runs tmux commands. Construct with New().

func New 

func New(opts ...Option) *Client

func (*Client) Binary 

func (c *Client) Binary() string

Binary returns the tmux executable this client runs. The rescue package spawns its own abandonable probe processes with it (a wedged server can leave clients stuck in uninterruptible connect(), so rescue cannot use the blocking Run path).

func (*Client) CapturePane 

func (c *Client) CapturePane(ctx context.Context, target string, lines int) (string, error)

CapturePane returns the visible content of a pane with ANSI escape sequences (-e) so the frontend ANSI parser sees colors. lines is the scrollback depth; 0 falls back to 300 (the config default — keep the two in sync).

A tmux failure is PROPAGATED (not swallowed to "",nil): callers use the error to hold their last-good state through a transient capture flake instead of treating a blank capture as truth — a blanked pane would drop a blocked agent's ✳ waiting lamp (the "never miss waiting" invariant). Only the "can't find pane/session/window" class — a target that no longer exists — maps to the empty+nil success return, because an empty capture of a dead pane is a legitimate empty, not a flake.

func (*Client) CapturePaneRange 

func (c *Client) CapturePaneRange(ctx context.Context, target string, startAbove, endAbove int) (string, error)

CapturePaneRange captures a history slice by absolute line offsets above the visible top: -S -startAbove .. -E -endAbove. endAbove 0 means "down to the visible bottom" (the -E flag is omitted), i.e. the CapturePane shape. Used by the H1 paged history fetch: chunk k is (offset+chunk, offset+1), which tmux clamps to the real history start — a fully-consumed history returns a short or single-line result, which the caller uses as the exhaustion signal. Verified live: -S -10000 -E -5001 abuts -S -5000 with no gap or overlap.

func (*Client) KillPane 

func (c *Client) KillPane(ctx context.Context, target string) error

func (*Client) KillSession 

func (c *Client) KillSession(ctx context.Context, name string) error

KillSession destroys a session. Exact-match target ("=") matters more here than anywhere else — a stray prefix match would tear down the wrong session.

func (*Client) KillWindow 

func (c *Client) KillWindow(ctx context.Context, session string, window int) error

func (*Client) LayoutOf 

func (c *Client) LayoutOf(ctx context.Context, target string) (string, error)

LayoutOf returns the window-layout string. Used by fit-mode to save/restore layouts when the frontend resizes panes.

func (*Client) ListPanes 

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

func (*Client) ListSessions 

func (c *Client) ListSessions(ctx context.Context) ([]Session, error)

func (*Client) ListWindows 

func (c *Client) ListWindows(ctx context.Context, session string) ([]Window, error)

func (*Client) NewSession 

func (c *Client) NewSession(ctx context.Context, name, cwd string) (string, error)

NewSession creates a detached session and returns the name tmux actually assigned (-P -F round-trips auto-numbered names when name is empty). cwd is the session's working dir; empty falls back to the user's home dir. The caller (server) passes config.DefaultSessionCWD here so tmuxctl stays decoupled from config.

func (*Client) NewWindow 

func (c *Client) NewWindow(ctx context.Context, session string) error

func (*Client) PaneCurrentPath 

func (c *Client) PaneCurrentPath(ctx context.Context, target string) string

PaneCurrentPath returns the target pane's working directory ("" on any failure). Used by @-file autocomplete: the @path token is resolved by the CLI running INSIDE the pane, so completions must be relative to ITS cwd, not the tmux-webui server's.

func (*Client) PaneTTYs 

func (c *Client) PaneTTYs(ctx context.Context) []string

PaneTTYs returns the pane_tty ("/dev/ttys000" form) of every pane across all sessions, for the Monitor's presence overlay to exclude processes a tmux pane already owns. Best-effort: an empty server or a failed query yields nil.

func (*Client) RenameSession 

func (c *Client) RenameSession(ctx context.Context, old, name string) error

RenameSession renames an existing session. The "=" prefix pins the target to an exact match so a rename can't accidentally hit a prefix-sibling session.

func (*Client) RenameWindow 

func (c *Client) RenameWindow(ctx context.Context, session string, window int, name string) error

RenameWindow renames a window. tmux itself accepts almost any name, so validation here stays minimal: non-empty, no control characters, capped at maxWindowNameLen.

func (*Client) ResizePane 

func (c *Client) ResizePane(ctx context.Context, target string, cols, rows int) error

func (*Client) ResizeWindow 

func (c *Client) ResizeWindow(ctx context.Context, target string, cols, rows int) error

ResizeWindow sets a window's size (requires window-size manual, which the workshop tmux sets globally). Used by the mobile single-pane fit: a sole pane can't be sized below its window, so the WINDOW must shrink for a fullscreen TUI (yazi/lazygit) to match the phone. target may be "session:winIdx".

func (*Client) Run 

func (c *Client) Run(ctx context.Context, args ...string) (string, error)

run executes tmux with the given args and returns stdout. Stderr is folded into the returned error so callers can surface tmux complaints.

func (*Client) RunOK 

func (c *Client) RunOK(ctx context.Context, args ...string) (string, bool)

runOK swallows errors. Use for queries where an empty result is the natural fallback (e.g., list-sessions on an empty server).

func (*Client) SelectLayout 

func (c *Client) SelectLayout(ctx context.Context, target, layout string) error

SelectLayout applies a tmux layout preset. Empty layout falls back to "even-horizontal" to match Python's default.

func (*Client) SelectPane 

func (c *Client) SelectPane(ctx context.Context, target string) error

SelectPane focuses a specific pane by tmux target (e.g., "session:0.1").

func (*Client) SelectPaneByDirection 

func (c *Client) SelectPaneByDirection(ctx context.Context, target, direction string) error

SelectPaneByDirection moves focus by direction: left/right/up/down (case-insensitive).

func (*Client) SendEnter 

func (c *Client) SendEnter(ctx context.Context, target string) error

SendEnter is a convenience for the most common single-key send.

func (*Client) SendKey 

func (c *Client) SendKey(ctx context.Context, target, key string) error

SendKey sends a non-literal key spec (e.g. "Enter", "C-c", "Up", "M-x").

func (*Client) SendMouseSGR 

func (c *Client) SendMouseSGR(ctx context.Context, target, button string, col, row int, phase string) error

SendMouseSGR injects a mouse event into the pane's program via send-keys -H (raw hex bytes → the program's stdin, exactly like a real terminal's report), so yazi/lazygit/htop/less/leaf react with zero per-app code. phase is "press"|"release"; wheel events are always a press. Returns an error for an unknown button.

func (*Client) SendText 

func (c *Client) SendText(ctx context.Context, target, text string) error

SendText delivers literal text to a pane. Default buffer name is "_webui_paste" (matches Python).

func (*Client) SendTextWithBuf 

func (c *Client) SendTextWithBuf(ctx context.Context, target, text, buf string) error

func (*Client) SplitWindow 

func (c *Client) SplitWindow(ctx context.Context, target string, horizontal bool) error

func (*Client) WindowPaneCount 

func (c *Client) WindowPaneCount(ctx context.Context, target string) int

WindowPaneCount returns how many panes the target's window holds (0 on error). Used to pick window- vs pane-resize in fit: only a single-pane window needs its window resized.

func (*Client) WindowSize 

func (c *Client) WindowSize(ctx context.Context, target string) (int, int, error)

WindowSize returns the target window's (width, height) in cells; target may be "session:winIdx". Returns (0, 0, error) on any failure so the caller can skip a resize it has no trustworthy size for. Mirrors LayoutOf's display-message shape; used by fit-mode to capture the pre-fit window size for restore (R2).

type Option 

type Option func(*Client)

func WithBinary 

func WithBinary(p string) Option

func WithTimeout 

func WithTimeout(d time.Duration) Option

type Pane 

type Pane struct {
	Window     int    `json:"window"`
	WindowName string `json:"window_name"`
	Pane       int    `json:"pane"`
	Active     int    `json:"active"`
	Width      int    `json:"width"`
	Height     int    `json:"height"`
	Command    string `json:"command"`
	// MouseMode is tmux's #{mouse_any_flag}: 1 when the pane's program has
	// requested mouse tracking (yazi/lazygit/htop/less -r/leaf…). The frontend
	// reads it to route wheel/click into the program instead of the browser's
	// own scroll/focus. 0 for a plain shell pane.
	MouseMode int    `json:"mouse_mode"`
	Title     string `json:"title"`
	ID        string `json:"id"`
}

type Session 

type Session struct {
	Name     string `json:"name"`
	Windows  int    `json:"windows"`
	Attached int    `json:"attached"`
}

type Window 

type Window struct {
	Index  int    `json:"index"`
	Name   string `json:"name"`
	Active int    `json:"active"`
	Panes  int    `json:"panes"`
}

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.