The Spacetile field guide

Configuration

Every Settings pane, every key in config.json, rules for apps, and the menu-bar item.

Last updated · Spacetile 1.2.1

Small decisions. Already made.Rules for new windows
@
Mail opensSend to Desktop 2
Mail
Messages
=
Calculator opensAlways float
Safari
Notes
Mail
Calculator
42
Rules match the app’s name and apply to windows opened after the change. An already-open window can be floated or tiled with ⌥F.

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.

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