A profile is a saved arrangement of apps across your Spaces: which app goes on which Desktop, how each Desktop is tiled, and what happens to apps the profile doesn’t mention. Applying a profile puts everything back, launching apps that aren’t running.
For example, a “Writing” profile could put your editor and browser side by side on Desktop 1, notes on Desktop 2 and music on Desktop 3, and hide everything else. You can apply it from the menu bar, with a shortcut, when you turn on a Writing Focus, or when you plug in your desk display.
Save your current layout
The quickest way to make a profile is to arrange your windows, then save them (recommended for your first profile):
- Arrange your windows on each Desktop the way you want them.
- Visit each Desktop you arranged. Spacetile only knows how a Desktop is tiled once it has laid it out since it started.
- Click Spacetile’s menu-bar item, then Save Current Layout….
- Type a name and click Capture.
The new profile appears in the menu-bar panel. It records every Desktop’s windows and tiling, your full-screen apps, and the displays connected now.
Once a profile has been applied, or saved from the menu bar, Save Current Layout… first asks whether to save to that profile or make a new one. Saving to it replaces its windows and layouts and keeps its icon, shortcut and other settings. In the new-profile dialog, typing an existing profile’s name turns Capture into Replace, which does the same.
You can also capture from the Profiles window (+ → Capture Current Layout) or the command line (spacetile capture <name>). Neither changes which profile counts as the current one. spacetile capture with an existing name replaces that profile’s windows and layouts without asking.
Design a profile
The Profiles window lets you build a profile from scratch or change one you saved. Open it with Edit Profiles… in the menu-bar panel, or ⇧⌘P while a Spacetile window is open.
- New: click + → New Profile, then build it in the designer. A new profile records the displays connected now.
- Duplicate: right-click a profile → Duplicate, then rename it with the pencil.
The sidebar lists your profiles. Right-click one to apply, rename, duplicate or move it to the Trash. The detail pane runs top to bottom in the order you build a profile: what it arranges, then how it behaves.
| Part | What it does |
|---|---|
| Header | The icon (click to choose one; it’s shown in the sidebar, the menu-bar panel and optionally the menu bar), the name (✎ to rename), a summary of its Desktops, windows and displays, and Apply Profile |
| Desktops | Choose which Desktop to edit. With separate Spaces per display, choose a display (drawn where it sat), then one of its Desktops. With Spaces spanning displays, choose the Desktop; the card below shows it on every display. Desktops the profile arranges are filled pills with a window count; the rest have a dashed outline and +. Drag an app from a tile onto a pill to move it to that Desktop |
| Desktop card | The selected Desktop, titled with its number, label and display. ⋯ removes it (or, when spanning, one display’s part) from the profile; the Desktop itself is untouched |
| Layout | Tile, Stack or Float, with what each means |
| Start from | Templates, available while the Desktop tiles: Single, Halves, ⅔ + ⅓, Thirds, Main + stack, Rows and Quarters. Each keeps the Desktop’s apps and fills the new tiles in order |
| Layout picture | Click a tile to choose an app, replace it, stack another app on it, split it, clear it or remove it. Drag the gaps between tiles to resize. When spanning, each display’s part sits where the display does; click one to point Layout and Start from at it |
| Floating | Apps placed on this Desktop but not tiled |
| When applied | Show afterwards: the Desktop to switch to, or stay where you are. Apps not in the profile: Leave running, Hide, or Quit (asks first). Shortcut: a key that applies the profile. Apply automatically: apply when exactly these displays are connected. On the displays now: where each Desktop would land on the displays connected now |
| Advanced | Folded away until opened. For each app in the profile, links, files, folders and commands to open when applying the profile launches it, one per line. See Opening things at launch |
Picking the same app in two places means its first and second windows, in the order they opened.
Quit asks before quitting apps each time you apply the profile, until you tick Don’t ask again for this profile. Finder and Spacetile are never quit.
Applying a profile
Apply a profile from any of these:
- its row in the menu-bar panel;
- Apply Profile in the designer, or right-click → Apply profile in the sidebar;
- the profile’s shortcut;
spacetile load <name>;- a Focus filter, when a Focus turns on or off;
- automatically, if Apply automatically is on (see below).
Applying does this:
- Every window the profile names moves to its Desktop. A Desktop 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. If a Desktop doesn’t exist, it’s skipped, its windows stay where they are, and Spacetile says which.
- Each Desktop takes the profile’s tiling.
- Apps that aren’t running are launched, with anything the profile opens in them, and their windows are placed as they appear.
- 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 Desktop fills it, however long that takes; other apps’ windows never do. The wait ends if a window on that Desktop closes or another profile is applied.
- Apps the profile doesn’t mention are left, hidden or quit, as set.
- Full-screen apps the profile recorded go full screen again, one at a time, from the Desktop their window is on. macOS adds each full-screen Space after the last Desktop, so Desktop numbers stay as the profile has them. For a Split View pair, Spacetile starts with the left window and chooses the right one in the picker. Windows that are already full screen, or not open, are left alone.
- If Show afterwards is set, Spacetile switches to that Desktop.
Empty tiles in the design are skipped. Windows already on a Desktop that the profile doesn’t mention stay there and tile as usual.
If you captured the profile with “Displays have separate Spaces” set differently from now, Spacetile asks before applying it, since its Desktops may land in different places.
Apply automatically
Turn on Apply automatically under When applied to apply the profile whenever the connected displays change to exactly the displays it was made with. It’s off by default. It only applies when:
- exactly those displays are connected, and no others;
- “Displays have separate Spaces” is set as it was when the profile was made;
- tiling isn’t paused.
Use it for a desk setup: plug in your external display and your desk profile applies.
Opening things at launch
A profile can open links, files, folders and terminal commands in the apps it launches. Set them under Advanced in the designer, one per line for each app, or in the file’s open field.
| A line starting with | Opens |
|---|---|
/ or ~ |
That file or folder, in the app |
$ |
The command after it, in a new terminal window, starting in your home folder. The window stays at a shell when the command finishes. Use this with Terminal or iTerm |
A scheme, like https:// or mailto: |
That link |
| Anything else | A web address: github.com opens https://github.com |
They only open when applying the profile launches the app:
- An app that’s already running is left as it is. Nothing opens in it, so applying a profile again never adds duplicate tabs or windows.
- What the app restores stays. A browser that reopens its last session keeps it and gets a new tab for each link; an editor that reopens its windows keeps them.
- Finder is always running, so it never opens anything. Open a folder in another app, or with
$ open ~/folderin Terminal.
Anything that opens a new window (a folder, a command’s terminal window) is just another window of that app: it fills the app’s next waiting tile, or tiles as usual. Spacetile doesn’t close these when you apply another profile.
Focus filters
Each Focus can apply a profile when it turns on, and another when it turns off.
- Open System Settings → Focus and choose a Focus.
- Under Focus filters, click Add Filter, then Spacetile.
- Set Profile to the profile to apply when the Focus turns on.
- Optionally, set When Focus ends, load to a profile to apply when it turns off.
The filter refers to profiles by name, so if you rename a profile, choose it again in the filter.
File format
Profiles are JSON files in ~/.config/spacetile/profiles/, one per profile, so you can edit them by hand or keep them in your dotfiles. Spacetile picks up changes as soon as you save.
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 menu-bar panel lists it as “name didn’t load”.
{
"name": "Working",
"show": 3,
"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"]
}
}
}
],
"fullScreen": [
{ "windows": ["com.apple.Music#0"] }
]
}
This puts Zed in the left 70% of Desktop 3, Safari above Claude in the right 30%, and Music full screen; it hides other apps and switches to Desktop 3.
- Windows are written
"bundle.id#index": that app’s window number index, counting from 0 in the order they opened. - A tile is a list of windows. More than one makes a stack, and an empty list is an empty tile.
- A split is
{"axis", "ratio", "first", "second"}, all four required."horizontal"putsfirston the left andsecondon the right;"vertical"putsfirstabovesecond.ratioisfirst’s share, between 0 and 1.
Only name and spaces are required at the top level, and space in each Space.
| Field | Meaning |
|---|---|
name |
The profile’s name, used by load and Focus filters |
spaces[].space |
The Desktop number, counting Desktops on that display |
spaces[].mode |
bsp (Tile, the default), stack or float |
spaces[].tree |
The tiling, as nested tiles and splits |
spaces[].floating |
Windows placed on the Desktop but not tiled |
spaces[].others |
Windows captured on a Desktop before Spacetile had laid it out; moved there and tiled as usual |
spaces[].display |
The display the Desktop was captured on, by signature (vendor-model-serial) or, in older profiles, by name |
show |
Desktop to switch to after applying |
hideUnlisted / quitUnlisted |
Hide, or quit, running apps the profile doesn’t mention. quitUnlisted wins if both are set |
open |
What to open in each app, by bundle ID, when applying launches it: {"com.google.Chrome": ["github.com/Spacetile"], "com.apple.Terminal": ["$ cd ~/code/spacetile && make dev"]}. An app named only here is launched too, and never hidden or quit. See Opening things at launch |
fullScreen |
Full-screen apps, each {"windows": [...]} with one window, or two in Split View, left first |
icon |
An SF Symbol name, such as "briefcase". Missing or unknown means the default, rectangle.stack |
autoApply |
true to apply automatically when exactly the recorded displays are connected. Missing means off |
displays |
The displays captured: each one’s identity (name, vendor, model, serial, whether it’s built in), where it sat, and how many Desktops it had. Written by Spacetile; easiest left as captured |
spansDisplays |
true when captured with “Displays have separate Spaces” off. Missing means each display had its own Spaces |
display |
Older profiles only: the display names, joined with “ + “, the profile was captured on |
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 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. Desktops whose display has no partner go after the main display’s own Desktops. Desktops from profiles saved before displays were recorded go to the main display.
See also
- Spaces and layouts: how Desktops, layouts and full-screen apps work.
- Commands:
captureandload. - Configuration: where Spacetile keeps its files.