Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// The VISIBLE screen of a node's session, never the history above it: what the phone's resume
// repaint and the relay attach snapshot paint (main/remote/host-service.ts).
//
// Pure: no tmux, no ssh, no PtyManager. `PtyManager.captureVisible` runs the argv built here (locally,
// or over the ControlMaster through `remoteCaptureVisibleArgs`) and parses the reply here.
//
// Which backend gets one (`visibleCaptureRoute`): the session host answers its own negotiated
// `captureVisible` from its headless emulator (route `sessionHost`; an older host without the feature
// answers nothing, never its ~200-line scrollback `capture`). A direct Windows pane has no visible-only
// read, so it gets NO capture (the client starts from the live stream) rather than history. A plain
// shell has no tmux to ask, and neither has a Zellij session (the optional local backend,
// zellij-backend.ts).
//
// The screen and the cursor are read in ONE tmux invocation (`capture-pane … ; display-message …`), so
// both describe the same instant: a cursor read in a second round trip could describe a screen that has
// since scrolled.
//
// The target is EXACT (`capturePaneTarget`). Node ids end in a counter, so `nt-x-1` is a prefix of
// `nt-x-12`, and tmux resolves a bare target by fnmatch then PREFIX on a miss: a bare target would
// capture ANOTHER node's screen and paint it on this node's client. Measured on tmux 3.4, with only
// `nt-x-12` alive:
// capture-pane -t nt-x-1 → 12's screen, exit 0 (the trap)
// capture-pane -t =nt-x-1 → "can't find pane", exit 1 (also for =nt-x-12: `=name` alone never
// resolves a target-PANE)
// capture-pane -t =nt-x-1: → "can't find session", exit 1
// capture-pane -t =nt-x-12: → 12's screen, exit 0 (exact AND resolves)
// display-message -t =nt-x-1: → exit 0, every format EMPTY
// and the combined `capture-pane -t =nt-x-1: ; display-message …` stops at the failed capture: exit 1,
// nothing on stdout. So an exact miss is a failed command, which the caller reads as unavailable.
/**
* What a visible-only capture returns: the screen and the cursor, read at one instant.
*
* No alternate-screen flag on the tmux and SSH routes. A client of a tmux-backed session reads the
* tmux CLIENT's output, and tmux paints its client on the alternate screen whatever the pane's
* application does. The pane's own `#{alternate_on}` (vim, a TUI) describes a different screen — a
* shell pane reads 0 while the stream is on the alternate screen.
*
* The SESSION-HOST route is the exception and sets `altScreen` itself: there is no tmux client between
* the pane and the stream, so the emulator's active buffer is exactly the stream's.
*/
export interface VisibleCapture {
/** The visible screen with SGR, byte-identical to what `capture-pane -p -e` prints on its own
* (one `\n`-terminated line per row); '' when there is none. Never history. */
screen: string
/** The pane's cursor at capture time, 0-based (`#{cursor_x}`, `#{cursor_y}`); null when unread. */
cursor: { x: number; y: number } | null
/**
* There is NO capture: the backend has no visible-only one, or the capture failed. Set only by
* `unavailableCapture()`; a real capture of an empty pane never carries it. The difference matters:
* a client paints a capture as reset + clear, so an empty one sent for "no capture" would erase
* everything the stream had drawn.
*/
unavailable?: true
/** Set ONLY by the `sessionHost` route (see above). Absent on every tmux/SSH capture. */
altScreen?: boolean
}
/** A session with no visible-only capture, or one that failed: nothing to paint, nothing known. */
export function unavailableCapture(): VisibleCapture {
return { screen: '', cursor: null, unavailable: true }
}
export function visibleCaptureRoute(
s: { sessionHost?: unknown; nativeWindowsPane?: unknown; sshRemote?: unknown; tmuxBacked?: boolean; zellij?: boolean },
tmuxAvailable: boolean
): 'none' | 'ssh' | 'tmux' | 'sessionHost' {
// A Zellij session is `tmuxBacked` too (that field means "releasing a client destroys nothing"),
// but there is no tmux session to capture: never aim the tmux socket at it (pty-manager's rule
// for every path that would talk to tmux). No capture — the client starts from the live stream.
if (s.nativeWindowsPane || s.zellij) return 'none'
if (s.sessionHost) return 'sessionHost'
if (s.sshRemote) return 'ssh'
return tmuxAvailable && s.tmuxBacked ? 'tmux' : 'none'
}
/** The tmux format read beside the screen: cursor column and cursor row, 0-based. */
export const VISIBLE_CAPTURE_FORMAT = '#{cursor_x} #{cursor_y}'
/** "Exactly this session, its active pane" — the only spelling that is exact AND resolves for a
* target-pane command (see the measurement at the top of this file). It does NOT validate the name:
* every caller passes the result as one argv element or `posixQuote`s it. A target spliced UNQUOTED
* into tmux command text must use pane-input.ts's `exactPaneTarget`, which refuses a name this app
* did not generate (named differently so an auto-import cannot pick the wrong one). */
export function capturePaneTarget(sessionName: string): string {
return `=${sessionName}:`
}
/**
* The local tmux argv (after the binary): visible screen with SGR, then the cursor line, in one
* invocation. The `;` is tmux's own command separator, passed as its own argv element (no shell).
* No `-S`: capture-pane without it starts at the first VISIBLE row.
*/
export function localCaptureVisibleArgs(socket: string, sessionName: string): string[] {
const target = capturePaneTarget(sessionName)
return [
'-L',
socket,
'capture-pane',
'-p',
'-e',
'-t',
target,
';',
'display-message',
'-p',
'-t',
target,
VISIBLE_CAPTURE_FORMAT
]
}
const CURSOR_LINE = /^(\d+) (\d+)$/
/**
* Split the combined reply: the LAST line is the cursor line when it has exactly the format's shape,
* and everything before it is the screen. Anything else (no such line, an older tmux that printed
* something different) leaves the whole output as the screen and the cursor unknown.
*/
export function parseVisibleCapture(stdout: string): VisibleCapture {
const body = stdout.replace(/\r?\n$/, '')
const cut = body.lastIndexOf('\n')
const last = cut === -1 ? body : body.slice(cut + 1)
const m = CURSOR_LINE.exec(last)
if (!m) return { screen: stdout, cursor: null }
return {
screen: cut === -1 ? '' : body.slice(0, cut + 1),
cursor: { x: Number(m[1]), y: Number(m[2]) }
}
}