Workspaces and Layout

Workspaces and Layout

A workspace is a named set of panes laid out on a grid. ClusterSpace lets you keep many workspaces in parallel and switch between them like browser tabs — each remembers its own grid, pane configuration, and the running PTYs in every pane.

---

The grid model

Each workspace has a grid defined by rows × cols (1×1 up to 4×4). Every cell can hold a pane (terminal, browser, or empty). Two extra optional fields, rowSizes and colSizes, store fractional weights so you can have, say, a tall left column and a short bottom row.

interface GridConfig {
  rows: number
  cols: number
  rowSizes?: number[]   // length === rows; absent = equal sizing
  colSizes?: number[]   // length === cols
}

Source: src/shared/types.ts:1-9. Persisted by WorkspaceStore in clusterspace-workspaces.json.

---

Creating a workspace

• Hotkey: Ctrl+T
• Status bar / empty-state button: + New Workspace
• Command palette: Ctrl+P → "new workspace"

The new-workspace dialog asks for a name and a starting grid (templates: 1×1, 2×1, 2×2, 3×2, 4×2, …). Pick one — the grid can be resized later.

---

Resizing the grid

Open Grid Resize Dialog (right-click any pane → Resize Grid, or from the command palette). You can change rows/cols on the fly. Existing panes are preserved when possible; panes that would fall outside the new grid get queued back to "unassigned" until you re-place them.

For non-uniform sizing, drag the gutter between two rows or two columns directly in the workspace. Drag is real-time — release to commit. Sizes are stored as fractional weights, so they survive window resizes.

---

Drag-and-drop pane swap

Grab a pane by its label (top strip) and drop it on another pane. The destination highlights in Carolina blue while you hover. Release to swap.

This is reversible — the swap just exchanges position fields on the two PaneConfig records and re-saves the workspace.

---

Multiple workspaces

The workspace tab bar at the top of the window lists every workspace. Click to switch, drag to reorder. Hotkeys:

Ctrl+1 … Ctrl+9	Switch to workspace N
Ctrl+Tab / Ctrl+Shift+Tab	Next / previous
Ctrl+T	New
Ctrl+W	Close (prompts)

PTYs survive workspace switch

When you switch workspaces, the terminals in the previous one keep running. Their PTYs are backgrounded, not killed. Switch back and your htop, build job, or long-running stream is exactly where you left it. This was a deliberate change from earlier behavior — see the Changelog.

This means: closing the app doesn't kill PTYs either (until process exit). Reopening the app re-attaches to your workspaces and re-spawns the terminal UI; running PTYs reattach. SSH+tmux sessions reattach without any state loss.

---

Window state persistence

The main window's size, position, and maximized state persist across launches via WindowState (see src/shared/types.ts:386-394). Move the window to your second monitor, maximize, quit, relaunch — you land where you left off.

If the saved position is off-screen (you removed a monitor), the window falls back to the primary display centered.

---

Workspace export / import

From the Settings dialog (Ctrl+P → "settings", or the gear icon in the status bar):

• Export current workspace — downloads a <name>.clusterspace.json file containing the grid, panes, and template references. Does NOT include running PTY state, SSH credentials, browser cookies, or anything secret.
• Import workspace — pick a .clusterspace.json to load it as a new workspace. Useful for sharing layouts with teammates.

---

See also

• Terminal-Panes — per-pane terminal configuration
• Per-Pane-Tabs — multiple tabs inside a single pane
• Browser-Panes — pane type beyond terminals
• Settings-and-Configuration — global app settings