Contexts

Contexts are a layer of organization between workspaces and panes. Each workspace can contain multiple contexts, and each context has its own independent pane layout, working directory, color tint, and icon. Think of them as sub-workspaces -- lightweight enough to create freely, powerful enough to keep unrelated tasks completely separated within a single project.

What Contexts Are

Within a workspace, contexts provide independent layout environments:

Workspace: "Backend Project"
  +-- Context: "Development" (blue tint)
  |     +-- Terminal: server
  |     +-- Terminal: logs
  +-- Context: "Testing" (green tint)
  |     +-- Terminal: unit tests
  |     +-- Terminal: integration tests
  +-- Context: "Agent Team" (orange tint)
        +-- Terminal: Claude agent 1
        +-- Terminal: Claude agent 2
        +-- Terminal: Orchestrator

Each context owns its own independent pane layout. Splitting, zooming, and rearranging panes in one context does not affect any other context.

Multi-Context Workspaces

The context tab bar appears below the workspace tab bar, showing all contexts for the active workspace. This gives you a clear two-level navigation hierarchy:

• Top bar: Workspaces (projects)
• Second bar: Contexts (tasks within a project)

Creating Contexts

When creating a context, you can set:

• A name for the context tab
• An optional CWD that overrides the workspace default
• An optional color tint and icon

Switching Contexts

You can also click context tabs directly. Switching is instant because layouts persist in memory after first activation.

Tip: Alt+1 through 9 switches by position in the context tab bar, similar to how Ctrl+Shift+1-9 works for workspaces.

Per-Context Settings

Tip: Use context colors to create a visual system. For example: blue for development, green for testing, orange for agent teams, red for production monitoring. You can tell at a glance which context is active.

Context Decorations

Context tabs can display decorations -- badges and status colors that convey information at a glance:

Decorations update in real time as agent states change.

Context Tab Bar

The context tab bar supports several organizational features:

Independent Layouts

Each context owns its own pane layout. This means:

• Pane arrangements in one context do not affect another
• Splitting, zooming, and rearranging are all scoped to the active context
• Each context can have a completely different layout topology -- one might be a single pane, another a 2x2 grid, another a 3-panel setup
• Layout presets can be applied independently per context

Cross-Context Pane Transfer

Drag a pane from one context to another within the same workspace. The terminal session stays alive during the transfer -- no output is lost, no process is restarted.

This is useful when you:

• Start work in one context and realize it belongs in another
• Want to reorganize panes after an agent team finishes
• Need to move a monitoring terminal to a dedicated context

Context Popout

Press Ctrl+Shift+O to detach the current context into a separate OS window. The context runs independently with its own window. When you close the popout window, the context automatically returns to the main Mosaic window.

Use cases:

• Second monitor: Put a monitoring or agent context on another display
• Side-by-side with other apps: Keep an agent team visible next to your IDE
• Presenting: Show terminal output without the full Mosaic chrome
• Focus mode: Isolate a context for distraction-free work

Efficient Memory Usage

Contexts are created on demand for performance. The pane layout is not initialized until the context is activated for the first time. This means:

• Creating many contexts has minimal memory cost until they are used
• The first activation has a brief setup delay, then subsequent switches are instant
• Inactive contexts consume no rendering resources

After first activation, context layouts persist in memory, so switching between previously-visited contexts is always instant.

Use Cases

Contexts shine when you need to separate concerns within a single project:

Development + Testing

One context for your development terminals (server, watcher, editor), another for running test suites. Switch between them instantly without losing layout state.

Agent Teams

Dedicate a context to an agent team with its own layout and color tint. When you create an agent team, Mosaic automatically creates a dedicated context for that team, with each agent getting its own pane.

Server + Client

Front-end dev server in one context, back-end in another. Each has its own CWD pointing to the right directory.

Research + Implementation

Keep reference terminals, documentation, and log viewers open in one context while coding in another. Context popout lets you put the reference context on a second monitor.

CI/CD Monitoring

A dedicated context with tailing build logs and deployment terminals, colored red or orange for quick identification.

All Context Shortcuts

Related Pages

• Workspaces -- the top-level organizational unit that contains contexts
• Panes & Tabs -- splitting, zooming, and managing panes within a context
• Agent Orchestration -- running multi-agent teams in dedicated contexts
• Getting Started -- installation and first steps