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. The Glossary shows where projects sit among the other levels.

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 local computer, SSH server, or paired computer 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.

On a paired Mac or Windows PC, choose Bind and select an existing folder on that computer. Folder completion reads the destination's directories. Cloning through the New Project dialog requires an SSH server location.

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.

The project menu offers Copy to another location…, or Copy to this Mac… for a remote project, where the destination supports copying over SSH. The dialog chooses the destination and links the resulting copy to its source. Each copy continues to own its own files and sessions.

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.

Related copies share the project's chosen icon. Remote project favicons are read from the machine that owns them; the path does not have to exist locally. Remote machine sections also show that machine's workspace groups and wing icons.

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
atrium worktree gc --dry-run      # preview stale atrium records

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 refresh after external git changes. On startup and window focus, atrium also forgets stale worktree records whose directories are gone, provided the parent still exists; unmounted volumes are skipped and an undo notice is offered. atrium worktree gc runs that cleanup explicitly. This differs from worktree prune, which removes unbound worktrees that still exist on disk.

Move an existing conversation

Use Move to worktree in an agent chat's attachment menu to continue the conversation in a new or existing worktree. Choose the branch and base for a new checkout, and optionally select uncommitted changes to copy. No files are selected by default, and source files stay in place.

An active agent finishes its turn before moving and receives a prompt to continue in the destination. An idle conversation stays idle. See Agent chat for the conversation controls.

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.