Workspaces

What a workspace is

A workspace is one branch of a Git project, in its own worktree and directory, with its own ports, processes, browser sessions, and terminals. A folder project has exactly one. The home workspace (~) holds terminals only.

Creating

For a Git project, create a workspace from the "+" on its row ("New workspace in <project>") or with ⌘N, choosing "Create branch" (a branch name and a base branch) or "Use existing" (pick a branch), plus optional notes. A folder project that isn't a Git repository has only its one workspace and offers no "New workspace" action. There is no separate title or directory-name field: Spaces generates a directory name on its own, independent of the branch name, and it isn't editable; the sidebar shows the branch name. A workspace created on the iPhone always branches from the project's default branch. From the CLI, see CLI: Workspaces.

Existing worktrees

A worktree you create with git outside Spaces, on a named branch, appears as a workspace on its own. A worktree on a detached HEAD is skipped. A non-default workspace whose worktree is gone is removed automatically; one whose directory still exists on disk keeps its record even when git's own listing omits it.

Setup

A workspace's setup script runs before anything else launches, right after it is created. While it is pending, running, or failed, the workspace shows a setup screen instead of its panel: status, timestamps, exit code, error text, and a log tail, with Retry, Reveal in Finder, an ad hoc terminal for repairs, and copy/open actions for the log. After a failure you can also edit the setup script before retrying. Processes and browser sessions wait until setup succeeds.

Workspace settings

Per-workspace browser sessions, processes, services, a stop script, and a read-only Environment section (see Environment variables). Editing settings while a workspace is running never starts or stops anything on its own: a process name or on-exit edit updates the running process immediately, while a command edit asks you to confirm before restarting it.

Notes

Your own free-text notes on a workspace, on the Mac. Set them from the Notes field when creating a workspace, or edit them from the notes button in the workspace footer, which opens a popover (⌘↩ saves, Esc closes). The button shows a tint once notes exist and its tooltip previews them; empty, its tooltip reads "Add notes". The home workspace has none. Coding agents keep their own status in a brief; see Agent status: Agent briefs.

Start, stop, and restart

• • Start launches configured processes that aren't already running and leaves running ones alone; it never touches ad hoc terminals or agents. It's offered whenever something is left to start.
• • Stop ends the workspace's processes and terminal sessions, closes its panes and its Chrome tabs, then runs the stop script.
• • Restart relaunches every configured process, running the stop script first. Ad hoc terminals, agent sessions, and running automations are left alone.

Restarting, whether one process or a whole workspace and from any client, keeps each process's pane in place: the new session takes over the same tab and split, on every Mac and iPhone watching. A restart never opens a pane or moves focus, so a process without a pane stays without one, and a process that fails to come back keeps its pane showing where it stopped. Chrome tabs and the Editor stay open. Starting a workspace from the CLI or MCP never moves focus in the Mac app. See What survives a restart for quitting and rebooting.

Hiding

Hiding takes a workspace out of the sidebar and every other list, the command palette, Alerts, and the session picker, without asking first, and leaves everything in it running. An already-open panel for that workspace keeps its own session picker working, since hiding suppresses listings rather than closing panels. The Workspaces dialog (the "Filter workspaces" button in the Projects header) brings it back; on the iPhone, the Spaces tab's Workspaces sheet. Hidden on one client is hidden on both. Projects hide the same way: hiding a project takes it and every workspace under it off every list, without changing which of its workspaces were themselves hidden, so unhiding the project brings back exactly what was showing before.

Deleting

Deleting a non-default workspace stops its sessions and removes its worktree checkout from disk, including any uncommitted or untracked files in it. A confirmation names the workspace, with checkboxes to also delete the local branch and the remote branch, both off by default; those checkboxes only decide whether the branch itself is deleted. The default workspace can't be deleted; delete the project to remove it. While a delete is in progress, the row dims and shows a small progress mark in place of its status, and nothing on it can be acted on until it completes. Deleting removes the workspace's settings and port assignments with it.