Split-pane sessions: view two live terminals side by side

[timkjr]

Codeman's terminal area shows exactly one active session at a time — switching panes rebinds the single xterm instance and WebSocket to a different session. Multi-monitor spanning and detached windows solve adjacent problems (a bigger window, or two separate windows), but there's no way to see two live sessions side-by-side in one window today.

Proposal (v1, scoped deliberately small): from the active session, open a second, independent, fully live session in a pane beside it via an explicit "Split" button + picker, with a draggable divider. Closing the second pane collapses back to the normal single-pane view.

Key scoping decisions, all deliberate:

• No persistence — a page reload always returns to single-pane. Persisting layout across reload/devices is a named v2 candidate, not designed here.
• Pane B is intentionally plainer than Pane A — its own xterm + WebSocket, but without the local-echo overlay, CJK IME, touch handlers, or keyboard accessory bar (all mobile/touch quality-of-life; this feature is desktop-only by nature). Promoting it to full parity is a scoped v2 once there are two call sites to compare.
• Button + picker trigger only — drag-a-tab-to-split is a named v2 candidate (something already intercepts drag events, and a keybind was declined during design).
• Out of scope for v1: more than 2 panes, vertical splits, mobile/tablet layouts, feature parity between panes.

It's implemented and tested; a PR referencing this thread is up. Flagging here first since it's a genuinely new feature, per the contributing guide.

Full design spec

Problem

Codeman's terminal area shows exactly one active session (pane) at a time — switching panes re-binds the single xterm instance and the single WebSocket to a different session. Multi-monitor spanning (scripts/span-codeman.sh / span-codeman.ps1) turned out to solve a different problem: it makes one browser window bigger, but that window still shows one session; floating subagent windows are draggable overlays on top of it, not tiled panes. There is no way today to see two live sessions (e.g. w1-codeman and w1-mcp-memory) side-by-side in one window, even on a monitor wide enough to fit both.

Goal (v1)

From the active session, open a second, independent, fully live session in a pane beside it — draggable divider, side-by-side only. Closing the second pane collapses back to today's normal single-pane view. No persistence: a page reload always returns to single-pane. Floating subagent/Ultracode windows keep their current behavior unchanged (global, unconstrained across the whole viewport, split or not).

Explicitly out of scope for v1 (v2 candidates, not designed here):

• More than 2 panes / grid layouts
• Vertical (stacked) splits
• Drag-a-tab-to-split as a trigger (v1 trigger is an explicit button + picker)
• Persisting the split layout across reload or across devices
• Mobile/tablet layouts (viewport is too narrow for this to make sense)
• Feature parity between the two panes (see "Pane B is deliberately plainer" below)

