Configuration Reference

💡 How to read this page

Default is the value applied when the key is absent. It ships in the bundled default-config.yaml (copied to your config on first launch) and in the in-app fallback, so the two always agree. Tier shows whether a key works on Free or requires Pro. On the free tier, the Pro keys are forced to their gated default. Your saved value is kept for when you upgrade.

ℹ️ Value formats

Percentage: a string like "50%". Color: RGB hex, #RRGGBB or #RRGGBBAA. Bool: true or false. Regex: a string that is matched with appId or title. See Config File → Value Formats for the full list.

Top-level structure

Key	Type	Tier	Description
`app`	map	Free	App preferences: launch-at-login and the beta update channel. They travel with your config file. The Pro license is not stored here; it lives in your Keychain.
`layout`	map	Free	Layout, focus, and visual settings (gaps, focus ring, overview, tabs, thumbnails, recent-windows).
`binds`	map	Free	Keybindings. See Keybindings for the full action table.
`gestures`	map	PRO	Trackpad gestures. See Trackpad Gestures.
`windowRules`	array	PRO	Declarative rules. They match windows and apply actions. See Window Rules.
`namedWorkspaces`	array	PRO	Persistent named workspaces. See Workspaces.

app

Key	Type	Default	Tier	Description
`launchAtLogin`	bool	`unset`	Free	Start FazerWM automatically when you log in. FazerWM registers itself as a macOS login item and reconciles the registration whenever the config changes. While the key is unset, FazerWM never touches your login items. A copy you added by hand in System Settings is left alone. Also settable from Settings → General → Startup.
`betaUpdates`	bool	`false`	Free	Receive pre-release builds from the beta channel. Stable updates are always offered regardless. Turning it on runs an update check as soon as the change is saved.

layout

Key	Type	Default	Tier	Description
`gaps`	int	`6`	Free	Logical pixels between all windows, columns, and screen edges.
`defaultWindowWidth`	width spec	`2x`	Free	Width of new tiled windows: `50%` (fraction of the display width), `2x` (N windows across on a 16:9 display; wider displays get more columns), or `900pt` (fixed points).
`newWindowsFollowMouse`	bool	`true`	Free	New windows open on the display under the cursor.
`stackedColumnDefault`	enum	`tabbed`	PRO	How windows stack in a column: `tabbed` or `tiled`. The free tier forces `tiled`.
`focusBehaviour`	enum	`keepInView`	Free / PRO	Where the focused column lands: `keepInView` (Keep in View, free) or `center` (Pro). `hyper+c` toggles the session between the two modes without changing this setting (Pro).
`focusAfterClose`	enum	`stayOnWorkspace`	PRO	Focus handoff after a window closes: `stayOnWorkspace` (Pro) or `lastFocused`. The free tier forces `lastFocused`.
`pointerFollowsFocus`	enum	`window`	PRO	Cursor warps on a focus change: `display`, `window`, or `none`. The free tier forces `none`. Windows with an `avoidMouse` rule are never warped.
`coupleWorkspaces`	bool	`false`	PRO	Workspaces switch in lockstep: changing the workspace changes it on every display at once (each display keeps its own layout within that workspace number). The free tier forces `false`.
`crossDisplayWrap`	bool	`true`	PRO	Focus and move actions continue onto the adjacent display at a workspace edge. The free tier forces `false`.
`crossDisplayWrapDetent`	bool	`true`	PRO	Two-press guard for `crossDisplayWrap`: the first press arms, the second press crosses. The free tier forces `false`.
`focusRing`	map	—	PRO	Focus ring settings. See below. `nil` on the free tier.
`overview`	map	—	Free	Overview thumbnail settings. See below.
`tabIndicator`	map	—	Free*	Tab indicator visuals. See below. *Only visible with Pro tabbed columns.
`thumbnails`	map	—	Free*	Thumbnail streaming. See below. *`streamFPS` is forced to 1 on the free tier.
`recentWindows`	map	—	Free	Alt-tab switcher settings. See below.

layout.focusRing PRO

A colored ring or gradient around the focused window. The whole section is Pro. It is nil (no ring) on the free tier.

Key	Type	Default	Description
`enabled`	bool	`true`	Show the focus ring.
`width`	int	`2`	Ring thickness, in pixels.
`cornerRadius`	int	`15`	Corner radius, in pixels.
`placement`	enum	`inside`	`inside` (overlaps the content) or `outside` (overlaps the desktop).
`colorActive`	color	`#7FC8FF`	The solid ring color. It also serves as the gradient start color.
`colorGradient`	map	—	An optional gradient. It takes precedence over `colorActive`. Map: `{ to: color, angle: degrees }`. The default angle is `180` (top to bottom). `0` = bottom to top. `90` = left to right. `270` = right to left.

layout.overview

Thumbnail sizing in the Workspace Overview (Hyper+Tab).

Key	Type	Default	Description
`thumbScaleActive`	percentage	`15%`	Thumbnail scale for the active workspace. Accepts `"25%"` or `0.25`.
`thumbScaleInactive`	percentage	`10%`	Thumbnail scale for the non-focused workspaces.
`minGaps`	int	`5`	Minimum gap between thumbnails. Legacy configs using `mingaps` still decode.

The legacy keys scale and inactiveScale are still accepted on load. They map to thumbScaleActive and thumbScaleInactive.

layout.tabIndicator

Visual indicators for tabbed columns. They are meaningful only when tabbed columns are in use (Pro).

