cmdpane

Documentation

Overview

Package cmdpane manages a persistent tmux split pane that mirrors command execution output in real time.

Index

• type Manager
  • func NewManager(workspace string) *Manager
  • func (m *Manager) Close()
  • func (m *Manager) EnsurePane(ctx context.Context) error
  • func (m *Manager) WriteFooter(exitCode int, err error)
  • func (m *Manager) WriteHeader(command, description string)
  • func (m *Manager) Writer() (io.Writer, error)
• type Placement
  • func DeterminePlacement(cols, rows, pixW, pixH int) Placement
  • func (p Placement) IsActive() bool

Types

type Manager

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

Manager manages a persistent tmux split pane that mirrors command execution output in real time via a tail -f log file.

func NewManager

func NewManager(workspace string) *Manager

NewManager creates a new command pane manager for the given workspace.

func (*Manager) Close

func (m *Manager) Close()

Close kills the tmux pane and closes the log file.

func (*Manager) EnsurePane

func (m *Manager) EnsurePane(ctx context.Context) error

EnsurePane creates or recreates the tmux command pane based on the current terminal dimensions. It is called before every command execution.

Resize handling:

• Terminal too small now → kill existing pane (if any)
• Pane direction changed (e.g. right→bottom after rotating screen) → recreate
• Pane size drifts >50% from target → recreate (tmux auto-resizes proportionally, so we only recreate on significant drift, not minor pixel changes)
• Pane killed externally → recreate

func (*Manager) WriteFooter

func (m *Manager) WriteFooter(exitCode int, err error)

WriteFooter writes a formatted footer after command execution.

func (*Manager) WriteHeader

func (m *Manager) WriteHeader(command, description string)

WriteHeader writes a formatted header before command execution.

func (*Manager) Writer

func (m *Manager) Writer() (io.Writer, error)

Writer returns an io.Writer that appends to the command pane log file. The writer is safe for concurrent use — writes are serialized so that parallel command executions (e.g. from sub-agents) don't interleave.

type Placement

type Placement struct {
	Direction string // "right", "bottom", or "" (none)
	Size      int    // absolute size of the pane in cells (columns or rows)
}

Placement describes where the command pane should be created.

func DeterminePlacement

func DeterminePlacement(cols, rows, pixW, pixH int) Placement

DeterminePlacement decides pane placement based on terminal dimensions.

cols/rows are character-cell counts (from tmux or TIOCGWINSZ ws_col/ws_row). pixW/pixH are pixel dimensions from TIOCGWINSZ (ws_xpixel/ws_ypixel). Pass 0 for pixW/pixH when pixel data is unavailable.

Rules (in priority order):

• physically portrait (pixH > pixW, or rows>cols when pixels unavailable) → bottom
• cols > 80 → right pane, 30% of cols
• rows > 50 → bottom pane, 30% of rows
• neither → no pane (zero-value Placement)

Why pixels matter: character cells are taller than they are wide (roughly 1:2 ratio). A visually-portrait terminal can still have cols > rows. Pixel dimensions correctly identify the physical orientation.

func (Placement) IsActive

func (p Placement) IsActive() bool

IsActive returns true when the placement indicates a pane should be shown.