Projects

What a project is

A project is a folder or Git repository on one device: your Mac, or a paired device. A Git project can have many workspaces, each on its own branch. A folder project has exactly one workspace, the folder itself.

Adding a project

Add a project from the "New project" button in the Projects header. The flow has three steps, each fixed once you make a choice:

• • Device: skipped when your Mac is the only device. An offline device is shown disabled.
• • Source: "Existing folder" (a path field with directory autocomplete on the chosen device) or "Clone a repo" (a Git URL). Continue reads any spaces.yaml it finds: for a folder, from the folder itself; for a repo, straight from its declared default branch, without cloning anything yet.
• • Configure: the setup script, stop script, services, processes, and browser sessions, prefilled from that spaces.yaml or empty with a note that none was found.

Create clones the repo when the source was a Git URL, creates the default workspace, and saves the settings you were shown, not a re-read of the file, so canceling any earlier step leaves nothing behind. If a managed clone from an earlier attempt already exists but is not registered to any project, Continue asks first before Create replaces it.

A folder has to be a Git repository's root, or a folder that isn't in a Git repository at all. Spaces turns down a subfolder of a repository or a worktree, including a workspace's own folder, and tells you which project already has it or which folder to add instead. Adding something that is already a project tells you which one.

A coding agent or script can add a project with spaces project create (see CLI) or the spaces_project_create MCP tool. There is no Configure step: any spaces.yaml is used as found, and you can change the settings afterwards. Neither replaces leftover managed clone folders; add that project from the app instead, which asks first.

Git and folder projects

A Git project's default workspace is the existing folder itself when you added one that way, or, when you cloned a repo, a worktree of the declared default branch checked out from the managed clone Create made. Every other workspace is a worktree on its own branch, sharing the project's one clone, in a folder Spaces manages, kept separate from the default workspace's folder. A folder project's single workspace is the folder itself.

The default workspace

Every project has a default workspace, listed first, that can't be deleted on its own; delete the project to remove it. For a Git project added as an existing folder, it's the folder itself, labeled with the repository's declared default branch. For a cloned repo, it's a worktree of the declared default branch. A folder project has no repository branch to label its workspace with: its one and only workspace is the folder itself, labeled with the folder name.

Project settings

The row's settings action (a gearshape icon) opens a dialog: setup script, stop script, services, processes, and browser sessions. Save persists your edits. Import and export spaces.yaml from the same dialog (see spaces.yaml: Import and export). After an import on a Git project, Save offers "Update All Workspaces" or "Project Only"; saving without an import never rewrites existing workspaces. A folder project has no separate workspace settings: its settings dialog edits its one workspace directly.

The home workspace (~)

Every device has one, at the top of its sidebar section, rooted at your home directory, for terminals that belong to no project. It has no settings, can't be deleted, and can be hidden.

Hiding a project

A project hides the same way a workspace does; see Workspaces: Hiding.

Deleting a project

Deleting a project stops everything it is running, removes the automations attached to its workspaces, removes its Git worktrees, and, if Spaces cloned the repository, removes the managed clone. A folder or repository you pointed Spaces at directly is left on disk. The default workspace goes with the project; there is no separate confirmation for it.