Workspaces

Workspace tab bar showing multiple workspaces with icons and color tints

Workspaces are Mosaic's top-level organizational unit. Each workspace is a fully independent environment with its own layout, contexts, working directory, background image, color tint, and icon. Terminal sessions stay alive across workspace switches -- nothing is ever interrupted when you change workspaces.

What Workspaces Are

A workspace in Mosaic owns one or more contexts, and each context owns its own independent pane layout. This hierarchy gives you:

Workspace
  +-- Context 1 (own layout, CWD, color)
  |     +-- Pane A
  |     +-- Pane B
  +-- Context 2 (own layout, CWD, color)
        +-- Pane C
        +-- Pane D

Each workspace is completely isolated. Layouts, contexts, background images, and settings in one workspace do not affect any other.

Creating Workspaces

Method	How
Keyboard	`Ctrl`+`Shift`+`N`
Command palette	`Ctrl`+`Shift`+`P`, then search "new workspace"

When creating a workspace, you can set:

A name for identification
An emoji or SVG icon from the categorized picker
A default working directory for new terminals
A color tint for the workspace tab

Switching Workspaces

Action	Shortcut
Switch to workspace 1	`Ctrl`+`Shift`+`1`
Switch to workspace 2	`Ctrl`+`Shift`+`2`
...	...
Switch to workspace 9	`Ctrl`+`Shift`+`9`

You can also click workspace tabs directly, or use the command palette to search and switch.

Tip: The Ctrl+Shift+1 through 9 shortcuts switch by position in the tab bar, not by workspace ID. If you reorder tabs, the shortcuts follow the new order.

Terminal Sessions Stay Alive

When you switch workspaces:

Terminal sessions keep running in the background -- long-running commands, builds, and agents continue uninterrupted
No terminal output is lost -- everything is buffered and waiting when you return
Switching is instant -- there is no teardown/rebuild delay

This is one of Mosaic's core design principles: workspaces are always alive, never paused.

Per-Workspace Settings

Default Working Directory

Set a default CWD for each workspace. Every new terminal opened in that workspace will start in this directory automatically.

To set it:

Right-click the workspace tab, or open workspace settings
Set the Default CWD to your project root directory
All new terminals and splits in that workspace inherit this directory

Tip: This is the single most useful workspace setting. Set it to your project root and never cd into it again.

Emoji and SVG Icons

Choose from a categorized icon picker with sections for Dev, Work, Creative, Nature, and more. Icons appear on the workspace tab for quick visual identification.

Color Tints

Apply a per-workspace color overlay to the workspace tab bar. Combined with icons, this creates a strong visual identity for each workspace, making it easy to tell at a glance which workspace you are in.

Background Image

Each workspace can have its own independent wallpaper set via a file picker. Combined with the wallpaper opacity slider (10-100%, independent of window opacity), you can create distinct visual environments for different projects.

Workspace Tab Bar

The workspace tab bar at the top of the window supports several organizational features:

Feature	Details
Drag reorder	Rearrange workspace tabs by dragging them to a new position
Hide/show	Hide a workspace from the tab bar without deleting it -- sessions and settings are preserved
Color tint	The tab bar reflects the workspace's chosen color for visual identification
Icon	Emoji or SVG icon displayed on the workspace tab
Cross-workspace transfer	Drag a pane tab onto a workspace tab to move it there

Tip: Hiding a workspace is useful for keeping your tab bar clean while preserving infrequently-used environments. Hidden workspaces can be shown again from the workspace management menu.

Layout Presets

Save and restore workspace layouts in Settings > Layouts:

Action	Description
Save	Capture the current layout as a named preset
Load	Apply a saved preset to the current workspace
Rename	Change the name of an existing preset
Delete	Remove a saved preset
Export	Save a preset as a JSON file for sharing or backup
Import	Load a preset from a JSON file

Quick layout presets (single, side-by-side, top/bottom, 2x2, 3-panel) are also available for instant layout switching without saving. See Panes & Tabs for details.

Per-Workspace Features

Several Mosaic features are scoped to the active workspace, giving you independent configuration per project:

Feature	Scope
Background image and opacity	Each workspace can have its own wallpaper and opacity level
Notification sounds	Override the default completion sound per workspace in Settings > Notifications
Snippets	Workspace-scoped snippets in addition to global ones
CI status monitoring	Configure a different GitHub repo and branch per workspace
Daily notes tasks	Tasks in the daily notes panel are per-workspace, per-date
Broadcast mode	`Ctrl`+`Shift`+`B` broadcasts keystrokes to terminals in the current workspace only
Contexts	Each workspace has its own set of contexts

Cross-Workspace Pane Transfer

Drag a pane tab to a workspace tab in the workspace bar to move that pane to a different workspace. The terminal session stays alive during the transfer -- no process is restarted, no output is lost. This is useful when you start work in one workspace and realize it belongs in another project.

Contexts -- organize panes into independent sub-environments within a workspace
Panes & Tabs -- splitting, zooming, rearranging, and tab management
Getting Started -- installation and first steps
Sidebar System -- the 4-slot dock layout for panels

Workspaces

On this page