Workspaces

atrium organizes work in four levels: workspaces group projects, projects contain rooms, and rooms tile panes.

Workspace: "Client work"          ← switchable group, own icon + accent
├── Project: ~/dev/acme-api       ← binds to a directory on disk
│   ├── Room: "main"              ← a tab, with its own mosaic
│   │   ├── Pane: editor (src/main.rs)
│   │   └── Pane: terminal (running an agent)
│   └── Room: "docs"
│       └── Pane: markdown (README.md)
└── Project: ~/dev/acme-web
    └── Room: "review"
        └── Pane: source control

Workspace: "Personal"
└── Project: ~/dev/side-thing

This page covers the top level. See Projects for the directory-bound unit, Rooms & wings for tabs, and Panes & mosaic for the layout tree.

Changed in v0.195.0. Before that release there was no grouping layer — "workspace" and "project" meant the same thing. If you have notes or scripts from before then, read their "workspace" as today's project. The internal symbols still carry the old vocabulary; see Naming.

What a workspace is

A workspace is a switchable, named group of projects. It owns no directory of its own — it is a lens over the projects you put in it. Switching workspaces re-scopes the sidebar, the project list, and Cmd+1…Cmd+9 to that group's projects.

Each workspace has:

• A name and an icon — emoji, any lucide-react glyph, or a custom picture.
• An accent color, scoped to that workspace's chrome while it is active. It never overwrites the theme's global accent.
• A membership list of projects. Every project belongs to exactly one workspace.
• Focus memory — the project (and pane) you were last on in that workspace, restored when you switch back to it.

Every install starts with one workspace called Main. Projects live there until you make another.

The workspace rail

The rail sits at the bottom of the Home sidebar: one round icon per workspace, the active one enlarged. It shrinks to fit rather than overflowing into a menu, so every workspace stays reachable at a glance.

• Click an icon to switch.
• Right-click an icon to edit that workspace's name, icon, and accent.
• + creates a new workspace — a name + icon + accent dialog with a live preview. There is no project-directory field; a new workspace starts empty and shows a New Project call-to-action.

Switching

Switching is a pager, not just a click target. The rail, the sidebar body, and the gradient wash all move together:

• Click a rail icon.
• Swipe horizontally with two fingers on the sidebar. This is a real macOS gesture — 1:1 tracking, peek-and-reverse, and it only commits when you lift. A horizontal-dominance guard keeps vertical scrolling from triggering it.
• ← / → or the scroll wheel over the sidebar.

The Home sidebar's project list pages along with the switch, and the destination workspace's active pane takes focus.

Moving a project between workspaces

Right-click a project row in the sidebar → Move to workspace ▸. The submenu lists every workspace plus New workspace….

Worktrees are not listed: a worktree always inherits its parent project's workspace and cannot be moved independently.

Removing a workspace never deletes anything — its projects move to the default workspace.

From the CLI

The CLI namespace is collection (the internal name for this layer). Mutations require the app UI to be running.

atrium collection list                          # every workspace + project counts
atrium collection create <name>
atrium collection rename <ref> <new-name>
atrium collection remove <ref>                  # projects fall back to the default
atrium collection switch <ref>
atrium collection move-workspace <project> <workspace>

atrium workspace list --collection <ref>        # projects in one workspace

<ref> resolves by name, id, or unique id prefix. collection list and workspace list agree on membership — the read path resolves each worktree to its parent's workspace before reporting.

Naming: internals vs. UI

The v0.195.0 restructure reclaimed the user-facing words without renaming a single symbol. That mismatch is deliberate and permanent, so it is worth knowing when you read JSON, env vars, or CLI flags:

You see in the UI

Internally it is called

Workspace	collection — collectionId, atrium collection, CollectionMeta
Project	workspace — $ATRIUM_WORKSPACE_ID, --workspace, ~/.atrium/workspaces/
Room	tab — tabs, TabSnapshot, $ATRIUM_TAB_ID

So atrium workspace list lists projects, and atrium collection list lists workspaces. See Data directory for where each lands on disk.