atriumatrium

Workspaces & rooms

How atrium organizes projects, tabs, and panes.

atrium has three levels of organization: workspaces, rooms, and panes.

Workspace

A workspace is a project. It binds to a directory on disk (typically a git repository) and owns the layout, rooms, panes, and task cards scoped to that project.

Each workspace has:

  • An immutable UUID and a user-editable name.
  • A projectDir — the absolute path of the project root. The file tree, git panel, and terminal working directories default to this path.
  • A list of rooms.
  • A custom icon — emoji or any lucide-react glyph. Right-click the workspace row in the sidebar → Customize icon to pick one; the icon shows up in the sidebar (collapsed and expanded), the activity sidebar group header, and the workspace dropdowns in the task panes. With no custom icon, workspaces fall back to a deterministic hash color.
  • Worktree linkage: a workspace can be marked as a git worktree of a parent workspace. Worktree children appear nested under their parent in the sidebar.
  • A hidden-from-sidebar flag, set from the workspace row's context menu, for projects you want bound to atrium without cluttering the sidebar.
Workspaces are stored as snapshots under ~/.atrium/workspaces/{id}/workspace.{timestamp}.json. Multiple timestamped snapshots are retained for recovery.

Creating and switching

  • Cmd+Shift+N opens the new workspace dialog.
  • Cmd+1 through Cmd+9 switch to top-level workspaces by index (worktrees excluded from numbering).
  • The activity sidebar lists all workspaces; click a row to switch.
  • atrium workspace create --name <name> --dir <path> from the CLI.

Room

A room is a tab inside a workspace. Each room has its own pane layout (the mosaic). One room is active per workspace at any time.

In the UI they are called rooms. The backend and persisted data still use the term tab internally, so if you look at a workspace snapshot JSON you will see tabs / TabSnapshot.

Creating, switching, closing

  • Cmd+T creates a new room.
  • Cmd+Shift+[ / Cmd+Shift+] switch to the previous / next room.
  • Cmd+Shift+P pins the current room so it sticks to the left of the room strip.
  • Cmd+Shift+W closes the current room. Closing the last room in a workspace opens a fresh empty room in its place so the workspace is never left without one.
  • Cmd+Shift+T opens the Omni menu for fuzzy-jumping to any room across any workspace.
  • atrium room list and atrium room switch <id> from the CLI.
Task-launched rooms get their name set to the task number and title (for example ATR-42 - Fix the auth middleware) so you can tell agent rooms apart from ad-hoc ones.

Pane

A pane is one tile in the mosaic. Panes are typed — terminal, editor, markdown editor, browser, source control, search, tasks list, task detail, diff review, image viewer, snapshot diff viewer. Each pane type is documented in Panes.

Panes live inside a room. Splitting a pane puts two panes side-by-side (or top-and-bottom) in the mosaic tree for that room. Panes of the same type can be grouped as subtabs under a single header.

How the three compose

Workspace  (e.g. ~/dev/atrium)
├── Room: "main"
│   ├── Pane: editor (src/main.rs)
│   └── Pane: terminal (running an agent)
├── Room: "docs"
│   └── Pane: markdown (README.md)
└── Room: "browser"
    └── Pane: browser (localhost:5173)

Every level is journaled. Opening atrium after a quit or crash restores all three.

Worktrees

atrium integrates with git worktrees: a workspace can be a worktree of another workspace, pointing at a different branch in a separate directory. The sidebar nests worktree workspaces under their parent. This makes parallel-branch workflows explicit without leaving the project context.

The branch selector and the worktree menu watch the workspace's resolved git directory via fs::watch, so external git operations — a git checkout in a terminal pane, a worktree added by another tool, a branch deleted via the GitHub CLI — refresh the UI in near real-time without a manual reload. Window-focus events also trigger an orphan-rescan so worktrees deleted while atrium was in the background fall off the list when you come back.