Current architecture (why this isn't a CSS change)

terminal-ui.js is built entirely around singleton state: this.terminal (one xterm instance), this._ws/this._wsSessionId (one WebSocket, rebound on every pane switch), a this._xtermSnapshots map used only to restore scrollback into that one terminal when switching back to a session. Roughly 280 references to this singleton state exist across the file (input handling, resize/fit, sizing-token claims, mobile touch gestures, CJK IME, local-echo overlay wiring, keyboard accessory bar, link providers, etc.).

Showing two sessions at once therefore requires a second, independently alive xterm + WebSocket pair running concurrently — not a layout change to one shared instance.

Related prior art: detachSession(id) already opens one session in a genuinely separate browser window with its own independent WebSocket, and two of those can already be snapped side-by-side today with zero new code. That covers "two sessions visible at once" but not what this spec is for: one Codeman window with two panes and a divider you can drag without leaving your seat, each still a full participant in that window's floating subagent windows, header, and settings.

Server-side check (done, not just assumed): MAX_WS_PER_SESSION = 5, scoped by clientId:tabNonce. Splitting always opens a different session in the second pane (self-splitting is disallowed), so this is two sessions each getting their normal one connection — the existing cap needs no server change.

Key design decision: Pane B is deliberately plainer than Pane A

Porting all ~280 singleton behaviors to a second, symmetric pane is not worth it for v1 — most of that code is input-quality-of-life for mobile/touch, and this feature is desktop-only by nature. So:

• Pane A (the session that was already active when you opened the split) stays exactly what it is today — unchanged code path, zero regression risk.
• Pane B is a new, smaller SplitTerminalPane object: its own xterm instance + fit addon, its own WebSocket, resize-on-divider-drag, and plain keyboard input. No local-echo overlay, CJK IME, touch/mobile handlers, or keyboard accessory bar.

If this asymmetry actually bothers you in daily use, promoting Pane B to full parity is a scoped v2 (extract shared logic once there are two call sites to compare).

Components

SplitTerminalPane (terminal-split.js): one instance per secondary pane — constructor(sessionId, mountEl), connect(), fit(), destroy(). No snapshot/scrollback-restore map needed since Pane B is destroyed on close, not hidden-and-restored.

Split container: .terminal-split-container (flex row) wraps .terminal-wrap (Pane A, untouched) + .split-divider (draggable) + .terminal-pane-b. Default 50/50, divider drag updates both panes' flex-basis live and refits both terminals, clamped 20%/80%.

Trigger UI: a "Split" header button (opt-in, off by default) opens a picker of other open sessions, excluding the active one. Picking one creates the split; closing collapses it back.

Edge cases

• Pane B's session ends/is deleted while split → collapse to Pane A at full width.
• Pane A's session ends while split → Pane B is promoted to the new primary pane.
• Both end → falls through to the normal welcome-screen state.
• Subagent/Ultracode floating windows → unaffected, already positioned independent of .terminal-wrap's layout.

[Ark0N]

Hey timkjr

thanks for this input!

[Ark0N]

Sorry this took a day longer than I said on the PR. Answer first: yes, I want the in-page divider, alongside the pop-out window, not instead of it. #453 goes in.

Why both. The pop-out (the ⧉ on a tab, detachSession()) opens /session/<id> as its own browser window: its own connection, its own lifecycle, and the OS decides where it sits. That is the right tool for a second monitor, and for "park this worker over there and forget about it". It is the wrong tool for the thing I actually do most, which is watching one session while typing into another on the same screen: two popups on one monitor is window management, and each popup is a second app surface with its own focus, notifications and reload. A divider inside the one window I already have is a different feature, not a variant of that one. And the fact that your prototype went straight to a second xterm and WebSocket for Pane B, rather than trying to rebind the singleton, is what convinced me it can exist without touching the primary pane's code path.

What I am agreeing to, so the scope is on record:

• Two panes, side by side, one draggable divider, desktop only (the 1180px gate), an opt-in header button that is off by default, no persistence. Exactly your v1.
• Pane B plainer than Pane A, on the condition that the "deliberately plainer" list in the invariants entry is complete and honest. After three passes it nearly is: the keyboard gates it does not mirror (the Ctrl+Z swallow, Shift+Enter, smart copy) either go on that list or get ported, and the Ctrl+Z one I would port.
• Pane B never grows its own way of doing anything the primary pane already owns. Replay, resize, input framing, skin and font propagation all mirror the primary's convention, which is what you have done.

v2, so nobody builds the wrong thing next:

• I would take: per-device persistence of the split (localStorage, like every other layout key, never the server), drag-a-tab-onto-the-divider as a second trigger, and Pane B parity in pieces, keyboard gates first and the local-echo overlay last (it is a mobile feature and this is desktop).
• I would not take a grid or a third pane grown out of this divider. Not because it is wrong. I have been sketching layouts where several live panes are the normal state rather than a mode, and if that happens it should be designed as a layout, with the tab strip and header rethought around it, rather than extruded from a flex-basis. Two panes is the honest scope for a divider.
• A vertical (stacked) split is fine if someone wants it, it is the same container with flex-direction: column, but I am not asking for it.

On #453 itself: the two items from my last pass (a split against a pid === null session, and the chord test that passes with the gate deleted) are all that is left. Push them, or say the word and I apply them at merge, and it goes in the next release either way. Thank you for flagging here before the PR, and for the spec: reading it first is what made the review fast.