Terminal Panes

Terminal Panes

The default pane type. Renders via xterm.js with the WebGL addon for fast scrollback, attached to a PTY (pseudo-terminal) running locally or — via SSH — on a remote host.

---

Renderer

• xterm.js 5 with WebGL + FitAddon + WebLinksAddon + SearchAddon
• Full-color (true color), unicode-aware, mouse-mode capable
• Scrollback default ~5000 lines (configurable in Settings → Terminal)
• Themes: dark default; custom theme overrides per-pane

Component: src/renderer/components/TerminalPane.tsx (+ TerminalTabContent.tsx for individual tab rendering) Hook: src/renderer/hooks/useTerminal.ts

---

PTY lifecycle

Event	Backend behavior
Pane created	Main process spawns a PTY via node-pty, attaches to the renderer over IPC
Pane closed	PTY is killed (close dialog gives an opt-out for SSH sessions to keep the remote tmux session alive)
Workspace switched	PTY is backgrounded — kept alive, just no UI binding. Switch back and the buffer + state are preserved.
App quit	PTYs are killed on before-quit
Pane crashed / shell exited	Restart button appears at the bottom of the pane; click it to re-spawn

Backend manager: src/main/pty-manager.ts. On Windows, ConPTY is used via node-pty's bundled bindings.

---

Restart button

When the shell exits (you ran exit, the process crashed, SSH lost connection), a small Restart Terminal chip slides up from the bottom of the pane. Click it to re-spawn with the same config.

If the pane was using a forced-fresh restart (via the right-click Restart option, or the Ctrl+R hotkey), it skips any tmux reattach logic and creates a brand-new session.

---

Clipboard

ClusterSpace's clipboard split is deliberate and differs from many terminal apps:

Key	Action
Ctrl+C	Always SIGINT. Never copies. This matches every other terminal you've ever used.
Ctrl+Shift+C	Copy selection to clipboard
Ctrl+V	Paste — uses bracketed-paste mode so multi-line content is preserved and shells can disable auto-execute of newlines
Right-click → Copy / Paste	Same actions via context menu

Selection no longer auto-copies on mouseup (that broke too often with mouse-mode apps). Highlight, then Ctrl+Shift+C.

---

Mouse mode and the "Disable App Mouse" toggle

Tmux, vim, less, htop, and many other tools enable terminal mouse mode (\x1b[?1000h and friends). xterm.js then forwards mouse events to the app instead of doing native selection.

This is great when you want to scroll in tmux, but it breaks when you just want to select text. Two escape hatches:

1. Hold Shift or Alt while dragging — xterm.js bypasses mouse-mode for that drag only.
2. Pane menu → Disable App Mouse — toggle that filters every mouse-mode-enable escape sequence from the PTY and every mouse-encoded sequence going back. App stops seeing mouse events; you select text normally.

The toggle is per-pane. Default is off (so apps that need mouse mode just work).

---

Context menu

Right-click any terminal pane to get:

• Copy / Paste / Select All
• Clear — sends \x1bc reset
• Restart Terminal — kills the PTY and spawns a fresh one
• Disable App Mouse — toggle described above
• Attach to tmux session… — opens the SSH-and-tmux
• Convert to Browser — replaces the terminal with a browser pane in-place (kills the PTY first; prompts)
• Maximize / Restore
• Close pane — confirm dialog

---

Tabs within a pane

A terminal pane can hold multiple tabs. Each tab is its own PTY connection — independent terminal, independent tmux session if SSH. See Per-Pane-Tabs for the full story (it's not what you'd expect — there's no tmux switch-client involved).

---

Themes

The renderer reads terminal.theme from Settings. Default is a dark theme matching the rest of the UI. Override fields (background, foreground, cursor color, ANSI palette) via the Settings dialog.

---

See also

• Per-Pane-Tabs — multi-tab terminal panes
• SSH-and-tmux — when the terminal is an SSH connection
• Broadcast-Mode — type to many panes at once
• Keyboard-Shortcuts — every hotkey