Skip to main content
Spaces are workspaces within a profile that let you organize tabs by project, topic, or context. Each Space has its own set of tabs, visual theme, and icon, making it easy to switch between different tasks.

​
Overview

Spaces help you:

Organize Tabs

Group related tabs together by project or topic

Visual Separation

Customize each Space with unique colors and icons

Quick Switching

Switch between Spaces with keyboard shortcuts (Ctrl+1-9)

Profile Isolation

Each Space belongs to a specific profile

​
Creating and Managing Spaces

1

Access Space Management

Open Settings (Cmd/Ctrl + ,) and navigate to the Spaces section
2

Create a New Space

Click “Create Space” and give it a descriptive name
3

Customize Appearance

Choose an icon from the Phosphor Icons library and set a background gradient
4

Start Using

Switch to your new Space and start opening tabs

​
Space Data Structure

Each Space stores the following data (src/main/controllers/spaces-controller/raw.ts): 
interface SpaceData {
  profileId: string;     // Parent profile ID
  name: string;          // Display name
  icon?: string;         // Phosphor icon name (PascalCase)
  theme?: SpaceTheme;    // Visual customization
  order: number;         // Sort order
  lastUsed: number;      // Timestamp for auto-switching
  createdAt: number;     // Creation timestamp
}

​
Switching Between Spaces

​
Keyboard Shortcuts

Spaces can be quickly accessed using keyboard shortcuts:
ShortcutAction
Ctrl + 1Switch to Space 1
Ctrl + 2Switch to Space 2
Ctrl + 3Switch to Space 3
……
Ctrl + 9Switch to Space 9
Shortcuts are generated in the application menu at src/main/controllers/app-menu-controller/menu/items/spaces.ts:132
Spaces appear in the application menu with:
  • Visual icons (on macOS using SVG rendering)
  • Checkmark indicating the currently active Space
  • Keyboard accelerators displayed

​
Space Icons

Spaces support icons from the Phosphor Icons library. The icon system:
  • Uses duotone style icons
  • Converts PascalCase names to icon paths
  • Renders as white SVG on macOS menu items
  • Falls back to “dot-outline” if icon not found

​
Icon Implementation

The icon rendering is handled at src/main/controllers/app-menu-controller/menu/items/spaces.ts:23-104: 
function getPhosphorIconPath(pascalName: string): string | null {
  const name = getIconNameFromPascalCase(pascalName);
  // Resolves to @phosphor-icons/core/assets/duotone/{name}-duotone.svg
}

​
API Operations

The Spaces system provides the following IPC handlers for renderer processes:
Get all Spaces across all profiles
const spaces = await window.flow.spaces.getAll();
Get all Spaces within a specific profile
const spaces = await window.flow.spaces.getFromProfile(profileId);
Create a new Space in a profile
const success = await window.flow.spaces.create(profileId, spaceName);
Update Space properties like name, icon, or theme
await window.flow.spaces.update(profileId, spaceId, { name: 'New Name' });
Delete a Space and all its tabs
await window.flow.spaces.delete(profileId, spaceId);
Switch the current window to a different Space
await window.flow.spaces.setUsing(profileId, spaceId);

​
Space Controller Architecture

The SpacesController at src/main/controllers/spaces-controller/index.ts:25 manages all Space operations:

​
Caching Strategy

  • Spaces are lazily loaded per-profile
  • In-memory cache avoids repeated disk reads
  • Cache invalidation on update/delete operations
  • Automatic reconciliation when data changes

​
Event System

The controller emits events for state changes: 
type SpacesControllerEvents = {
  'space-created': [profileId, spaceId, spaceData];
  'space-updated': [profileId, spaceId, updatedFields];
  'space-deleted': [profileId, spaceId];
  'requested-all-spaces-from-profile': [profileId];
}
These events trigger UI updates via the IPC message system at src/main/ipc/session/spaces.ts:57-62: 
spacesController.on('space-created', fireOnSpacesChanged);
spacesController.on('space-updated', fireOnSpacesChanged);
spacesController.on('space-deleted', fireOnSpacesChanged);

​
Window-Space Relationship

Each browser window tracks its current Space: 
// Get current Space for a window
const currentSpaceId = window.currentSpaceId;

// Set Space for a window
window.setCurrentSpace(spaceId);
Implementation at src/main/ipc/session/spaces.ts:52-55: 
export function setWindowSpace(window: BrowserWindow, spaceId: string) {
  window.setCurrentSpace(spaceId);
  window.sendMessage('spaces:on-set-window-space', spaceId);
}

​
Space Ordering

Spaces can be reordered within a profile using the reorder operation: 
const orderMap = [
  { profileId: 'main', spaceId: 'space-1', order: 0 },
  { profileId: 'main', spaceId: 'space-2', order: 1 },
  { profileId: 'main', spaceId: 'space-3', order: 2 },
];

await spacesController.reorder(orderMap);
This updates the order field for each Space and re-sorts the display order.

​
Last Used Space

The system tracks when Spaces were last accessed: 
// Update last used timestamp
await spacesController.setLastUsed(profileId, spaceId);

// Get most recently used Space
const lastSpace = await spacesController.getLastUsed();

// Get most recently used Space in a profile
const lastProfileSpace = await spacesController.getLastUsedFromProfile(profileId);
This enables features like “restore last Space” when opening a new window.

​
Default Space Creation

When a new profile is created, a default Space is automatically created with the same name as the profile (src/main/controllers/profiles-controller/raw.ts:94-99): 
if (shouldCreateSpace) {
  await spacesController.create(profileId, profileName).then((success) => {
    if (!success) {
      debugError('PROFILES', `Error creating default space for profile ${profileId}`);
    }
  });
}

​
Use Cases

Project Organization

Create separate Spaces for each project you’re working on

Context Switching

Quickly switch between work, research, and entertainment contexts

Research

Keep related research tabs together in a dedicated Space

Development

Separate development, staging, and production environments
  • Profiles - Spaces exist within profiles
  • Tabs - Tabs are organized within Spaces
  • Shortcuts - Keyboard shortcuts for Space switching

Build docs developers (and LLMs) love

Get started for freeTalk to us