Workspace
Workspaces
A workspace is Swarm’s saved project context. It gives a local folder a stable identity and display name, can include linked directories and workspace-specific presentation, and keeps Terminal UI and Desktop sessions attached to the same project context.
Saved context
A workspace is metadata around your folder, not a copy of your project.
A saved workspace is an account-scoped record for a local folder. Swarm keeps its stable workspace identity, primary path, display name, linked directories, order, optional icon and theme, and workspace definition state. The current selection is saved per user, while sessions retain the workspace identity, path, and name they were created with.
Removing a workspace from Swarm removes saved workspace metadata only. It does not delete the folder or files on disk.
Workspace-aware file tools are scoped to the primary folder and linked directories. Bash permissions are a separate safety boundary, not a filesystem sandbox, so review command requests carefully in high-risk environments.
Fields
What Swarm persists for a workspace
workspace identityA stable, account-scoped ID that keeps sessions and workspace bindings attached to the same saved project.pathThe primary local folder. It is always part of the workspace and cannot be removed as a linked directory.workspace_nameThe human-readable name shown in workspace lists, session headers, and Desktop routes.directoriesThe primary folder followed by any linked folders. A path inside any of these roots resolves to this workspace.presentationAn optional PNG icon and workspace theme. A blank theme inherits the global theme.workspace definitionAn optional generated project summary with pending, completed, or failed analysis state.order and selectionSaved ordering is account-scoped; the current workspace selection is persisted per user.worktree settingA workspace-scoped default that can route new sessions into an isolated Git worktree.Commands
Terminal workspace commands
/workspace/workspaces is an alias./workspace save [path|#n]/workspace select <name|#n>/workspace scan [query]/add-dir [path]Switching to another workspace is unavailable while a run is active. A successful TUI switch selects the saved workspace and opens a fresh chat draft for it rather than moving the active session.
Temporary folders
You can use a folder before saving it as a workspace.
Desktop can use a browsed local folder as temporary context and promote it later. Temporary use gives the current Desktop view a workspace path, but it does not add a saved workspace record or persist a current workspace binding.
Save the folder to make it durable. Saved workspaces appear in the workspace list, can be reordered, can include linked folders, and can carry an icon, theme, definition, and worktree default.
TUI and Desktop
Both surfaces use the same saved workspace records.
Terminal UIThe launch directory resolves to a saved workspace when it is inside that workspace’s primary or linked roots. Otherwise, the TUI offers a save-and-switch setup flow. Use /workspace or /workspaces for ongoing management.DesktopThe workspace home lists saved and discovered folders, provides a folder browser, and supports adding, opening, editing, reordering, or removing saved workspace metadata. A folder can also be used temporarily before it is saved.Shared runtimeBoth surfaces call the same account-scoped workspace APIs. Selecting a saved workspace updates the same per-user current binding, and new sessions are created with that workspace’s identity, path, and name.Desktop navigation uses workspace routes rather than treating the shell directory that launched Desktop as a saved workspace. Choose an existing workspace, add a folder, or use a folder temporarily.