Workspaces
A workspace is a named container that groups one or more project directories together. While sessions are the atomic unit of work, workspaces are the organizational unit — they let you gather all the sessions that belong to a project (or a set of related projects) under a single label.
What is a workspace?
Section titled “What is a workspace?”A workspace stores:
| Field | Description |
|---|---|
id | Stable UUID assigned at creation |
name | Display name shown in the UI |
paths | Flat list of directory paths (backward-compat; derived from projects) |
projects | Structured list of WorkspaceProject entries, each with a path, name, and optional git repo info |
pinned | Whether the workspace is pinned to the top of the list |
settings_overrides | Per-workspace settings that override global defaults (e.g. default provider, permission preset) |
provider_account_overrides | Per-provider account selection for sessions in this workspace |
auto_created | true when Magia created the workspace automatically from a directory |
Workspaces are persisted by the Rust backend in workspaces.json inside Magia’s app data directory. The Zustand store (useWorkspacesStore) is an in-memory cache backed by four Tauri commands: get_workspaces, save_workspace, delete_workspace, and merge_workspace_paths.
How sessions map to workspaces
Section titled “How sessions map to workspaces”A session belongs to a workspace when its projectPath matches one of the paths registered in the workspace. The mapping is resolved by the backend command resolve_workspace_for_session, which normalizes both paths before comparing. Magia calls resolve_workspaces_batch at startup to bulk-resolve all known sessions.
Sessions can belong to exactly one workspace (the first matching one found), or to no workspace at all. Sessions without a workspace match are visible in the global “All Sessions” view.
Auto-creation from a directory
Section titled “Auto-creation from a directory”When you open a new session for a directory that does not yet have a workspace, Magia can automatically create one. The auto_create_workspace Tauri command derives a name from the directory basename and marks the workspace with auto_created: true. Auto-created workspaces behave identically to manually created ones and can be renamed or deleted freely.
Workspace display modes
Section titled “Workspace display modes”There are two ways to navigate workspaces, controlled by the workspaceDisplayMode setting:
| Mode | Behaviour |
|---|---|
tabs | Each workspace appears as a tab along the top of the session sidebar. Clicking a tab filters the sidebar to only sessions in that workspace. |
sidebar | Workspaces are listed in the sidebar navigation; selecting one filters the session list below. |
The mode can be changed at any time in Settings → General → Workspace display.
The workspacesEnabled flag controls whether the workspace feature is active at all. When disabled, all sessions are shown in a flat list regardless of their project directory.
CRUD operations
Section titled “CRUD operations”Create
Section titled “Create”Use the New Workspace button in the workspace panel or let Magia auto-create one when you open a session in an unregistered directory. Programmatically, call createWorkspace in the store — it generates a UUID, timestamps the record, and persists it via save_workspace.
Update the name, icon, color, description, or per-workspace settings via the workspace settings sheet. Path membership can be extended with mergeWorkspacePaths, which appends new paths without removing existing ones.
Delete
Section titled “Delete”Deleting a workspace removes the container only — the sessions and their underlying project directories are not affected. Sessions that were in the deleted workspace will appear in the unassigned pool.
Per-workspace provider accounts
Section titled “Per-workspace provider accounts”Each workspace can pin a specific provider account for each provider (e.g. a “work” Claude account for the ~/work/project workspace). This is stored in provider_account_overrides as a map of providerId → accountId and applied when a new session is created inside that workspace.
Workspace icons and colors
Section titled “Workspace icons and colors”Workspaces support an emoji icon, a hex color accent, and a icon_image (base64 data URL, 512×512) for custom image icons. These are purely cosmetic and help distinguish workspaces at a glance in the tab bar or sidebar.