Profiles

A profile is a saved arrangement of apps across Spaces: which app goes on which Space, how each Space is tiled, and what happens to apps the profile doesn’t mention. Profiles are JSON files in ~/.config/spacetile/profiles/, one per profile, so they can live in your dotfiles.

Making one

• Capture: the Profiles window (Edit Profiles… in the mini-map footer, or ⇧⌘P) → + → Capture Current Layout, Save Current Layout… in the mini-map, or spacetile-ctl capture <name>. This saves every Space’s windows and tiling. Visit each Space first, because Spacetile only knows how a Space is tiled once it has laid it out. Once a profile has been applied, or saved from the mini-map, Save Current Layout… first asks whether to save to that profile, replacing its windows and layouts and keeping its icon, shortcut and other settings, or to save a new profile. In the new-profile dialog, typing an existing profile’s name turns Capture into Replace, which updates that profile’s windows and layouts and keeps its other settings. Saving from the Profiles window or spacetile-ctl leaves the current profile as it was. spacetile-ctl capture overwrites without asking.
• Design: the Profiles window (Edit Profiles… in the mini-map footer, or ⇧⌘P) → + → New Profile, then build it in the designer.
• Duplicate: right-click a profile → Duplicate, then rename it with the pencil.

The designer

The sidebar lists the profiles, each with its icon. Right-click one to apply, rename, duplicate or move it to the Trash. New profiles record the displays connected now. The detail pane runs top to bottom in the order you build a profile: what it arranges, then how it behaves.

Picking the same app in two places means its first and second windows, in window-opening order. The designer hides the numbers.

Applying a profile

Five ways:

• Apply profile, in the designer;
• its row under Profiles in the mini-map;
• the profile’s shortcut;
• spacetile-ctl load <name>;
• automatically, if “Apply automatically” is on, when exactly the displays it was captured on are connected.

Applying does this:

1. Every window the profile names moves to its Space. A Space captured on a display that isn’t connected goes after the main display’s own Desktops, which is where macOS moves a disconnected display’s Desktops. A Space whose Desktop doesn’t exist is skipped, its windows stay where they are, and Spacetile says which.
2. Each Space takes the profile’s tiling.
3. Apps that aren’t running are launched, and their windows are placed as they appear.
4. A tile whose window isn’t there yet (its app is still launching, or the window sits on a Space Spacetile hasn’t shown since it started) stays empty, waiting for that app. The app’s next window on that Space fills it, however long that takes, and other apps’ windows never do. The wait ends if a window on that Space closes or another profile is applied.
5. Apps the profile doesn’t mention are left, hidden or quit, as set.
6. Full-screen apps the profile recorded go full screen again, one at a time, from the Desktop their window is on. macOS adds each new full-screen Space after the last Desktop and Spacetile can’t move it, so Desktop numbers stay as the profile has them. A Split View pair starts with its left window, and Spacetile chooses the right one in the picker. Windows that are already full screen, or not open, are left.
7. If “Show afterwards” is set, Spacetile switches to that Space.

Empty slots in the design are skipped. Windows that are already on a Space but aren’t mentioned stay there and tile as usual.

Focus filters

Each Focus mode can apply a profile. In System Settings → Focus → choose a Focus → Add Filter → Spacetile, set:

• Profile: applied when the Focus turns on.
• When Focus ends, load: optional, applied when it turns off.

The filter refers to profiles by name, so renaming one means choosing it again in the filter.

File format

A file that doesn’t load stays visible: the Profiles window lists it with the error under the sidebar (click to open it), and the mini-map lists it with a warning.

Windows are written "bundle.id#index", meaning that app’s nth window in opening order. A tile is a list of windows (more than one makes a stack), and a split is {axis, ratio, first, second}. Every field except name and spaces is optional, and an empty list is an empty slot.

fullScreen lists full-screen apps as windows: one, or two in Split View, left first.

{
  "name": "working",
  "show": 3,
  "display": "Studio Display",
  "hideUnlisted": true,
  "spaces": [
    {
      "space": 3,
      "mode": "bsp",
      "tree": {
        "axis": "horizontal",
        "ratio": 0.7,
        "first": ["dev.zed.Zed-Preview#0"],
        "second": {
          "axis": "vertical",
          "ratio": 0.5,
          "first": ["com.apple.Safari#0"],
          "second": ["com.anthropic.claudefordesktop#0"]
        }
      },
      "floating": [],
      "others": []
    }
  ],
  "fullScreen": [
    { "windows": ["com.apple.Music#0"] }
  ]
}

When a profile is applied, each recorded display is paired with a connected one: the same display first (by signature, so a renamed display still matches), then one with the same name (another unit of the same model), then one in the same role (built-in for built-in, the biggest external for an external). Each connected display stands in for one recorded display. Spaces whose display has no partner go after the main display’s own Desktops, where macOS puts a disconnected display’s Desktops. Spaces from profiles saved before displays were recorded go to the main display.