Workspaces: named groups of projects

Workspaces are named groups of projects, each with its own icon and accent. Covers the Home workspace picker, showing several groups, moving projects, and the collection CLI.

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 named group of projects. It owns no directory of its own — it is a lens over the projects you put in it. Home can show several workspaces at once, while one remains active for project creation, keyboard switching, and context-sensitive actions.

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 picker

The active workspace row sits at the top of the Home sidebar. Click it to open the workspace picker:

Click a workspace row to make it active.
Check or uncheck its circle to show or hide that workspace's project section in Home. At least one stays visible.
Edit changes its name, icon, and accent; the same dialog can delete a non-required workspace.
New workspace opens 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.

In collapsed Home, the same picker opens from the active workspace icon. The sidebar can therefore stay as a 40 px rail without losing workspace management.

Switching

Switching changes the active workspace and restores its last-focused project and pane:

Pick it from the workspace picker.
Use the workspace actions in the command palette.
Use atrium collection switch <ref> from the CLI.

Showing a workspace and activating it are separate. A checked workspace can remain listed in Home while another workspace is active, which makes cross-workspace drag and drop possible without a switch first.

Moving a project between workspaces

Right-click a project row in the sidebar → Move to workspace ▸, or drag the project into another visible workspace section. The menu 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.