Settings (⌘, while Spacetile is open, or Settings… in the menu-bar panel) is the easiest way to change how Spacetile behaves. Everything it saves is also in a plain JSON file you can edit by hand or keep in your dotfiles.
Settings panes
Settings has a toolbar of panes. It opens on the pane you used last, or on Permissions while a check there needs attention. While Settings, the Profiles window or the Welcome guide is open, Spacetile shows in the Dock and ⌘Tab.
| Pane | What’s there |
|---|---|
| General | Updates (Channel, version, Check for Updates…), mouse options, window previews, the active window border and dimming, animation, macOS tiling, follow options, layout algorithms, spacing and the default split, Command line (Install Command…), and Open at login |
| Keys | Every command grouped by modifier family, with pictures for the place commands and a search field. Use Spacetile’s shortcuts turns all shortcuts off and on, and Use Shortcuts From loads another window manager’s set. See Commands |
| Rules | Always-float apps, title rules, apps sent to a Space and apps that open full screen. See Rules |
| Spaces | Each Desktop’s label and layout mode (Tile, Stack or Float), and Edit Profiles… |
| Menu Bar | A live preview, the menu-bar items and the index style. See Menu-bar item |
| Licence | Your Trial or Licence, entering a Licence key, and buying or renewing. See Licence and updates |
| Permissions | Checks the Accessibility permission and the macOS settings Spacetile relies on, with a button to fix each one, and reopens the Welcome guide. Its toolbar label counts the checks that need attention |
General, Keys, Rules, Spaces and Menu Bar each have Restore Defaults at the bottom, and Keys also has a Restore button per section. Edit → Undo (⌘Z) takes back any change, a restore included.
Profiles have their own window: Edit Profiles… in the menu-bar panel. See Profiles.
Rules
Rules decide what happens to an app’s windows when they open. Set them in Settings → Rules:
| Rule | What it does |
|---|---|
| Always float | The app’s windows are never tiled |
| Title rules | Windows of an app whose title matches a pattern float. The pattern is a regular expression; Settings checks it as you type and shows how many open windows it matches |
| Send new windows to a Space | The app’s new windows go to that Desktop on the active display |
| Open full screen | The app’s new windows go full screen, after any Space rule has moved them |
Rules match an app by the name it shows in the menu bar; Settings lists every installed app to choose from and marks a name no app has with ?. Rules apply to windows opened after the change. To float or tile a window that’s already open, focus it and press ⌥f.
By default, Activity Monitor, App Store, Archive Utility, Calculator, Dictionary, FaceTime, Photo Booth, Screen Sharing, Software Update, System Information and System Settings always float, and so do Finder’s copy, connect, move, info and preferences windows.
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 | The current Space’s number, in one of three styles: 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 brighter) |
| Space name | The Desktop’s label |
| Layout mode | A Tile, Stack or Float icon, or ⤢ on a full-screen app |
| Window count | How many windows Spacetile manages on this Space |
| Stacked windows | How many windows are stacked out of sight, such as +2 |
| Profile icon | The icon of the profile applied, or saved from the menu bar, last |
| Profile name | The name of the profile applied, or saved from the menu bar, last |
By default the item shows the index, name and stacked windows.
While tiling is paused, a pause badge leads the item. A ⚠︎ leads it when Spacetile needs your attention: Accessibility is off, config.json has an error, or a Licence key is needed. Click the item to see why.
Click the item to open the menu-bar panel with the mini-map. See Menu-bar mini-map.
Files
Everything Spacetile saves is in ~/.config/spacetile/:
~/.config/spacetile/
├── config.json keys, rules, Spaces, mouse and menu-bar settings
└── profiles/*.json one file per profile
Settings writes these files for you. You can also edit them by hand: changes apply as soon as you save, whichever way your editor saves. Your Licence key is kept in the keychain, and the update Channel in Spacetile’s preferences, not here.
If config.json has an error
If config.json stops parsing, Spacetile keeps running with the last good settings. The menu-bar item shows ⚠︎, and the panel and Settings show the error. Settings offers two buttons above every pane:
- Open config.json, to fix it in your editor.
- Revert to Last Good, which moves the broken file to the Trash and writes the settings Spacetile is still running.
Spacetile doesn’t overwrite a broken file by itself, but changing anything in Settings saves the running settings over it.
config.json
keys, focusFollowsMouse, mouseFollowsFocus, floatApps, floatTitles, spaces and appSpaces are always written, and a file missing any of them doesn’t load. The rest are optional, and default as shown.
| Key | Default | Meaning |
|---|---|---|
keys |
see Commands | Shortcuts, as "chord": "command", such as "alt-h": "focus west" |
shortcuts |
true |
Register keys as shortcuts. false releases every shortcut 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 |
Go to the Space a window is sent to |
followRoutedWindows |
false |
Go to the Space an app rule sends a new window to |
windowPreviews |
false |
Draw windows’ content in the mini-map and profile designer. Needs the Screen Recording permission |
padding |
automatic | Space around the edge of the screen, in points (0 to 200). Automatic is 10 pt on displays wider than 1600 pt, 5 pt otherwise |
gap |
automatic | Space between tiles, in points (0 to 200). Automatic follows the same rule |
spacing |
true |
false tiles edge to edge, with no padding or gaps, and keeps padding and gap for turning it back on. toggle spacing flips it |
activeBorder |
false |
Outline the focused window. toggle border flips it |
borderColor |
accent colour | The outline’s colour, as "#RRGGBB" |
borderOpacity |
1 |
The outline’s opacity, from 0.1 to 1 |
dimInactive |
false |
Shade the windows and desktop behind the focused window, on its display. toggle dim flips it |
dimOpacity |
0.3 |
The shade’s opacity, from 0.05 to 0.9 |
animateWindows |
false |
Slide and resize windows into their tiles instead of jumping there. Windows jump anyway while Reduce Motion is on |
ratio |
0.5 |
The share an existing window keeps when a new window splits its tile, and the main window’s share with master and stack tiling, from 0.1 to 0.9 |
tiling |
"bsp" |
How Tile Spaces place windows: "bsp", "i3" or "master-stack". See Algorithms |
stacking |
"fill" |
How Stack Spaces lay windows out: "fill" or "accordion" |
floatApps |
system utilities | App names whose windows never tile |
floatTitles |
Finder dialogs | A list of {"app", "title"}: that app’s windows whose title matches the regular expression float |
spaces |
10 entries | A list of {"space", "label", "layout"}: each Desktop’s label (shown in the menu bar) and starting mode, "bsp", "stack" or "float". space is the Desktop number, not counting full-screen apps, so it can differ from the number ⌥N uses. Settings adds an entry the first time you label or set the layout of a Desktop beyond these |
appSpaces |
none | "App name": desktop: new windows of that app go to that Desktop on the active display, numbered as in spaces |
fullScreenApps |
none | App names whose new windows go full screen, after any appSpaces rule |
nativeTiling |
true |
Treat macOS’s own tiling (the green button’s menu, Window → Move & Resize, fn⌃ arrows) as Spacetile commands. See macOS tiling |
menuBar |
index, name, stacked | What the menu-bar item shows: {"items": [{"item": "index", "shown": true}, …], "indexStyle": "single"}. Items are logo, index, name, layout, windowCount, stacked, profileIcon and profileName; index styles are single, stepper and displays. Items left out are added, hidden, at the end |
See also
- Commands: every command you can bind in
keys. - Profiles: the profile file format.
- Troubleshooting: what to do when something isn’t working.