Key	Type	Default	Description
`position`	enum	`left`	Indicator side: `left` or `right`.
`width`	int	`14`	Indicator bar width, in pixels.
`gap`	int	`1`	Gap between the indicator and the column content.
`gapsBetweenTabs`	int	`5`	Vertical gap between tab indicators.
`cornerRadius`	int	`8`	Corner radius of each tab indicator.
`colorActive`	color	`#7fc8ff`	Indicator color for the active tab.
`colorInactive`	color	`#517B9C`	Indicator color for inactive tabs.
`tabSize`	tab-size	`20%`	Per-tab indicator height: `"distributed"`, a percentage (`"5%"`), or pixels (`"100px"`).
`hideWhenSingleTab`	bool	`true`	Hide the indicator when a column has only one tab.
`placeWithinColumn`	bool	`true`	Draw the indicator inside the column, not outside it.
`tooltipTitleShow`	bool	`true`	Show the window title in the tab tooltip.
`tooltipTitleMaxLength`	int	`100`	Maximum characters for the tooltip title.
`tooltipThumbnailShow` PRO	bool	`true`	Show a live thumbnail in the tab tooltip. This is a Pro feature.
`tooltipThumbnailScale`	percentage	`10%`	Scale of the tooltip thumbnail.

layout.thumbnails

Key	Type	Default	Tier	Description
`streamFPS`	int	`15`	Free / PRO	Capture frame rate for the live thumbnails. The free tier is forced to `1`. Pro sets a user value.

layout.recentWindows

The alt-tab style window switcher. The switcher keybinds are flat under binds (recentWindow*).

Key	Type	Default	Description
`enabled`	bool	`true`	Enable the switcher overlay and register its `recentWindow*` keybinds. Turning this off frees those shortcuts for other apps but does not stop focus-history tracking; it always runs, since focus-after-close resolution and workspace-switch focus restoration read it.
`columns`	int	`8`	Grid columns in the switcher.
`highlight.colorActive`	color	`#9CFDBA`	Highlight color for the selected thumbnail.
`highlight.outlineWidth`	int	`1`	Outline width of the highlight.

binds

Every action is a key under binds:. It is mapped to a modifiers+key string. You unbind an action when you set the value to an empty string (""). See Keybindings for the complete action table, the default shortcuts, and the modifier semantics.

Key	Type	Default	Description
`hyper`	modifier-string	`rshift+ropt`	The Hyper chord itself. You can compose any modifiers (for example, `lctrl+loption+lcmd+lshift`). You do not need Karabiner.
`dragColumn`	modifier-string	`hyper+loption`	Hold this bind while you drag a title bar. This moves a whole column. PRO
(all other actions)	string	varies	One entry per action (for example, `focusWindowLeft`, `columnMoveRight`, `recentWindowNext`). The full list is in Keybindings.

gestures PRO

The whole section is Pro. It is nil (gestures disabled) on the free tier. See Trackpad Gestures for the binding format and the full action list.

Key	Type	Default	Description
`overlaySwipe`	bool	`true`	A 2-finger scroll navigates inside the Overview and the Recent Windows switcher.
`bindings`	map<action, descriptor>	see Gestures	Maps an action name to one or more gesture descriptors (`"3-left"`, `"hyper+4-up"`, `"pinch"`). An empty string unbinds a default.

windowRules PRO

An array of rules. The rules are scored: each matching criterion adds 1 point. The rule with the highest score wins. The whole section is Pro. It is nil (no rules) on the free tier. See Window Rules for worked examples.

Key	Type	Description
`name`	string	An optional label. It is shown in the rule list.
`match.appId`	regex	Matched against the app bundle identifier.
`match.title`	regex	Matched against the window title.
`match.floating`	bool	Filter by the float classification: `false` = tiled only, `true` = floating only, omit = either.
`floating`	bool · enum · map	`true` / `false` / `avoidMouse`, or a map `{ enabled, avoidMouse, sticky, position }`.
`floating.position`	string · map	`"center"` or `{ x, y }` where each is a percentage (`"10%"`), pixels (`"100px"`), or an integer.
`width`	width spec	Column width for the matched tiled windows: `50%`, `2x`, or `900pt`. Omit to inherit `layout.defaultWindowWidth`.
`height`	percentage	Column height for the matched tiled windows.
`workspace`	string · int · map	Target workspace: a name (`chat`), a number (`2`), `"current"`, or a map `{ name\|number, preferredDisplay: [...] }`.
`workspace.preferredDisplay`	array	A display name, a keyword (`primary`), or an index. Multiple entries match any of them.
`group`	map	Group the matched windows into a tabbed or tiled column: `{ name, mode: "tabbed"\|"tiled" }`.

namedWorkspaces PRO

An array of persistent named workspaces. The whole section is Pro. It is nil on the free tier. See Workspaces.

Key	Type	Default	Description
`name`	string	(required)	A unique workspace identifier. It is also used as the window-rule target.
`label`	string	= `name`	A short label for the menu bar, SketchyBar, and the overview overlay's edge markers.
`displays`	array	all	Pin to specific displays by name, by keyword (`primary`), or by index.
`presence`	enum	`always`	`always` (visible even when empty) or `onDemand` (made by a window rule, removed when empty).
`focus`	keybind	—	Shortcut to switch to this workspace.
`moveColumn`	keybind	—	Shortcut to move the focused column here.
`moveWindow`	keybind	—	Shortcut to move the focused window here.