Configure
Window and workspace rules
Match new windows by app or title, and set per-workspace layouts, monitors and gaps.
Window rules
| Field | Meaning |
|---|---|
app |
Bundle id or app name. Exact match, case does not matter. |
title |
A regular expression, matched anywhere in the title. |
float |
Open the window floating. |
workspace, layout |
Where it opens, and the layout of that workspace if it is empty. |
size, center |
For floating windows: { width, height } as fractions of the screen (or points above 1), and centering. |
maximize |
Open maximized. |
width |
Column width in the scrolling layout, as a fraction of the screen. |
monitor |
Open on the workspace that this monitor shows: a role, its number (1 is the leftmost) or part of its name. workspace wins when both are set. |
focus = false |
Open without taking the focus. The window that had it gets it back. |
run |
A command or a list of commands to run after the other actions. |
stop = false |
Let later rules add to this one. By default the first match is the last. |
name |
A label. It shows in wm logs (rule=finder float,center) and is what wm.floating.disable takes. It matches nothing. |
A rule needs app or title. Rules apply in order, and later values win.
Default floating rules
Some windows should not be tiled: the picture-in-picture window of Google Meet, the popup of a browser extension, Finder, Preview.
wm adds a list of rules for them, after the rules of your config, so these windows start floating and centered without any
setting. The list is wm.floating.defaultRules, and each entry is a normal wm.rule with a name:
| Name | Windows |
|---|---|
helium-popups, chrome-popups, chromium-popups, edge-popups, brave-popups, firefox-popups |
Windows of the browser that are not the browser: picture-in-picture (Google Meet, the “Picture-in-Picture” window of Firefox), extension popups, about:blank popups. A browser window has the name of the browser in its title (... - Helium); these have not. An empty title is a dialog and floats already. |
finder, preview, calculator, activity-monitor, archive-utility, quicktime-player |
The windows of these apps. |
system-settings, raycast-settings |
System Settings and the settings window of Raycast. |
Only the Helium title was checked on a real Mac. The others come from how the browsers name their windows: ... - Google Chrome,
... - Chromium, and the name Brave, Edge or Firefox anywhere in the title (Edge writes a zero-width space inside its name, and
Firefox uses a long dash). The bundle ids of Chromium (org.chromium.Chromium) and Edge (com.microsoft.edgemac) were not checked
either. Read wm logs first if a browser does not match, because a pattern that misses the real windows would float all of them.
wm.floating.disable("finder", "preview") -- tile these again (or: wm.floating.disable { "finder", "preview" })
wm.floating.enabled = false -- no default rule at all
wm.rule { app = "com.apple.finder", float = false } -- a rule of yours for the same window wins: the config goes first
for _, rule in ipairs(wm.floating.defaultRules) do -- change the list itself
if rule.name == "preview" then rule.size = { 0.5, 0.85 } end
end
table.insert(wm.floating.defaultRules, { name = "notes", app = "com.apple.Notes", float = true, center = true })
An unknown name in wm.floating.disable is a config error. Rules apply to windows that open after the reload; use wm window center
for one that is open already.
Workspace rules
wm.workspace(name, options) needs at least one option.
| Option | Meaning |
|---|---|
layout |
scrolling or tiling. |
monitor |
Bind the workspace to a monitor (a role, a number or part of its name). Showing it shows it there. |
default |
With monitor: the monitor starts with this workspace. |
gaps, border |
Settings for this workspace only. |
layout_options |
Tiling, scrolling and master options for this workspace only, for example { split_ratio = 0.6 }. The master options have master_ in front: master_ratio, master_count, master_orientation, master_new_window. |