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.
Session backends: Zellij and herdr beside tmux
nodeterm keeps a local terminal alive across app restarts by running it inside a multiplexer
session named nt-<node id>: tmux on macOS/Linux, the session host on Windows. Some people live
in Zellij or herdr and want their canvas terminals to be sessions of that tool, so they
can attach to them from anywhere else. This document is the measurement behind v1: what
PtyManager needs from its backend, what each tool offers, which one v1 implements and why, and
what that backend does not do.
How it was measured
- Zellij 0.45.1 (
zellij-x86_64-unknown-linux-musl, the latest GitHub release on 2026-09-30). - herdr 0.9.3 (
herdr-linux-x86_64, latest release on 2026-09-30; source at 0.9.1 read for paste framing and config paths). - Both run from
/var/tmpwith a throwawayHOME,XDG_CONFIG_HOME,XDG_DATA_HOME,XDG_CACHE_HOME,XDG_RUNTIME_DIR, plusZELLIJ_SOCKET_DIR(Zellij) /HERDR_HOME(herdr). The user's tmux servers were never touched; every server started was killed afterwards. - A painter was a real client in a real pty (a 60-line Python
pty.forkharness that writes scripted input, resizes, and sends SIGHUP). Linux, x86_64. Nothing was measured on macOS.
What PtyManager needs, and what each tool answers
| Need (tmux today) | Zellij 0.45.1 | herdr 0.9.3 |
|---|---|---|
Create-or-attach by stable name (new-session -A -s nt-<id>) |
zellij --config <kdl> --layout-string 'layout { pane; }' attach --create --close-on-exit nt-<id> -- <shell> [args]. Atomic. The initial command is ignored on a reattach. options --default-layout <file> and a default_layout line both still produced the tab bar and status bar; --layout-string did not, and a reattach with it adds no tab. options --default-shell was ignored on a created session, hence the explicit initial command. |
A session is a whole server holding workspaces/tabs/panes (herdr --session <name> server). A node would be a pane made with workspace create --cwd … --env K=V — and the only way to attach a pty to ONE pane is agent attach <pane>, which answered agent_not_found for a plain shell pane. A full herdr --session X attach draws herdr's own workspace UI. |
| Detach, leave running (client exit) | SIGHUP to the client: "Bye from Zellij!", session stays. | Server-side; clients detach. |
Strict exists (has-session -t =name) |
list-sessions -n lines name [Created …] ((EXITED - attach to resurrect) for serialized ones). No sessions = exit 1 plus "No active zellij sessions found" — exit status alone cannot tell absence from failure. Exact names only. |
session list --json (running: true/false). |
| Shell exit ends the session | With a client attached: yes (client prints "Bye", session gone). With no client attached: the session stays listed with no terminal pane ("zombie"); an attach --create to it connects and exits at once. Right after creation a session also has no terminal pane for a moment. |
Pane closes inside a still-running server. |
Capture screen + history (capture-pane -p [-e] -S) |
action dump-screen --pane-id <p> --full [--ansi] (viewport, or viewport + scrollback; --ansi keeps SGR). ~16 ms per call. |
pane read <pane> --source visible|recent [--ansi] [--lines N]. |
Send text as ONE paste honouring the app's paste mode, then Enter (paste-buffer -p) |
action paste --pane-id <p> <text>: plain when the app never asked, framed ESC[200~…ESC[201~ after printf '\e[?2004h' (both measured against cat -v); \n stays \n. Enter = action write --pane-id <p> 13. Text rides ONE argv element: 131,000 bytes delivered, 140,000 failed (exit 126, Linux MAX_ARG_STRLEN). No stdin form. |
pane send-text is never framed — measured: text arrived raw after ?2004h. The mode-aware paste (paste_payload in src/pane.rs) is only behind agent prompt, which requires herdr's own agent detection. |
| Targeting with no client | An action without --pane-id silently did nothing headless (no focused pane without a client). action list-panes --all --json gives ids; the target is the focused live terminal pane, else the lowest id. |
Pane ids (w1:p1) from pane list. |
Kill (kill-session -t =name) |
kill-session <name>, exact match (nt-e did not touch nt-e1). With session_serialization false the session is gone, not resurrectable. |
session stop / pane close. |
| List sessions + attached-client counts (reaper, session memory) | Names: list-sessions -n. Clients: --session <s> action list-clients (one row per client). Not wired in v1 (see gaps). |
session list; client counts not measured. |
Per-session environment at creation, no secrets on argv (-e + update-environment) |
Each session is its own server process, forked by the client that created it, so the session env IS the creating client's env. Measured: a variable exported only to the creating client was visible in the pane; nothing on argv. ZELLIJ_SESSION_NAME is set in the pane. |
Per-pane --env KEY=VALUE is argv (visible in /proc/<pid>/cmdline while the CLI runs). A server started with a variable does pass it to its panes, but then one server per node. |
Pane foreground command (#{pane_current_command}, restart/Eco gates) |
No headless CLI: list-clients shows a running command only with a client attached (N/A for a shell); list-panes gives the launch command. The process table does: zellij --server <socketdir>/contract_version_1/<name> → its child shell → the shell's tpgid → that process. Measured server → bash (tpgid = sleep) → sleep. |
pane process-info --pane <id> returns foreground_processes with argv and cwd — the best answer of the three. |
| Resize / size ownership | Pty resize → client SIGWINCH. Two clients: the session takes the smallest (100×30 + 80×20 → 80×20). | Not measured. |
| Mouse / scroll / copy | Client enters the alternate screen (?1049h) and enables ?1000h ?1002h ?1003h ?1006h; wheel scrolls Zellij's own scrollback; a mouse drag emitted OSC 52 (ESC]52;c;<base64>) to the client — the same model as tmux in nodeterm. |
Own UI; not measured. |
| Key passthrough | Keybindings are session-wide (a session created with cleared keybinds ignored a second client's own config). In default_mode "locked" Ctrl-g, Ctrl-p, Ctrl-t, Ctrl-o all reached cat -v; with the unlock moved to Ctrl-Alt-g, Ctrl-Alt-g then Ctrl-o d detached. |
Not measured. |
Decision: Zellij for v1
Zellij maps onto the tmux contract nearly one to one: an atomic create-or-attach by name, a real
client as the painter (alternate screen, mouse, OSC 52 — the renderer needs nothing new), a paste
that applies the application's own bracketed-paste mode, and environment delivery with nothing on
argv. herdr is a workspace manager whose unit is a server of many panes: a node would have to be
one pane, which cannot be attached to on its own (agent attach refuses a non-agent pane), per-pane
environment is argv, and its text send does not honour paste mode.
herdr gaps, for whoever picks it up: single-pane attach for a non-agent pane; mode-aware paste
from the CLI (pane send-text framing like paste_payload); a per-pane environment that is not
argv (stdin or a file). herdr's pane process-info is better than anything Zellij offers for the
foreground-process question and would be the model for that leg.
v1 design (what shipped)
- Setting:
settings.sessionBackend=tmux(default) |zellij, Settings → Session protection → Session backend. Read throughnormalizeSessionBackend: anything else is tmux. The row is shown only by a core that reports Zellij discovery (POSIX), and says when Zellij is selected but not installed (new terminals then use tmux). - The backend follows the session that exists. A warm tmux session is reattached in tmux; a live Zellij session is reattached in Zellij, whatever the setting says now; only a node with no session anywhere is created in the selected backend. Switching the setting therefore never strands a running agent in one multiplexer while cold restore relaunches it in the other.
- Local projects only. SSH projects keep the remote tmux; Windows keeps the session host.
- Our config (
<userData>/zellij.kdl, rewritten when it changes): locked mode with the lock toggle on Ctrl-Alt-g, no pane frames, no startup tips,session_serialization false, mouse on; plus the bare one-pane layout. When nodeterm starts the default shell, it passes-lfor bash/zsh/fish, as tmux runs its default shell as a login shell. - Zombies: a session listed with no terminal pane is only believed after five pane-less reads 300 ms apart (a just-created session looks the same for a moment); a confirmed zombie is killed before the node is created again.
- Unknown is warm, whatever the setting. When Zellij cannot be asked about a node, the create
is never cold — even with tmux selected — because a node that may still run in Zellij must not
get its snapshot replayed and its agent
--resumed a second time in a new tmux shell (found in review: a first version folded to warm only when Zellij was selected).sessionExists, by contrast, claims a Zellij session only from a listing that parsed and shows it live. - Session names may contain spaces (measured:
my work [Created 0s ago]); the listing parser takes everything before the last[Created. The first version rejected such a line, and one personal session made every probeunknown. --before every positional text (paste,write-chars): measured,- item onewas refused as an unknown argument and-hprinted help with exit 0 while delivering nothing.- Only when Zellij is in play. Probes of nodes we know nothing about (the per-create
list-sessions, the per-deletekill-session, the relay listing) run only when Zellij is selected or has been used on this machine (ourzellij.kdlexists; it is written only when a Zellij terminal is created). A tmux user who merely has Zellij installed runs exactly the old path. - Socket path length. Zellij refuses a socket path over the platform limit ("IPC socket path is
too long (108 bytes, max 107)", measured in review on Linux; macOS allows 103). With the setting on and a
path that would not fit, new terminals fall back to tmux and the Settings row says why. A stock
Mac (no
XDG_RUNTIME_DIR, 49-character$TMPDIR) with a real node id computes to ~104 bytes — over the limit — so on such a Mac the row is expected to say so untilXDG_RUNTIME_DIRorZELLIJ_SOCKET_DIRis set short. Calculated, not run. - Delete kills
nt-<id>in Zellij (exact name) whenever Zellij is in play, so a node deleted after a restart, never mounted since, does not leave its session running. - Paste: refused (not split) above 120,000 UTF-8 bytes.
- Session memory: the sweep reads tmux; the panel reports how many Zellij sessions it did not measure instead of "No sessions are running here.".
Not available with Zellij (named in the Settings row)
- Agent-to-agent messaging and triggers into Zellij sessions are refused (no pane-owner or paste-mode probe).
- Model switch refuses: it cannot stop the foreground process of a Zellij pane.
- The session-memory panel counts Zellij sessions but does not measure them; the idle-session reaper does not see them.
- Pasted text reaches Zellij as a command-line argument (readable by other local users while the call runs); pastes over 120 KB are refused.
- The stale-folder banner and the live pane folder for file links are unavailable.
- SSH projects and Windows keep tmux / the session host.
- nodeterm mobile’s direct SSH attach only finds tmux sessions.
Also true and not in that list: control-mode shadow clients do not exist for Zellij (a released
Zellij node is re-attached by a painter, not a zero-pty control client); the late cold-start check
is SSH-only anyway; paneCursor is unknown, so a resync paint leaves the cursor where it lands.
Surfaces
- Desktop: measured and tested on Linux only. macOS is untested: see the checklist, whose first item decides whether Zellij can be used there at all without a short socket dir.
- Server Edition: the same core. The Settings row appears whenever the server host reports Zellij discovery; sessions are created on the server host.
- Mobile: over the relay, the phone's
pty.attachgoes through the same core and joins the Zellij session (listNodetermSessionsincludes Zellij sessions and remembers them for the attach). The phone's direct SSH path runstmuxon the host and cannot see Zellij sessions — an iOS follow-up.
Device checklist (not run here)
- macOS socket path: on a stock Mac, does the Settings row report the socket path as too long
(expected, see above), and with
ZELLIJ_SOCKET_DIRset short, do Zellij nodes open? Also run the*.realzellij.test.tssuites on a Mac (their sandbox falls back to a short/tmpsocket dir when the sandbox path would not fit). - macOS:
ps -A -o pid=,ppid=,tpgid=,comm=,args=shape andtpgidfor the pane shell (Restart agent / Eco read the pane command from it). - macOS: Zellij from Homebrew is found from a Finder-launched app (
/opt/homebrew/bin). - A canvas node in Zellij: typing, resize, wheel scroll, drag-copy (OSC 52 pill), Shift+Enter in an agent CLI, Ctrl-g reaching Claude Code.
- Attach from an outside terminal with
zellij attach nt-<id>; both clients see the same pane; the smaller one sizes it. - App restart with a Zellij node: warm reattach, no cold restore, agent still running.
- Machine reboot: cold restore replays the scrollback snapshot and resumes the agent in a new Zellij session.
- Server Edition on a Linux host with Zellij installed: create, reattach from a second tab.