Panes and the tiling mosaic layout
How atrium tiles terminals, agents, editors, and browsers into one room — splits, subtabs, drag-to-rearrange, and the pane lifecycle.
Inside a room, panes are arranged in a mosaic — a binary tree of horizontal and vertical splits, with panes at the leaves. You can split, swap, resize, maximize, and group panes without leaving the keyboard. The Glossary explains how panes, subtabs, and rooms relate.
Splitting
Keyboard examples below use macOS notation. See Shortcuts for Windows bindings.
Cmd+Dsplits the focused pane right (horizontal split — new pane to the right).Cmd+Shift+Dsplits the focused pane down (vertical split — new pane below).- Drag a pane header onto another pane's edge to drop into that zone (left, right, top, bottom).
- Drop onto the center of another pane's header to stack the pane as a subtab.
Resizing, swapping, equalizing
- Drag split dividers with the mouse or trackpad.
- Right-click a split divider for Swap, Equalize, and Lock/unlock.
- Maximize a pane (double-click its divider or use the pane header menu) to hide siblings. Restore with the same action.
Focus and navigation
Cmd+[/Cmd+]cycle focus to the previous / next pane within the room.- Click any pane to focus it. The focused pane shows a subtle accent ring.
atrium pane focus <id>from the CLI.
Subtabs
Panes can be grouped under one header slot. Drop a pane onto another pane's header to stack them, or choose New Subtab from the Pane menu.
- Click a subtab to switch to it.
- Drag a subtab within its strip to reorder it, or out to a split, another group, a room, a wing, or a sidebar dock. Dropping it on a composer inserts a reference.
- Close a subtab with the
×button; the group stays alive as long as another subtab exists.
Room rows and Activity cards can also be dragged onto a pane's edge to make a split, or its center to add a subtab. A drop on the chat composer inserts a reference to the item instead.
Pane identity
Each pane has an immutable UUID. The pane header displays an auto-generated title (for example editor: main.rs or Claude Code — session abc123). Override it with atrium pane rename <id> --name <name>; the custom title is persisted with the pane.
Lifecycle
- Create — opened by a keyboard shortcut, drag gesture, launcher action, or
atrium pane create. - Hide — a pane that sits in a room other than the active room is kept in the DOM so its state (scrollback, editor buffer, running process) survives instant switching.
- Unmount — after 10 seconds hidden, a pane's React components are unmounted to free memory. State is preserved and restored on remount.
- Close —
Cmd+Woratrium pane close <id>. Closing a pane with unsaved changes or a running process prompts for confirmation. - Error isolation — a crash in one pane does not propagate to other panes or the app shell.
Popout
Any non-browser pane can be popped out of the mosaic into a floating overlay layered above the mosaic but below toasts and dialogs. The pop-out button lives in the pane header; once detached, the pane keeps the same header (focus ring, split, search, close) so it behaves exactly like an in-mosaic pane — just floating. Popped panes can be docked back, hidden, or shown all-at-once via Expose mode. Position, size, and which panes are out persist across restarts. See Shortcuts → Pane popout for the full keyboard surface.
Persistence
The entire mosaic tree for each room is serialized to that room's snapshot. Pane-specific state (cwd, scrollback, session ID, editor buffer position, browser URL and history) lives in per-pane JSON inside the project snapshot. See Persistence & recovery.
File drop
Drag a file from Finder onto atrium:
- Dropped on the app with no existing pane for that file → opens an editor pane for it.
- Dropped on a pane's header → opens the file as a subtab under that header.
- Dropped on a pane's edge zone → opens the file as a new split.