Troubleshooting

Each entry below is symptom → cause → fix. If you don’t find your issue here, the FAQ covers the higher-level questions.

Terminals don’t survive restarts

Symptom. You quit nodeterm, relaunch, and terminals come back empty instead of exactly where you left them.

Cause. Cross-restart continuity relies on tmux. If tmux isn’t installed (or isn’t on the PATH nodeterm can see), each terminal falls back to a plain shell with no persistence.

Fix. Install tmux and restart nodeterm:

brew install tmux   # macOS
# Debian/Ubuntu: sudo apt install tmux

Confirm Persistent sessions (tmux) is on in Settings → Shell & terminals. Details in Terminal persistence.

Copy doesn’t reach the clipboard

Symptom. You select text in a terminal but nothing lands on your system clipboard — often only on a remote (SSH) session.

Cause. nodeterm copies via OSC 52, which tmux emits on your behalf. On the remote host that path needs tmux ≥ 3.2; older tmux doesn’t emit the sequence.

Fix. Upgrade tmux on the remote host to 3.2 or newer. Locally, use the emulator copy chords instead — ⌘C (mac) or Ctrl+Shift+C / Ctrl+Insert (Linux/Windows) — after selecting with Option-drag (mac) or Shift-drag. See Terminal persistence → copy.

A terminal shows a white box or “lost context”

Symptom. When you zoom way out or pan fast, a terminal briefly renders as a blank box.

Cause. Terminals draw with WebGL, and browsers cap how many WebGL contexts can be live at once. nodeterm keeps itself under that cap on purpose: when too many terminals are visible simultaneously, the extras fall back to a slower DOM renderer rather than fighting for a context. This is by design — it prevents the flickering you’d otherwise see.

Fix. Zoom in so fewer terminals are on screen; the one you’re looking at gets a WebGL context back. Nothing is lost — only the rendering path changes.

An agent badge never changes

Symptom. An agent node never shows RUNNING / NEEDS YOU, or its session name and subagent cards never appear.

Cause. Those badges come from the agent’s own hooks posting to a small loopback server inside nodeterm — not from parsing output. If the managed hook scripts weren’t installed (or the agent was already running before nodeterm set them up), there’s nothing to report status.

Fix. Close and re-open the agent node so it launches with hooks in place. Note that custom agents don’t get badges at all — they only show process / terminal-title status. See Status & notifications and the Agents overview.

An SSH project won’t connect

Symptom. An SSH project fails to connect, or connects but agents behave as if their CLI is missing.

Cause. nodeterm multiplexes over an SSH ControlMaster and probes the remote host through a login shell. A non-login SSH exec channel often skips your shell rc, so tools on a custom PATH (like claude, or tmux) look absent. Remote persistence also needs tmux on the host.

Fix. Make sure your CLIs are on the PATH your login shell sets up (e.g. in .profile / .zprofile, not just .zshrc’s interactive branch), and that tmux is installed on the remote host. See SSH projects.

auto permission mode seems ignored

Symptom. You set the Claude permission mode to Auto, but sessions still prompt as if it were off.

Cause. --permission-mode auto only exists in Claude Code ≥ 2.1.71. On an older CLI — local or the remote host of an SSH project — nodeterm silently drops the flag rather than crash the launch (older CLIs would exit on an unknown value). Your setting stays Auto; only the launched command changes.

Fix. Upgrade Claude Code to 2.1.71 or newer (on the SSH host for a remote project). nodeterm surfaces the degrade with a ⚠︎ hint on the Auto rows in the tab ⌄ menu when the CLI is too old or not yet probed. See Permission modes.