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
// PANE INPUT: typed bytes reach a node's PANE, never a tmux CLIENT. `PtyManager.sendPaneKeys` uses
// these plans (bulk pause, Esc in the ⌘M chat view, the chat clear). They were written for live-link
// Control, retired in 2026-11; the measurements below are about tmux and still hold.
//
// Why a pane and not a client. Writing into a tmux client's pty (the owner's painter) makes tmux
// read the bytes as that client's KEYBOARD: they go through its key tables, so `C-b s` opens the
// session chooser and every other session on the server is one keystroke away (`C-b s`, `j`,
// Enter). So keys are injected into the pane with `send-keys -H`, which tmux
// hands to the pane as `KEYC_LITERAL` bytes (`cmd-send-keys.c` → `window_pane_key` →
// `input_key`: "Literal keys go as themselves"), with no client and no key table involved — the
// same command the background-write path already types with (`encodeSendKeysHex`).
//
// THE TWO PLANS
// - keys → `tmux -L <socket> source-file -`, the command TEXT on stdin:
// if-shell -F -t =nt-x: '#{pane_in_mode}' 'copy-mode -q -t =nt-x:'
// send-keys -t =nt-x: -H 1b 5b 41
// `source-file -` keeps every typed byte (a password typed into the shell, say) off every
// command line, local and SSH. The mode cancel comes first because `send-keys` into a pane in a
// mode does NOT reach the app: copy mode dispatches its own key table, and tree mode (`C-b s`
// opened by the owner) handles the keys itself — `j` then Enter would switch the owner's
// client to another session. `copy-mode -q` leaves ANY mode, not just copy mode.
// - paste → the paste plan `sendText` already uses (`load-buffer -` from stdin, the same mode
// cancel, `paste-buffer -d -p -r`), with the text `sanitizePasteText`-ed, and NO Enter: tmux
// frames it only when the pane's app asked for bracketed paste (`-p`), `-r` keeps `\n`.
//
// WHY NOT `paste-buffer` FOR EVERYTHING (the spec's first candidate). tmux 3.7 passes paste buffer
// CONTENT through vis(3) (issue #453), so an ESC byte arrives as the two characters `^[`: an arrow
// key arrives as the text `^[[A`, and Ctrl-C as `^C` (measured below, row x and 4e). Keys must never
// ride a paste buffer.
//
// MEASURED (2026-10-04, Linux, private socket + private TMUX_TMPDIR, conf = `set -g prefix C-b`;
// tmux 3.4 = /usr/bin/tmux, tmux 3.7b = the release the macOS app bundles, sha256-pinned, built
// from source). The pane ran `stty raw -echo -iexten; cat > file`, i.e. the file is exactly what the
// app's stdin received. SSH was NOT measured over a real ssh (no key for `ssh localhost` on the
// measuring host); the remote command line is proven under a real /bin/sh in
// pane-input.realtmux.test.ts instead.
//
// check 3.4 3.7b
// 1 bytes exact: 0x00-0xff in 4 batches, ESC[A, 276/276 exact 276/276 exact
// ESC O A, CR, ^C, DEL, ç 漢 🙂 é
// 2 prefix inert: 02 73 via the keys plan, a real pane got 02 73, pane got 02 73,
// client attached pane_in_mode 0 pane_in_mode 0
// control: the SAME bytes typed INTO the client tree-mode opened tree-mode opened
// 3 copy mode, then 61 mode left, pane got 61 mode left, got 61
// control: send-keys -H with NO cancel eaten by copy mode eaten by copy mode
// tree mode (C-b s on the client), then j Enter tree gone, pane got tree gone, pane got
// 6a 0d, client stayed 6a 0d, client stayed
// on its session on its session
// tree mode via choose-tree -t, then 61 tree gone, got 61 tree gone, got 61
// `copy-mode -q` exists yes yes
// 4 paste a\nb, app asked for ?2004h ESC[200~ a \n b ESC[201~ (both)
// paste a\nb, app did not a \n b (both)
// paste x ESC[A y (sanitized first) x [A y (both)
// paste ç漢🙂é intact (both)
// paste into a pane in copy mode mode left, framed (both)
// (info) paste p ^C q DEL r TAB z CR w bytes verbatim ^C → "^C", DEL → "^?",
// TAB/CR verbatim
// (info) UNSANITIZED ESC in a paste ESC verbatim "^[" (vis(3))
// 5 =nt-a-1: with nt-a-12 alive only nt-a-1 got it (both)
// =nt-a-9: (missing), keys and paste exit 1 "can't find session", nothing (both)
// =nt-a-1: after nt-a-1 was killed exit 1, nt-a-12 untouched (both)
// 6 16384 bytes in ONE source-file (16 lines) exact, 58 ms exact, 96 ms
// 7 latency, 50 single bytes (spawn → bytes in median 3.1-3.3 ms, median 2.4 ms,
// the file) p95 4.0-5.9 ms p95 12.1 ms
// 8 SSH not measured over ssh (see above)
// x (info) ESC[A through paste-buffer -r ESC[A "^[[A" (text)
//
// Also measured: a guard command tmux cannot PARSE (an unknown flag inside the if-shell string)
// rejects the whole `source-file -` text before anything runs — exit 1, nothing typed — on both
// versions; separate LINES are separate command groups at RUN time (a failing line does not stop
// the next one), which is harmless here because every line names the same exact target.
// Version floors: `source-file -` needs tmux 3.1 (CHANGES 3.0a→3.1); an older SSH host fails the
// keys plan closed (exit 1). `copy-mode -q` is 3.2+ per the plan; untested below 3.4.
// Read from tmux's source (window.c `window_pane_key`), not measured: `send-keys` honours a window's
// `synchronize-panes` (the keys are copied to its other panes) and silently drops input to a pane
// disabled with `select-pane -d` while still exiting 0. nodeterm's conf sets neither.
import type { SshConnection } from '../shared/ssh'
import { posixQuote } from '../shared/ssh'
import { sanitizePasteText } from './paste-injection'
import {
assertPasteBuffer,
exactPaneTarget,
localTmuxDeleteBufferArgs,
pasteBufferName,
type PasteDelivery
} from './tmux-naming'
import { SESSION_SOCKET_REF, childArgs, remoteDeleteBufferArgs, sessionTmuxCmd } from './remote-ssh/control-master'
/** One unit of pane input. `keys` are typed byte for byte; `paste` is text tmux frames per the
* pane's own bracketed-paste state. */
export type ControlInputChunk = { kind: 'keys'; data: string } | { kind: 'paste'; text: string }
/** Bytes per `send-keys -H` line: 3 characters each on the line, so ~3 KiB a line. */
export const KEYS_PER_COMMAND = 1024
/**
* "Exactly this session, its active pane". Node ids end in a counter, so `nt-a-1` is a prefix of
* `nt-a-12`, and tmux resolves a bare target by prefix on a miss: a bare target would type into
* ANOTHER node. `=name:` is exact and resolves (capture-route.ts has the measurement). Throws for a
* name this app did not generate: the target is spliced UNQUOTED into tmux command text. ONE
* definition (tmux-naming.ts), shared with every other node-keyed tmux verb.
*/
export { exactPaneTarget }
/** The stdin of `tmux source-file -`: leave any mode, then type each byte literally. */
export function keysCommandText(session: string, data: string): string {
const t = exactPaneTarget(session)
const bytes = Buffer.from(data, 'utf8')
if (bytes.length === 0) throw new Error('no bytes to type')
let out = `if-shell -F -t ${t} '#{pane_in_mode}' 'copy-mode -q -t ${t}'\n`
for (let i = 0; i < bytes.length; i += KEYS_PER_COMMAND) {
const hex = [...bytes.subarray(i, i + KEYS_PER_COMMAND)].map((b) => b.toString(16).padStart(2, '0'))
out += `send-keys -t ${t} -H ${hex.join(' ')}\n`
}
return out
}
/** argv (after the tmux binary) for the keys plan; the command text rides stdin. */
export function localKeysArgs(socket: string): string[] {
return ['-L', socket, 'source-file', '-']
}
/** The text rides stdin (load-buffer -); tmux frames it only if the pane's app asked (-p). No Enter. */
export function localPasteArgs(socket: string, session: string, buffer: string): string[] {
const t = exactPaneTarget(session)
assertPasteBuffer(buffer)
return [
'-L', socket,
'load-buffer', '-b', buffer, '-', ';',
'if-shell', '-F', '-t', t, '#{pane_in_mode}', `copy-mode -q -t ${t}`, ';',
// -d: drop our private buffer afterwards; -p: tmux decides framing from the pane's real state;
// -r: keep `\n` as `\n` instead of tmux's default `\n`→`\r` rewrite.
'paste-buffer', '-d', '-p', '-r', '-b', buffer, '-t', t
]
}
/** ssh args running `tmux -L node-terminal source-file -` on the host; the command text rides stdin. */
export function remoteKeysArgs(conn: SshConnection, controlPath: string, session: string): string[] {
// The socket is the one HOLDING `session` (an adopted legacy session lives on the other server).
return childArgs(conn, controlPath, sessionTmuxCmd(session, `tmux -L ${SESSION_SOCKET_REF} source-file -`))
}
/**
* ssh args for the remote paste plan with an exact target; the text rides stdin. Every piece the
* remote SHELL would otherwise read is single-quoted: tmux's `;` (bare, it would end the tmux
* command), the `=name:` target, the `#{…}` format (`#` starts a comment) and the inner command,
* which is one tmux argument.
*/
export function remotePasteArgs(conn: SshConnection, controlPath: string, session: string, buffer: string): string[] {
const t = exactPaneTarget(session)
assertPasteBuffer(buffer)
const q = posixQuote(t)
return childArgs(
conn,
controlPath,
sessionTmuxCmd(
session,
`tmux -L ${SESSION_SOCKET_REF} load-buffer -b ${buffer} - ';' ` +
`if-shell -F -t ${q} '#{pane_in_mode}' ${posixQuote(`copy-mode -q -t ${t}`)} ';' ` +
`paste-buffer -d -p -r -b ${buffer} -t ${q}`
)
)
}
/**
* EVERYTHING one chunk decides, in one tested place (the lesson in tmux-naming.ts's
* `localPasteDelivery`: a caller that re-composes sanitize / empty / buffer name lets a test pass
* while one of them is deleted). The argv to run, its stdin, and the buffer sweep for a paste whose
* `paste-buffer` never ran (run it with `runPasteDelivery`). null: a paste that sanitized to
* nothing — there is nothing to run. Throws for an empty key chunk or a name we did not generate.
*/
export function controlInputPlan(socket: string, session: string, chunk: ControlInputChunk): PasteDelivery | null {
if (chunk.kind === 'keys') {
return { args: localKeysArgs(socket), body: keysCommandText(session, chunk.data), cleanup: null }
}
const body = sanitizePasteText(chunk.text)
if (body.length === 0) return null
const buffer = pasteBufferName()
return { args: localPasteArgs(socket, session, buffer), body, cleanup: localTmuxDeleteBufferArgs(socket, buffer) }
}
/** `controlInputPlan` on the host, over the ControlMaster (the host's `node-terminal` socket). */
export function remoteControlInputPlan(
conn: SshConnection,
controlPath: string,
session: string,
chunk: ControlInputChunk
): PasteDelivery | null {
if (chunk.kind === 'keys') {
return { args: remoteKeysArgs(conn, controlPath, session), body: keysCommandText(session, chunk.data), cleanup: null }
}
const body = sanitizePasteText(chunk.text)
if (body.length === 0) return null
const buffer = pasteBufferName()
return {
args: remotePasteArgs(conn, controlPath, session, buffer),
body,
cleanup: remoteDeleteBufferArgs(conn, controlPath, buffer, session)
}
}