Projects: bind a folder to rooms, panes, and tasks

A project binds to a directory on disk (typically a git repository) and owns the layout, rooms, panes, and task cards scoped to it. It is the unit you actually work in; workspaces are the switchable groups projects live in.

Each project has:

• An immutable UUID and a user-editable name.
• A projectDir — the absolute path of the project root. The file tree, source-control panel, and terminal working directories default to this path.
• A location — the Mac or SSH-connected box that owns its directory, daemon, panes, and sessions.
• A list of rooms.
• The workspace it belongs to (exactly one).
• An icon — see Project icons.
• Worktree linkage, if it is a git worktree of another project.
• A hidden-from-sidebar flag, set from the project row's context menu, for projects you want bound to atrium without cluttering the sidebar.

Creating and switching

• Cmd+Ctrl+N opens the New Project dialog.
• Cmd+1 through Cmd+9 switch to projects by index within the active workspace (worktrees excluded from numbering).
• The Home sidebar lists the active workspace's projects; click a row to switch.
• Home may show several workspace and location sections at once. Drag a project between workspace sections to reorganize it; location is not changed by that gesture.
• atrium workspace create --name <name> --dir <path> from the CLI. (The CLI calls projects workspace — see Naming.)

For a project on another box, choose its location during creation or target the command with atrium --location <name> workspace create …. The owning location is marked in project pickers and breadcrumbs when it is not local.

Copies on other locations

The same repository can be represented by separate projects on several machines. atrium links related copies as kin without treating their files as one shared filesystem. Each copy keeps its own path, rooms, panes, worktrees, branches, and sessions.

When a room launches or controls work against a related copy, its breadcrumb shows Acting on and the destination location. Creating or materializing a copy is an explicit launch preflight; atrium does not silently upload the current working tree to an unknown box. See Locations → Projects and copies.

Project icons

Right-click the project row in the sidebar → Edit to set the icon. Three sources, in order of specificity:

1. A custom glyph — an emoji or any lucide-react icon.
2. The project's favicon — toggle Use project favicon and atrium searches the repo (public/, static/, app/, and the repo root) for one, then loads it off disk. If the file later stops resolving, the icon falls back to the default glyph rather than breaking.
3. A deterministic hash color, when you set neither.

The icon renders everywhere the project appears: the sidebar (expanded and collapsed), the activity sidebar's group headers, and the project dropdowns in the task panes. It also carries the activity pulse while agents are working in that project — including favicon icons, which are letterboxed into the pulse's sprite slicer.

When the directory moves

Rename or move a project's folder outside atrium and the project would otherwise be stranded: its rooms, panes, scrollback, and file-tree state stay under the old id while the renamed path opens as a brand-new empty project.

atrium detects the missing directory and replaces the mosaic with a notice offering Locate…. Point it at the new path and the project is repointed in place, rebasing the absolute paths that lived under the old directory (pane working directories, expanded tree paths) while leaving anything outside it alone.

One caveat the notice states directly: agent sessions do not resume across a move. Some harnesses key their session history to the folder path, so the lossless recovery is to rename the folder back.

Worktrees

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

• A worktree inherits its parent's workspace and cannot be moved to another one.
• Create and delete are non-blocking — the sidebar shows in-flight state while git works, so the UI never freezes on a slow checkout.
• Mark a worktree done to fold it into a collapsible group instead of deleting it.

atrium worktree create --branch <name>
atrium worktree list
atrium worktree remove <ref>
atrium worktree adopt <path>      # bind a worktree git already knows about
atrium worktree prune

Always create worktrees through atrium rather than bare git worktree add — the CLI binds a child project, copies .worktreeinclude, and runs post-create setup. A bare git worktree leaves an orphan atrium cannot see (atrium worktree adopt is the recovery).

The branch selector and worktree menu watch the project'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.

Persistence

Local projects are stored as snapshots under ~/.atrium/workspaces/{id}/workspace.{timestamp}.json. A remote project's snapshots live in the remote location's atrium data directory and are served by that location's daemon. Multiple timestamped snapshots are retained for recovery. See Persistence & recovery, Locations, and Data directory.