TilingBud configuration
Diese Seite gibt es noch nicht auf Deutsch; hier steht die englische.
TilingBud reads ~/.config/TilingBud/config.toml (or $XDG_CONFIG_HOME/TilingBud/config.toml if that variable is set).
The file is created with comments on first launch. Save it in any editor and the change applies immediately;
Settings > Configuration File shows the status and any problem with its line number. Changes made in Settings are
written back into this same file, keeping your comments.
The format is TOML (comments with #, [sections], key = value with strings, numbers, true/false and lists).
The file stays English in every language: keys, values and the comments TilingBud writes. The interface (Settings,
menus, messages about problems in the file) follows the language macOS uses for TilingBud, set in System Settings >
General > Language & Region > Applications; it is English and German so far. The tilingbud command answers in
English on every system.
Reference
Section titled “Reference”| Section | Key | Type | Default | Meaning |
|---|---|---|---|---|
| (top level) | apply_rules_at_launch |
true/false |
true |
Window rules also act on the windows that are open when TilingBud starts (a Teams window already open lands on its space too). A rule move that fails is tried again, up to three times, five seconds apart. |
| (top level) | stand_in_first_spaces |
true/false |
false |
When a display goes away, macOS removes its first space and puts that space’s windows on the main display’s first space until the display returns. TilingBud adds a stand-in space on the main display with the same name, layout and windows, placed before the display’s other spaces, and removes it when the display returns and macOS took the windows back. Experimental: it goes through Mission Control, which opens for a moment; when Mission Control refuses, the windows stay on the main display’s first space. |
[tiling] |
inner_gap |
number 0-200 | 8 |
Points between windows when a space is tiled. |
[tiling] |
outer_gap |
number 0-1000, or four: [top, right, bottom, left] |
8 |
Points between windows and the screen edges; a wide edge keeps room for widgets ([8, 320, 8, 8]). The control bar keeps the same distance to its edge; windows keep inner_gap to a docked bar. |
[tiling] |
mouse_follows_focus |
true/false |
true |
When the focus moves to another display (a space or window there is focused, by TilingBud or by macOS) and the pointer is not on it, the pointer jumps to the middle of the focused window, or of the display if it has no window. Within one display the pointer stays where it is. |
[tiling] |
focus_follows_mouse |
"off", "autoraise", "autofocus" |
"off" |
The window under the pointer gets the focus once the pointer rests on it for a moment. "autoraise" also brings it to the front, "autofocus" leaves it behind the window in front; where macOS does not allow that, it falls back to "autoraise" (Settings says so). Not while a mouse button or a modifier key is held, over the menu bar, the Dock, a menu or a TilingBud window, nor while Mission Control is open |
[tiling] |
layout |
"off"/"bsp"/"main"/"stacked"/"scroll" |
"bsp" |
How the windows of every space are kept arranged. "bsp": new windows split the area of the focused one, closed, minimized or moved windows leave a gap that the others fill. "main": a main area and the other windows in a secondary area beside it, new windows at its end. "stacked": all windows on one frame, the focused one in front, with a bar of app icons. "scroll": columns side by side in a row that may be wider than the screen, a new window in a column right of the focused one; the row scrolls to the focus, and columns out of view wait at the screen edge with a strip of 40 points in view (never at an edge another display borders). "off" leaves windows alone. |
[tiling] |
split_ratio |
number 0.1-0.9 | 0.5 |
Share of the existing window when a new window splits its area. |
[tiling] |
new_window_placement |
"first"/"second" |
"second" |
Whether a new window goes left of or above (first) or right of or below (second) the focused window. |
[tiling] |
float_position |
"center"/"stay"/"last" |
"center" |
Where a window that floats beside a saved layout (“other windows float”) lies when it appears, and where a window taken out of the layout (window --toggle float, “Float Window” in its menu, or an arranged window put on all spaces with window --toggle all-spaces/“On All Spaces”) lies: center the middle half of the usable area, nearly full height; stay where the layout had it; last where it floated the last time (center the first time). window --toggle float --grid … goes before it. |
[tiling] |
tile_position |
"previous"/"focused" |
"previous" |
Where a floating window goes when it is arranged again (also a window back from all spaces on one space): previous its old place, split with the same neighbors as before (the index in main and stacked), beside one of them when they no longer stand together, beside the focused window when none is left; focused beside the focused window like a new window. The place is kept while the window floats on its space. |
[tiling] |
auto_balance |
true/false |
false |
Give all managed windows equal areas again (bsp) whenever one joins or leaves. Not on a space a saved layout arranges: its ratios stay. |
[tiling] |
drag_keeps_place |
true/false |
true |
A managed window dragged within its space (bsp, by its title bar or with the drag modifier) keeps the place it is let go at: each edge it shares with a neighbor follows it, an edge at the screen border stays, and an overlay marks the windows that make room while it is dragged. false puts it back in its place. A drop on another window swaps or inserts as before. |
[tiling] |
split_width_multiplier |
number 0.1-3 | 1.0 |
The one rule for side by side or on top of each other in bsp: an area that is split (for a new window, a dropped one, the first arrangement and space --tile) is split side by side while it is at least this many times as wide as high, else on top of each other. 1.0 puts them side by side while the area is wider than high; 0.5 keeps windows side by side longer, 2 stacks them sooner. |
[tiling] |
layout_cycle |
list of "off"/"bsp"/"main"/"stacked"/"scroll" |
["bsp", "main", "stacked"] |
The modes space --layout next and prev step through. The windows keep their order across modes: the main window of main is the first window of bsp and the first of the stack. |
[tiling] |
ratio_steps |
list of numbers 0.1-0.9 | [0.5, 0.667, 0.333] |
The shares window --ratio next and prev step through, counted from the step nearest to the window’s share now and wrapping at the end. On a main space they step main_ratio. Full width is window --toggle zoom-fullscreen. |
[tiling] |
main_position |
"auto"/"left"/"right"/"top"/"bottom" |
"auto" |
main layout: side of the main area; "auto" is left on a display wider than tall and top otherwise. |
[tiling] |
main_ratio |
number 0.1-0.9 | 0.5 |
main layout: share of the main area. Dragging its divider changes it for that space until TilingBud restarts. |
[tiling] |
main_count |
whole number 1-10 | 1 |
main layout: windows in the main area. |
[tiling] |
scroll_width |
number 0.1-1 | 0.5 |
scroll layout: width of a new column as a share of the usable area. |
[tiling] |
scroll_widths |
list of numbers 0.1-1 | [0.5, 0.667, 1.0] |
scroll layout: the widths window --ratio next and prev step the focused column through. |
[tiling] |
scroll_heights |
list of numbers 0.1-0.9 | [0.333, 0.5, 0.667] |
scroll layout: the shares of its column’s height window --height next and prev step a window through when it shares the column with others. |
[tiling] |
scroll_reveal |
"nearest"/"center" |
"nearest" |
scroll layout: focusing a column out of view scrolls the row by as little as brings it into view, or puts it in the middle. |
[tiling] |
scroll_swipe_fingers |
0, 3, 4 |
0 |
scroll layout: a horizontal swipe with this many fingers scrolls the row under the pointer; swipes with another count reach macOS as before. 0 is off. Settings warns when macOS switches spaces with the same count. |
[tiling] |
scroll_modifier |
"", "option", "control", "command", "shift", "fn", "control_command" |
"" |
scroll layout: with this key held, the scroll wheel scrolls the row under the pointer. "" is none. |
[tiling] |
bsp_inner_gap, main_inner_gap, stacked_inner_gap, scroll_inner_gap |
number 0-200 | — | The inner gap of that layout instead of inner_gap; unset, the layout uses inner_gap. In stacked it is the distance between the windows and the control bar that lists them. |
[tiling] |
bsp_outer_gap, main_outer_gap, stacked_outer_gap, scroll_outer_gap |
number 0-1000, or four: [top, right, bottom, left] |
— | The outer gap of that layout instead of outer_gap; unset, the layout uses outer_gap. The control bar keeps it to its edge on a space in that layout. |
[tiling] |
dock_zone |
"auto"/"always" |
"auto" |
Area reserved for windows a rule docks to an edge (dock), in bsp and main: the tiled windows leave it free, so they never cover the docked window. "auto": only while a docked window is on the space, as wide as the window plus outer_gap. "always": dock_size points on every edge a rule docks to, also without a docked window, so the tiled windows do not move when it opens or closes. |
[tiling] |
dock_size |
number 100-1000 | 340 |
Width (or height, at the top and bottom) of the reserved area with dock_zone = "always"; a wider docked window widens it. |
[[space]] |
id |
string | — | Mission Control’s identifier of the space the entry belongs to. Written by Settings; the comment after [[space]] names the space’s current number. The first space of a display has no identifier of its own and is written as display:<display UUID>. |
[[space]] |
name |
string | none | Name of the space, shown in the menu bar. It stays with the space when other spaces are added, removed or moved. Emojis in it are drawn in their colors. |
[[space]] |
icon |
string | none | The space’s symbol: the name of an SF Symbol ("eurosign.circle") or one emoji ("💶"), shown where a label lists "icon" and before the name in the menu and Settings. Anything else is reported with its line. |
[[space]] |
layout |
"off"/"bsp"/"main"/"stacked" |
[tiling] layout |
Layout of this space only; overrides [tiling] layout. A mode chosen in the control bar, the menu, by shortcut or space --layout overrides it, also after a restart, until space --layout reset or a change of this value, also one made while TilingBud was not running; space --layout save (Save for This Space in the control bar) writes it here. |
[[space]] |
display |
display name, "main" or a list of them |
none | The display the space belongs on, e.g. "SAMSUNG" or ["SAMSUNG", "main"]: the first connected one of the list, else the main display (names as Settings > Displays shows them, case ignored). macOS gathers every space on the remaining display when one is unplugged and gives a newly connected display an empty space; TilingBud then moves the space back to its display through Mission Control (it shows briefly) and removes that empty space if it was the display’s only one and has no windows and no entry. A display keeps at least one space. Without display a space stays where macOS puts it. |
[[space]] |
layout_preset |
name of a saved layout | none | The space is arranged by this saved layout (a file layouts/<name>.json next to this file): its windows go into the places the layout names, a place whose window is missing takes no area and its window goes there when it appears. Saving a space as a layout sets it, unless the save window’s “Use for this space” is off (--no-keep). A window of an app with a place in the layout stays on the space against a rule naming another space, and a window opening on another space while its place waits is moved here. A name without a file is reported with its line and the space is arranged as without it. |
Menu bar
Section titled “Menu bar”[menu_bar]show_icons = trueicon_grouping = "per_app"| Key | Default | Meaning |
|---|---|---|
show |
"spaces" |
What the item in the menu bar shows: "spaces" a pill per space, "current" only the pill of the space each display shows, "icon" only TilingBud’s symbol (a click opens the menu), "off" no item (opening TilingBud again, a double click on the app, opens Settings) |
show_icons |
true |
An app icon per window (or per app) in each space’s pill |
icon_grouping |
"per_app" |
"per_app": one icon per app with a window count; "per_window": one icon per window |
highlight_active_icon |
true |
The focused window’s icon is larger and fully opaque |
show_sticky_windows |
false |
Windows shown on every space get an icon on each space |
compact_icons |
false |
Icons overlap to save room; the focused window’s icon is shown in full |
show_window_title |
false |
The focused window’s title on the pill of the space you are on, after its icons. Off, the titles of windows on other spaces are not looked up (without Screen Recording each lookup searches the app’s windows), and the hover panel leaves their second line blank |
title_width |
160 |
Points the title always takes on that pill (60 to 400), so the menu bar does not move; longer titles are cut |
hover_panel_width |
300 |
Widest the window list shown on hover may get, 200 to 600 points |
left_margin |
0 |
Space before the first pill, -8 to 8 points |
right_margin |
0 |
Space after the last pill, -8 to 8 points |
label |
["number", "name"] |
What a pill’s label shows, in this order, e.g. “7 Finance”: "number" (position on its display), "name", "shortcut" (the keys bound to space --focus N, smaller and dimmed; “7 Finance ⌃F1”), "layout" (a symbol for the space’s layout mode: split, main and secondary, stacked, or three places while the space keeps a saved layout, whose name the hover panel shows; the place stays empty while the space is off, so the pill keeps its width), "icon" (the space’s icon; left out without one). A space without a name shows its number instead (unless "number" is listed too); a missing shortcut is left out |
displays |
"own" |
With several displays: "own" every display’s menu bar shows that display’s spaces (as "active" where macOS gives the menu bar item’s copies on the other displays no view of their own), "active" the spaces of the display with the focused window, "all" every display’s spaces grouped with a separator. Numbers count per display in every mode |
theme |
"soft" |
Look of the pills, none with an outline: "soft" slightly rounded corners, "square" nearly square corners, "rounded" round ends. The fills follow the menu bar’s light or dark look |
segmented |
false |
Theme option: the pills of a display are segments of one bar, rounded only at its ends, with a divider between two, instead of standing apart |
label_block |
"first" |
Theme option: parts of the label on a block at the pill’s left edge, opaque on the space you are on and following the menu bar’s look (light with dark parts in the light look, dark with white parts in the dark look): "first" the first part (e.g. the number), "label" every part, "pill" the whole pill (the focused pill solid in that color), "none" no block |
block_color |
"auto" |
Theme option: the color of the block where it is solid: "auto" follows the look as above, "accent" the system accent color, "#RRGGBB" a color of its own; on a color the parts on the block are black or white, whichever reads better |
auto_shrink |
true |
A display whose menu bar has too little room for the pills shrinks them step by step, on that display only, instead of macOS hiding the item there: first without the window title, then with only the number and the layout symbol, then with compact icons, then with numbers only. It grows back only when the larger pills fit with room to spare |
A pill changes its width only when it gains or loses an icon, when a space is added or removed, or when an option or a space name changes; a new title or a change of focus never moves anything in the menu bar.
Control bar
Section titled “Control bar”[control_bar]show = "docked"edge = "left"A bar of TilingBud’s own at an edge of a space with the space’s layout, its windows, its floating windows and actions. It lives on its space and slides with it, stays above the other apps’ windows and never takes the focus; every click runs a command, as a shortcut would. Resting the pointer on an item for half a second shows what it does beside the bar; a right click on the bar outside a window’s or the layout’s icon opens TilingBud’s menu, as on the menu bar item.
| Key | Default | Meaning |
|---|---|---|
show |
"docked" |
When a space has a bar and in which form. Floating (a short bar centered at the edge, above the windows): "auto" while a floating window is covered or the space is stacked, showing only those sections; "always" on every space, also with the layout off; "hover" as soon as the pointer reaches the bar’s edge. Docked, on every space (a docked bar that came and went would move the windows each time): "docked" a strip along the whole edge, and the windows of every arranged space are arranged beside it (it covers nothing, nothing covers it). "off" never. space --toggle control-bar shows or hides the bar of the shown space until show changes or TilingBud restarts |
size |
32 |
Thickness of the bar in points, from 24 to 56 (Settings: steps of 4); its buttons are 8 pt smaller. 48 matches the icon bar of a stacked space; a docked bar keeps this much room |
background_opacity |
1.0 |
How much of the bar’s glass background (blurred) shows, from 0 to 1; at 0 only the buttons stay (Settings: “Background blur”) |
border |
false |
A thin line around the bar |
theme |
"soft" |
Corners of the bar, its marks and its block, with the values of [menu_bar] theme: "soft" slightly rounded, "square" nearly square, "rounded" round ends. The window in front is marked with a ring in the color of its border ([borders] focused_color, the first color of a gradient), a covered floating window with a fill |
edge |
"left" |
"left", "right", "top" or "bottom"; a stacked space keeps room for a floating bar there |
sections |
["space", "presets", "layout", "windows", "floating"] |
Sections at the bar’s start (left, or top on a vertical bar) in this order; one with nothing to show is left out. Presets: the name of the saved layout arranging the space, while one does; a click opens the chooser. Space: the space’s label from label. Layout: the mode; a click opens the chooser beside the bar: every mode with a preview of the space’s windows, the layout settings and, while the mode differs from the saved one, Save for This Space (writes [[space]] layout) and Back to Saved; below them the saved layouts with their sketches (Stop Using, Edit…, Save Current…). Windows: the arranged windows, the focused one marked, a click focuses. Floating: the floating windows, the covered ones marked, a click brings one forward. Mode: the shortcut mode that is on (shortcuts --mode), on a block in the accent color, while one is. |
sections_center |
["mode"] |
Sections in the middle of the bar, in this order. Each section stands in one of sections, sections_center and sections_end; a list left out gives up a section another list names. A bar that shows a section in the middle or at the end is as long as its edge. |
sections_end |
["actions"] |
Sections at the bar’s end (right, or bottom on a vertical bar), in this order. |
label |
["number", "name"] |
The parts of the Space section, in this order: "number", "icon", "name", "shortcut", with the rules of [menu_bar] label (the layout has a section of its own). At a left or right edge, text wider than the bar’s buttons is turned on its side and reads from bottom to top |
label_block |
"first" |
Parts of the Space section on a block, as on a pill: opaque (light with dark text in the light look, dark with white text in the dark look) across the bar’s thickness, from the bar’s start when the section is first: "first" the first part, "label" every part, "none" no block |
block_color |
"auto" |
The block’s color, as [menu_bar] block_color |
actions |
["balance", "gaps", "arrange", "raise-floating", "overview"] |
Entries of the Actions section in this order, each at most once: balance, auto-balance, raise-floating and overview (every window of the space to scale, space --overview) run at a click; gaps (inner and outer gap 0 to 16, off for now, reset) and arrange (rotate 90°, 180°, 270°, mirror, turn the split) open a choice with the current values marked. An entry that does not apply to the space (balance on a space that is not bsp) is shown disabled with the reason. Window commands are in a window icon’s menu; other commands belong on a shortcut |
replaces_stack_bar |
true |
A stacked space lists its windows in the bar; with show = "auto" it then always has one |
covered_floating |
true |
With show = "auto", a covered floating window brings the bar |
all_spaces_windows |
true |
Windows assigned to all spaces (rule all_spaces) count as floating windows of the space they are shown on: listed in the Floating section and, when covered, bringing the bar |
icon_grouping |
"per_app" |
Icons of the Windows and Floating sections, as [menu_bar] icon_grouping: "per_app" one icon per app where the app first appears, with the number of its windows; an app’s floating windows join the icon of its arranged windows (marked “floating” in the list) while the Windows section is shown; resting on it lists them beside the bar (a click focuses one, a right click opens its menu) and a click on the icon focuses the app’s windows in turn. "per_window" one icon per window |
The icon of a window has a menu (right click): float or tile, dock on the left or right (writes the app’s rule like Settings does, after asking, so every window of the app is docked), move to a space, minimize and close.
Performance
Section titled “Performance”[performance]title_update_interval = 2 # seconds, 0.2 to 30poll_interval = 5 # seconds, 0.25 to 10| Key | Default | Meaning |
|---|---|---|
title_update_interval |
2 |
Window titles that change all the time (terminal spinners) update the menu bar at most this often |
poll_interval |
5 |
Safety-net re-read of the window state; events normally make it unnecessary, window titles included. A lower value finds a change an app reported no event for sooner and costs more energy. While change events arrive it waits four intervals, in Low Power Mode twice the interval, and it does not run while the displays sleep or the session is locked |
Updates
Section titled “Updates”[updates]check = trueinstall = "ask"| Key | Default | Meaning |
|---|---|---|
check |
true |
Look for a new version 10 s after launch and then once a day; the check reads the list of versions from downloads.tilingbud.com and sends nothing but TilingBud’s version, the macOS version and the CPU type. false checks only when you ask (“Check for Updates…”, tilingbud update --check) |
install |
"ask" |
"ask": a new version is announced in the menu, and nothing is downloaded before you choose “Install and Relaunch”. "automatic": it is downloaded and verified in the background and installed when TilingBud quits. A copy installed with Homebrew only announces it, with brew upgrade --cask tilingbud |
Keyboard
Section titled “Keyboard”[keyboard]caps_lock_control_escape = true| Key | Default | Meaning |
|---|---|---|
caps_lock_control_escape |
false |
Recommended for TilingBud’s shortcuts (lctrl+1 … and the others on Control): Caps Lock is the left Control key, tapped alone (within tap_ms, no key or click in between) it sends Escape, and Escape is Caps Lock. It applies to every app and every keyboard, not only to TilingBud: TilingBud sets the system’s key mapping (hidutil) and takes it back when this is off again and when it quits. Settings > Keyboard says when macOS’s Modifier Keys or another tool (Hammerspoon, Karabiner) change these keys too |
tap_ms |
250 |
Longest press of Caps Lock, in milliseconds (50 to 500), that sends Escape; held longer it is Control only |
shortcut_hints |
false |
Each shortcut that runs shows its keys and its command’s title for about a second at the bottom of the display with the focus, on every space and without taking the focus. Settings > Shortcuts also has a tester: while it is on, a press shows what it would do instead of doing it |
drag_windows |
false |
With drag_modifier held, a press anywhere in a window and a drag moves it; where it is let go the layout decides as after a drag at the title bar (swap, insert, dock). In every app: clicks with the modifier held go to TilingBud, not to the app (Option-drag to copy in Finder, for example) |
drag_modifier |
"option" |
The key held for drag_windows: "option", "control", "command", "shift", "fn" or "control_command"; no other of these may be held with it |
right_drag |
"resize" |
Dragging with the right button and the modifier held: "resize" moves the window’s corner nearest to the press (at least 120 × 80 points), "none" leaves right clicks to the app |
Shortcuts
Section titled “Shortcuts”Global keyboard shortcuts are entries of [shortcuts]: the key combination (in quotes) equals a command of the
command line (cli.md), without the leading tilingbud. A new configuration file starts with these:
"alt+t" = "window --toggle float" takes the focused window out of the layout and puts it back, ctrl+1 to ctrl+0
show desktop 1 to 10, ctrl+alt+1 to ctrl+alt+0 move the focused window there and ctrl+alt+shift+1 to
ctrl+alt+shift+0 move it and go along.
[shortcuts]"ctrl+alt+1" = "space --focus 1""ctrl+alt+shift+1" = "window --space 1""ctrl+alt+cmd+1" = "window --space 1 --follow""ctrl+alt+right" = "space --focus next""ctrl+alt+t" = "space --tile""alt+h" = "window --focus west""alt+l" = "window --focus east""shift+alt+h" = "window --swap west""shift+alt+l" = "window --swap east""ctrl+alt+l" = "window --resize east 50""shift+alt+space" = "window --toggle float""alt+r" = "window --focus recent""alt+f" = "space --raise-floating""shift+alt+f" = "window --focus floating.next""alt+z" = "window --toggle zoom-fullscreen""alt+return" = "window --promote""alt+space" = "space --layout next""ctrl+alt+g" = "space --toggle gaps""alt+d" = "display --focus next""shift+alt+d" = "window --display next"- Modifiers:
ctrl,alt(opt),shift,cmd, in any order, for the key on either side;lctrl,rctrl,lalt,ralt,lshift,rshift,lcmd,rcmdfor one side only. - One side: with
"lalt+l" = "window --focus east"the right option key with L still types what the keyboard layout says (@on a German layout); with"lalt+x"and"alt+x"both bound, the left side runs the first and the right side the second. In Settings a right-click on a shortcut binds its modifiers to one side. - Keys: letters, digits,
f1tof20,leftrightupdown,space,return,tab,escape,deleteand the punctuation keys- = [ ] ; ' \ , . / \``. Letters, digits and punctuation name the key printed with them on the selected keyboard layout (alt+zis the Z key on a German keyboard too,alt+ö` works there); when the layout changes, the shortcuts are read again. - Space numbers in shortcuts count over all displays in Mission Control’s order (
indexintilingbud query --spaces): with ten spaces on the main display,space --focus 1tospace --focus 10are those andspace --focus 11is the first space of the second display, whichever display you are working on. Pills number the spaces per display. - A value that starts with a domain but is not a valid command is reported with its line; the other shortcuts stay active.
Settings > Shortcuts lists the commands with their keys and records new ones (written in the command form): new keys replace the command’s old ones, and keys another command had move over after asking. It marks keys that an enabled macOS shortcut also uses and keys that could not be registered because the system or another app holds them. “Add a Shortcut” binds any command by choosing it and its argument from lists and recording the keys; “Recommended shortcuts” adds a set for tiling windows in one step (keys already in use stay as they are and are listed). Shortcuts need no extra permission.
Apps, shell commands, lists, modes and per-app shortcuts
Section titled “Apps, shell commands, lists, modes and per-app shortcuts”A value is a TilingBud command (it starts with a domain such as space, window or app) or a
shell command (any other value). A list runs several in order; a table adds options:
[shortcuts]exclude_apps = ["Factorio", "com.vmware.fusion"]"alt+return" = "app --open iTerm""rctrl+f" = "open ~""rctrl+v" = "open -a /usr/local/bin/code""ctrl+alt+m" = ["space --focus 3", "open -a Mail"]"alt+h" = { command = "window --focus west", except_apps = ["iTerm2"] }"cmd+s" = { command = "~/bin/note-save.sh", pass = true }"alt+r" = "shortcuts --mode resize""ctrl+alt+q" = { command = "shortcuts --mode default", every_mode = true }"shift+next" = "space --focus next"
[shortcuts.mode.resize]capture = true"h" = "window --resize west 50""l" = "window --resize east 50""return" = "shortcuts --mode default"app --open <name or bundle id>starts the app or brings it to the front with its space (see the app command in cli.md); an app that is not found is reported with the shortcut’s line.- A TilingBud command runs inside TilingBud, without a shell; a line that starts with
tilingbud(tilingbud space --focus 2) runs the same way. A value that starts with a domain but does not parse is reported with its line, never handed to the shell. - Any other value runs with your login shell (
$SHELL -l -c, so the PATH of your profile applies), in your home folder, without input or output; TilingBud does not wait for it. The text is not written to the log readably. - A list runs its steps one after another, each waiting for the one before; a step that fails (a command that fails, a shell command with an exit status other than 0) stops the rest. A step is a string like any value.
- A table takes
command(a string or a list, as above) and:pass = truelets the key press reach the app in front as well after the action ran;apps = [...]makes the shortcut work only while one of these apps is in front,except_apps = [...]never while one of them is; apps are named by name or bundle identifier, and while a shortcut does not apply its keys reach the app.every_mode = truekeeps a shortcut of[shortcuts]working while a mode is on. exclude_appsturns every TilingBud shortcut off while one of these apps is in front (games, virtual machines).[shortcuts.mode.<name>]is a mode: aftershortcuts --mode <name>only its shortcuts (and those withevery_mode) work, and its keys need no modifier. Escape leaves the mode unless the mode binds Escape itself;shortcuts --mode defaultleaves it too. Keys a mode does not bind reach the app in front; withcapture = truethey are swallowed instead while the mode is on, and the mode ends after two minutes without a key press.- Media keys can be shortcut keys, alone or with modifiers:
play,next,previous,volume_up,volume_down,mute,brightness_up,brightness_down(holding next or previous counts the same). The press then does only the shortcut.
Window rules
Section titled “Window rules”Each [[rule]] says what to do with windows of an app. At least one matcher (app, bundle, title, role or
subrole) and one action are needed. Everything
set for a whole app is a rule that names only the app; Settings > Apps edits these.
Rules also apply to TilingBud’s own Settings window (app = "TilingBud"): always_on_top and all_spaces act on
it directly; it is never arranged, and space does not move it. The file TilingBud creates starts with such a rule
(Settings on top, on every space), which you can change or remove.
[[rule]]app = "Slack"space = 3 # windows open on space 3
[[rule]]app = "Notes"all_spaces = true # every window of the app is on all spaces
[[rule]]app = "Calculator"float = true # never tiled (float = false forces tiling)border = false # no window border
[[rule]]app = "Safari"title = "^Downloads" # regular expression on the window titlespace = 2
[[rule]]app = "iPhone Mirroring"dock = "right" # floats at the right edge; tiled windows leave room for it
[[rule]]app = "MoneyMoney"main = false # only the main window is arranged, its other windows floatfloat = true
[[rule]]subrole = "AXDialog" # every dialog floats ...except_apps = ["Xcode"] # ... but Xcode'sfloat = true
[[rule]]app = "Safari"except_title = "^Preferences" # every Safari window but the settingsspace = 2
[[rule]]app = "Music"space = 1display = "Sidecar Display (AirPlay)" # the first space of the iPad, while it is connected| Key | Meaning |
|---|---|
app |
App name (case does not matter), or the path of a program starting with / or ~ ("~/bin/lulu", "~/Applications/Foo.app"): windows of that program, or of a program inside that app bundle or folder; links are followed |
bundle |
Bundle identifier, e.g. com.apple.finder |
title |
Regular expression matched against the window title |
main |
true: only the app’s main window, false: only its other windows (second windows, dialogs that macOS reports as ordinary windows). A window of which it is not known whether it is the main window never matches, so the first window of an app is not floated by mistake. It only takes part in the decision whether a window floats (float), not in the other actions. Use it for apps with one main window; apps with equal windows (Safari) change their main window with the focus |
role, subrole |
Accessibility role and subrole the window must have (case does not matter), e.g. role = "AXWindow", subrole = "AXDialog"; tilingbud query --window shows them. Like main, a window whose role is not known yet never matches, and they only take part in float and dock |
except_apps |
Apps whose windows the rule leaves out: a list of app names or bundle identifiers, e.g. ["Xcode", "com.apple.Safari"] |
except_title |
Windows whose title matches this regular expression are left out |
space |
The space windows are moved to when they appear: its number, counted on its display as Mission Control does, or its name from [[space]] (space = "Comm"), which finds the space on any display however the numbers shift; a name no space has, or that two spaces have, is reported with the rule’s line. Renaming a space in Settings changes the name in rules, shortcuts and display profiles too |
display |
The display of space: its number (display in tilingbud query --spaces) or its name; without it, and while the named display is not connected, the main display |
float |
true: never tile, false: always tile |
all_spaces |
true: all windows of the app are shown on every space (reversible); they always float |
always_on_top |
Only TilingBud’s own windows (its window level). For other apps’ windows it is reported as not available: only the window’s own app, or the Dock with SIP partly off, can change a window’s level; raising it again after every click broke the focus |
border |
false: the windows get no border. The file TilingBud creates has such a rule for iPhone Mirroring (also docked and on all spaces), whose phone-shaped window a rectangle does not fit |
dock |
"left", "right", "top" or "bottom": the window floats, is placed at that edge when it opens, and on a bsp or main space the tiled windows leave a strip for it ([tiling] dock_zone). Dragged away from its edge, it stays where it was dropped, floating without a dock, until it closes. Cannot be combined with float = false; a later rule with float = false ends the dock |
list |
true: windows of the app that TilingBud leaves out for their window level (up to the Dock’s) or because macOS marks them as panels or helper windows are listed and arranged like other windows. For one window until it closes, use “Arrange” in Settings > Apps > Windows left out instead. Only app, bundle and title decide which windows it lists; sheets, windows with a parent, transparent windows and windows under 50 points stay out |
slot |
"<layout>.<place>": the window goes into that place of a saved layout, the place by its number in reading order or by its app ("mail.1", "mail.Notes"), and to the space that keeps the layout (layout_preset) unless the rule has space. A layout or place that does not exist, or a layout no space keeps, is reported with the rule’s line |
Windows whose app does not let their size be set (fixed-size dialogs such as MoneyMoney’s bank transfer window) float from the start without a rule; a window that only lacks a full-screen button (Activity Monitor) is still tiled.
Rules act when a window appears, and on the windows already open when TilingBud starts while
apply_rules_at_launch is on (the default); “Apply Window Rules Now” applies them to every open window at any time. A property the system cannot apply is reported (Settings > Windows) and the other actions of
the rule still apply.
Signals
Section titled “Signals”Each [[signal]] runs a shell command when something happens (a bar like SketchyBar redraws
when the space changes). The command runs through your login shell, detached; its output is not kept. Signals come only
from this file (and Settings, which writes it): tilingbud query --signals lists them, but the command line can neither
add nor run them.
[[signal]]event = "space_changed"action = "sketchybar --trigger space_change"
[[signal]]event = "window_focused"app = "iTerm2" # only for iTerm2 windowsexcept_title = "^vim"action = "~/bin/terminal-focused.sh"label = "terminal"| Key | Meaning |
|---|---|
event |
When the command runs: window_created, window_destroyed, window_focused, window_moved, window_resized, window_minimized, window_deminimized, space_changed, space_created, space_destroyed, display_added, display_removed, display_changed (another display has the focus), app_launched, app_terminated, app_activated, app_hidden, app_shown, mission_control_entered, mission_control_left, system_woke |
action |
The shell command |
label |
A name for the signal, shown in Settings and query --signals |
app, except_apps, title, except_title |
Limit window and app events as in [[rule]]: the app (name, or a program path), apps left out, a regular expression the window title must match or must not match. Other events ignore them |
The command gets the event’s values as environment variables, each only where the event has it:
TILINGBUD_EVENT, TILINGBUD_WINDOW_ID, TILINGBUD_PROCESS_ID, TILINGBUD_SPACE_INDEX (index in query --spaces),
TILINGBUD_SPACE_ID, TILINGBUD_RECENT_SPACE_INDEX (the space shown before, for space_changed),
TILINGBUD_DISPLAY_INDEX and TILINGBUD_DISPLAY_ID (the display’s uuid).
Using signals
Section titled “Using signals”There are two ways to act on events:
-
A signal: TilingBud starts a command for every event, with the values in variables. Settings > Signals edits them, or the file does:
[[signal]]event = "space_changed"action = "sketchybar --trigger space_change SPACE=$TILINGBUD_SPACE_INDEX" -
Listening: a tool keeps
tilingbud subscribe [<event>…]running and reads one JSON line per event; nothing is started per event and no[[signal]]entry is needed (docs/cli.md, “subscribe”):Terminal window tilingbud subscribe space_changed window_focused | while read -r line; doecho "$line" | jq .space_indexdone
Typical uses: a bar redraws its spaces (space_changed), a script sets a chat status when a space opens
(space_changed with TILINGBUD_SPACE_INDEX), a layout script runs when a display is plugged in (display_added).
More about a window: tilingbud query --window $TILINGBUD_WINDOW_ID. The event names are listed by
tilingbud subscribe nope (it fails and names them).
Events are the changes TilingBud sees, each reported once: the windows and spaces that exist when TilingBud starts are
no events. A signal whose command still runs when its event comes again runs once more when it ends, for the newest
occurrence; events in between are dropped. window_moved and window_resized also come when the layout places windows.
Saved layouts
Section titled “Saved layouts”A saved layout is the arrangement of a managed space with places instead of windows: each place names the app of the
window that belongs there (as TilingBud shows it, or its bundle identifier) and may give a title pattern. Each layout
is a file layouts/<name>.json next to this file, read again whenever it changes; a file that cannot be read is
reported by its name. A space keeps a layout with layout_preset in its [[space]] entry, and a rule puts windows
into a place with slot.
A layout has variants, tried in order: the first whose when holds for the display of the space is used (the
conditions of display profiles, without when.), one without when holds on every display.
Ratios are shares of the area. bsp has a tree of splits ("h" side by side, "v" on top of each other, ratio
the share of first) with places as leaves; main and stacked have places in order, main also mainRatio
and mainCount.
A place may say how its window is opened, with the options of app --open: file (a document or folder, ~ for the
home folder), url (a link) and arguments (start arguments); a place with a document or link takes the window that
shows it first, so two windows of one app keep their places. project is the folder of an editor’s workspace: it opens
first in a window of its own and the file in it. Saving sets it when the window’s title names a folder above the
file (“description.md — ashub-workspace”). "park": true makes a place a parking place: a new
window that matches it takes the place and the window there is minimized; clicked in the Dock, that window takes the
place back and parks the other. Without it a second window joins the layout. With "openApps": true applying the layout on purpose
(Settings, space --layout-apply, a shortcut) opens a window for every free place, one after the other: an app that
does not run starts with the place’s document, a running app gets a new window from the “New Window” entry of its menu, without coming to the front,
with the document in it, and an app without that entry (Reminders) brings its one window over. Each window comes to the layout’s space, also when a rule names another one. A space
that keeps the layout, a display change and a restart open no apps, unless the layout has "openAtLaunch": true
(“Open its apps when TilingBud starts”, space --layout-save --open-at-launch): then, when TilingBud starts, every
space that keeps it gets what its places miss opened, without being shown; the windows are brought to it. Only the document of a window’s shown tab is
kept, not its other tabs. With
"floatOthers": true windows that take no place float on the space while the layout arranges it: each is put where
float_position says once when it appears (center: the middle half, each further one a little lower right;
stay leaves it where macOS opened it) and then stays where it is moved. window --toggle float (“Float Window”)
on such a window takes it into the arrangement; moved to a space without the layout, it is arranged there.
Applying a layout by hand writes it as the space’s layout_preset, so it keeps arranging the space until it is
stopped (space --layout-clear, “Stop Using” in the menu, Settings > Spaces) or another one is applied. A place also
keeps its app’s bundle identifier ("bundle"), by which the app is opened and matched.
{ "openApps": true, "variants": [ { "when": { "shape": "superwide" }, "mode": "bsp", "tree": { "split": "h", "ratio": 0.5, "first": { "app": "Mail" }, "second": { "split": "v", "ratio": 0.5, "first": { "app": "Calendar" }, "second": { "app": "iTerm2", "title": "^build", "file": "~/coding/tb" } } } }, { "mode": "stacked", "places": [{ "app": "Mail" }, { "app": "Calendar" }, { "app": "iTerm2", "file": "~/coding/tb" }] } ]}Display profiles
Section titled “Display profiles”Values that differ per display or per setup of displays go into [[display_profile]] entries. A profile has a
name, a condition of when.* keys (all given parts have to hold) and the values it sets for the displays it
matches, written with their table: keys of [tiling], [menu_bar], [borders] and [control_bar], space.<name or id>.layout for
one space and all_spaces.layout for every space on that display. Where several profiles match, the last one in the
file wins per key. Nothing is written back: when the display changes, its own values return.
[[display_profile]]name = "laptop alone"when.builtin = truewhen.displays = 1tiling.inner_gap = 2all_spaces.layout = "stacked"space.Code.layout = "bsp"
[[display_profile]]name = "ipad"when.kind = "sidecar"menu_bar.title_width = 80| Condition | Values | Holds when |
|---|---|---|
when.display |
name | the display’s name as macOS shows it (case does not matter) |
when.kind |
"builtin", "external", "sidecar", "airplay" |
the kind of display; sidecar is an iPad used as display |
when.builtin |
true/false |
built-in or not |
when.uuid |
text | this one device (its UUID) |
when.shape |
"superwide", "ultrawide", "landscape", "square", "portrait", "tall" |
aspect ratio (width to height) of the usable area: at least 3 (32:9), at least 2.1 (21:9, 24:10), at least 1.15 (16:9 to 4:3), at least 0.87 (1:1, 16:18), at least 0.45 (16:9 upright), below (ultrawide upright) |
when.min_width, when.max_width |
points | width of the usable area |
when.min_pixels, when.max_pixels |
pixels | pixel width of the display |
when.scale |
1, 2, 3 |
points to pixels |
when.min_diagonal, when.max_diagonal |
inches | size macOS reports for the display |
when.displays |
1, ">=2", "<2" … |
number of connected displays |
when.connected |
name or list of names | all these displays are connected |
Other keys (rules, shortcuts, [[space]] names) are the same on every display and reported when a profile sets them.
So are the keys with one value for the whole Mac: menu_bar.show, menu_bar.displays (there is one menu bar item),
tiling.focus_follows_mouse and tiling.mouse_follows_focus. Every other value a profile sets is used for its display
everywhere: the arrangement, a gap reset (space --gap inner reset returns to the display’s gap), where a window taken
out of the layout lies, the menu bar on that display (its label, its icons) and the control bar there, including the
color of its focus mark, which is the focused border’s.
Window borders
Section titled “Window borders”[borders]enabled = truewidth = 4 # points of line outside the window, 1 to 20radius = 16 # optional: one corner radius for all windows, 0 to 40focused_color = "#4C9AFF" # "#RRGGBB", "#RRGGBBAA", or two colors for a gradient: ["#FF7E5F", "#96C93D"]unfocused_color = "#80808080" # optional: also draw a border around windows without focusorder = "below" # "below" or "above" the window| Key | Default | Meaning |
|---|---|---|
enabled |
true |
Draw borders |
width |
4 |
Width of the line outside the window, in points |
radius |
automatic | Corner radius for every window. Without the key each window gets its own radius as the window server reports it |
focused_color |
["#F5AF19", "#F12711"] |
Color of the focused window’s border; a list of two colors draws a gradient from the top left to the bottom right corner |
unfocused_color |
none | If set (a color or two), other windows on the shown spaces get a border too |
order |
"below" |
"below": the border lies behind its window, only the part outside the window shows and it never covers the window’s content or popovers. "above": in front of the window |
follow_without_events |
false |
Also follow the windows on a timer (60 times per second while one moves, 30 in Low Power Mode, 5 after a second without movement), not only on the window server’s move events: for a macOS version whose events miss moves. Without move events at all the timer runs anyway; it stops while the displays sleep or the session is locked |
A border is a transparent click-through window placed directly behind or in front of its window, so windows in
front of it still cover it. It belongs to the space of its window, so it slides along when you switch spaces, and
Mission Control hides it. The window server reports when a bordered window moves or changes size, so the border
follows at once. Popovers, menus and sheets get no border; the border stays on the app’s window behind them.
An app without borders is a window rule with border = false (Settings > Apps). Borders are not included in
screenshots or screen sharing. They are drawn on the spaces that are shown, not over
native full-screen windows.
Example
Section titled “Example”[tiling]inner_gap = 6outer_gap = 10
[[rule]]app = "Calculator"float = true
[[rule]]app = "System Settings"float = true
[[space]] # space 1id = "display:2953A6D1-22F1-4FE4-8F82-33F48D250F02"name = "Dev"
[[space]] # space 2id = "2E83F7F5-4BFC-4165-A598-E4FFEB4B024A"name = "Mail"layout = "off"Permissions
Section titled “Permissions”Window titles of other apps additionally need Screen Recording; without it TilingBud reads titles through Accessibility, which is slower for windows on other spaces. Switching spaces by the Dock swipe needs no setting; as fallback TilingBud can use your own “Switch to Desktop N” shortcuts (System Settings > Keyboard > Keyboard Shortcuts > Mission Control), which are off by default.