Everything Spacetile remembers is in ~/.config/spacetile/:
~/.config/spacetile/
├── config.json keys, rules, Spaces, mouse and menu-bar settings
└── profiles/*.json one file per profile (see profiles.md)Settings edits these files. You can also edit them by hand: changes apply as soon as the file is saved, whether the editor writes in place or saves by replacing the file. If config.json stops parsing, Spacetile keeps the last good settings running and shows ⚠︎ in the menu bar with the error. It never overwrites a file you’ve broken.
config.json
Only keys, focusFollowsMouse, mouseFollowsFocus, floatApps, floatTitles, spaces and appSpaces are always written. The rest are optional and default as shown.
| Key | Default | Meaning |
|---|---|---|
keys |
see Commands | "chord": "command", e.g. "alt-h": "focus west" |
shortcuts |
true |
Register keys as global shortcuts. false releases every chord but keeps keys, for binding the commands in another tool |
focusFollowsMouse |
true |
Focus the window under the pointer |
mouseFollowsFocus |
true |
Move the pointer into windows focused by keyboard |
followAfterSending |
true |
Switch to the Space a window is sent to |
followRoutedWindows |
false |
Switch to the Space an app rule sends a new window to |
padding |
automatic | Space around the edge: 10pt on displays wider than 1600pt, 5pt otherwise |
gap |
automatic | Space between tiles, same rule |
ratio |
0.5 |
Share an existing window keeps when a new window splits its tile |
floatApps |
system utilities | App names whose windows never tile |
floatTitles |
Finder dialogs | {"app", "title"}: windows whose title matches the regular expression float |
spaces |
10 entries | {"space", "label", "layout"}: each Desktop’s label (shown in the menu bar) and default mode. space is the Desktop number Mission Control shows, not counting full-screen apps, so it can differ from the number ⌥N uses. Settings ▸ Spaces lists every Desktop you have and adds an entry the first time you label or set the layout of one beyond these |
appSpaces |
your yabai rules | "App name": desktop: new windows of that app go to that Desktop, numbered as in spaces |
fullScreenApps |
none | App names whose new windows go native full screen, after any appSpaces rule |
nativeTiling |
true |
Read macOS’s own tiling (the green button’s menu, Window ▸ Move & Resize, fn⌃ arrows) as Spacetile commands instead of undoing it. See macOS tiling |
menuBar |
index, name, stacked | What the menu-bar item shows, see below |
Rules match an app by the name it shows in the menu bar. They apply to windows opened after the change. Use ⌥f to float or tile a window that’s already open.
Menu-bar item
Settings → Menu Bar chooses what the item shows and in what order (drag to reorder):
| Item | Shows |
|---|---|
| Spacetile logo | A tile-grid mark |
| Space index | Index only (the number in a square), Index stepper (a square per Space: filled for the current one, outlined for Spaces with windows, with a diamond for each full-screen app), or Every display (each display’s current number, the active display’s bright). On a full-screen app it shows ⤢ instead of a number |
| Space name | The Space’s label |
| Layout mode | BSP, Stack or Float icon, or ⤢ on a full-screen app |
| Window count | Windows Spacetile manages on this Space |
| Stacked windows | Windows stacked out of sight, e.g. +2 |
| Profile icon | The icon of the profile applied, or saved from the mini-map, last. Off by default |
| Profile name | The name of the profile applied, or saved from the mini-map, last. Off by default |
Click the item for the mini-map. It opens with a Spacetile switch: off pauses tiling and every shortcut except Pause. Below the map are your profiles with their icons (one click applies), Save Current Layout…, Edit Profiles…, Settings… and Quit. While tiling is paused, a pause badge leads the item and the map dims.
Settings panes
Settings (⌘,) has a toolbar of panes. It opens on the pane you used last, or on Permissions & macOS while a check there needs attention. The window is titled after the pane. While Settings, Profiles or the Welcome guide is open, Spacetile shows in the Dock and ⌘Tab. Every pane has Restore Defaults at the bottom (Keys also has a Restore button per section), and Edit › Undo (⌘Z) takes back any change, a restore included. If config.json doesn’t parse, a banner above the pane offers Open config.json and Revert to Last Good, which moves the broken file to the Trash and writes the settings still running.
| Pane | What’s there |
|---|---|
| General | Open at login, mouse options, window previews, macOS tiling, follow options, spacing and default split ratio, config file shortcuts |
| Keys | Every action grouped by modifier family, with pictures for the place commands and a search field. Click a shortcut to re-record it, use Record shortcut for unbound ones, and click a group’s prefix to change the whole group. Taking a shortcut from another action says so, with Undo. ⌃←, ⌃→, ⌃↑, ⌃↓, ⌘Q, ⌘Tab and ⌘Space are refused: macOS owns them, and Spacetile steps between Spaces with ⌃← and ⌃→ when instant switching fails |
| Rules | Always-float apps, title rules, app → Space rules and apps that open full screen, with app icons and every installed app to choose from. A ? marks a name no installed or running app has, duplicates can’t be added, and title rules show how many open windows they match, checking the regular expression as you type |
| Spaces | Label and layout mode (BSP, Stack, Float icons) per existing Space |
| Menu Bar | A live preview, then menu-bar items and index style |
| Permissions & macOS | Checks Accessibility and the macOS settings Spacetile relies on, with links to fix them, and reopens the Welcome guide. Its toolbar label counts the checks that need attention |
Profiles have their own window: Edit Profiles… in the mini-map footer, or ⇧⌘P while Spacetile is active (see Profiles).