Configuration

OmniWM stores its editable configuration at ${XDG_CONFIG_HOME:-$HOME/.config}/omniwm/settings.toml. XDG_CONFIG_HOME is honored only when it is an absolute path beginning with /; otherwise OmniWM uses ~/.config/omniwm/settings.toml. That file is the canonical settings source: it is live-reloaded whenever you save it from an editor, and OmniWM configuration changes made in the Settings window are written back to it. OmniWM writes the top-level key schemaVersion = 4.

The schema is strict

After version upgrades, settings.toml is validated as a whole. In a version 4 file, a missing required key invalidates the entire file, and each action may appear in the hotkeys array at most once — an unknown or duplicate action id rejects the file, while an action that is left out is unassigned. Workspace 10+ hotkey entries are optional. Enumerated string keys must use one of their listed values; an unknown value rejects the whole file too. Conflicting trackpad gesture finger-count assignments (see gestures) reject the whole file as well. The safest way to edit is to change values in place (or use the Settings window) rather than deleting keys. See the Settings Reference for every key and its default.

Opening the file

Click OmniWM’s status bar icon and use:

• Reveal Settings File — shows settings.toml in Finder.
• Edit Settings File — opens it in your editor.

Both commands recreate the file from the running settings if it was deleted, so you always land on a complete, valid file.

Settings window

The searchable Settings window groups controls by task. Desktop contains Styles, Workspace Bar, Dynamic Island, Widgets, and Menu Bar; Windows contains Workspaces, Layouts, Displays, App Rules, and Overview. Appearance holds app appearance, motion, borders, and system-wide window corners. Layouts has Spacing, Niri, and Dwindle tabs. App Rules now uses the same settings window, with Save/Revert and discard protection for drafts. Clipboard retention limits and scratchpad labels are edited in TOML; clipboard history can be enabled from the Command Palette’s Clipboard mode.

Start at Login is managed by macOS, and System-wide Window Corners changes a macOS preference. Neither is stored in settings.toml.

Settings > Appearance > App & Motion carries a System-wide Window Corners control (macOS 26.4+). It writes the system-wide preference, so it changes standard Mac app windows everywhere — including windows OmniWM does not manage — and apps that draw their own window chrome may ignore it. Affected apps must be fully quit and reopened before the new radius applies.

Live reload and recovery

• Saving settings.toml from an editor applies the changes immediately; no restart needed.
• If the file cannot be parsed, OmniWM leaves it untouched and reports the problem in Diagnostics: at startup it runs with defaults, and a malformed live edit leaves the active settings unchanged. If you later save from the Settings window, OmniWM first secures the exact rejected bytes as settings.toml.corrupt (then settings.toml.corrupt.1) next to the config file — two write-once slots — before replacing the file.
• Unrecognized keys are preserved on save and reported by the built-in diagnostics rather than deleted. If an unrecognized key belongs to an array element that cannot be matched unambiguously after an edit, OmniWM leaves the file untouched and blocks writes instead of attaching the key to the wrong element.

Automatic version upgrades

A file without schemaVersion is a legacy version 0 file; OmniWM v0.6.4 emitted version 1 files. OmniWM guarantees automatic upgrades for settings emitted by v0.6.2 through v0.6.4 and upgrades valid version 2 and 3 files as well. Version 0 files pass through all four migration steps in memory. Version 1, 2, and 3 files start at their next step without rerunning earlier migrations. Only the final strict version 4 file is written:

• Missing settings introduced since version 0 receive their compatibility defaults. In particular, focus.raiseOnMouseFocus becomes true to preserve the old behavior; gaps.fullscreenUsesOuterGaps and workspaceBar.hideInNativeFullscreen become false; and scratchpads.labels starts empty.
• The version 0 hotkey step adds the required scratchpad slot entries. The old assignFocusedWindowToScratchpad and toggleScratchpadWindow ids become their slot 1 equivalents while preserving the configured triggers; an explicitly configured slot 1 id wins if both forms are present.
• The retired consumeOrExpelWindowLeft and consumeOrExpelWindowRight actions are removed. Diagnostics suggest the current replacement commands.
• The version 1 to version 2 step adds the 18 switchWorkspaceSlot.N and moveToWorkspaceSlot.N entries plus closeFocusedWindow, all unassigned unless already present. Final validation still rejects any unrelated unknown or duplicate hotkey id.
• The version 2 to version 3 step moves a nonempty monitorRoutingOverrides array into one routing.arrangements entry with a stable UUID. An empty array becomes no arrangements. All original monitor rows and their unrecognized fields remain intact, including rows for disconnected displays; the migration does not query displays. Custom routing can inherit that arrangement for a connected subset. A missing, non-array, or malformed old routing field rejects the configuration without rewriting it.
• The version 3 to version 4 step adds the Set Mark and Remove Mark hotkey actions as unassigned entries. Existing hotkey bindings keep their assignments.

Before rewriting version 0, 1, 2, or 3, OmniWM copies its exact original bytes to the write-once backup settings.toml.pre-v4, using settings.toml.pre-v4.1 if the first slot already contains different data. An existing byte-for-byte identical backup is reused. If neither slot is safe to use or the backup cannot be written, OmniWM leaves the original file untouched, applies the upgraded settings only in memory, and blocks subsequent settings writes so the original cannot be overwritten.

After a successful backup, OmniWM atomically rewrites the file once as canonical version 4 TOML. The rewrite preserves unrecognized keys, the target of a symlink, and file permissions, but it can reorder the document and does not preserve comments. The pre-v4 backup retains the exact original text. If the rewrite fails, the original file remains intact and subsequent configuration writes are blocked. A valid release migration never creates a .corrupt backup; those recovery slots are reserved for a genuinely rejected file that is later replaced by an explicit settings save.

Config logs and the built-in Diagnostics report every defaulted path, mapped or retired hotkey, and the backup location. Paths shown there use the resolved XDG config directory, including a custom XDG_CONFIG_HOME.

Older schema-less files are attempted through the same migration, but are outside the guaranteed compatibility range. OmniWM v0.6.0 used direction-specific resize action ids: for both resizeGrow and resizeShrink, replace the .left/.right pair with one .horizontal entry and the .up/.down pair with one .vertical entry, choosing which binding to keep if the pair differed. If a version 0, 1, 2, or 3 file contains structures that cannot satisfy strict post-migration validation, startup leaves the file untouched and runs with defaults, and a live edit is rejected without changing the active settings. A file with a newer, unsupported schemaVersion is not treated as corrupt: OmniWM leaves it untouched, blocks configuration writes, and reports that this OmniWM version cannot safely edit it.

Runtime state lives elsewhere

Volatile runtime state is kept out of the config file so settings.toml stays clean for dotfile management. Clipboard history, update-check timestamps, the persisted window restore catalog (including Niri column and Dwindle tree placements), the Quake terminal’s custom frame, and the last palette mode live in ${XDG_STATE_HOME:-$HOME/.local/state}/omniwm. XDG_STATE_HOME is honored only when it is an absolute path beginning with /; otherwise OmniWM uses ~/.local/state/omniwm.

The separate OmniWM Dev app uses omniwm-dev instead of omniwm for both its config and state directories. See Building from Source for the development build workflow.

What’s in the file

The full schema is documented key by key in the Settings Reference. At the top level:

Table / array	Covers
[general]	Hotkeys master switch, Hyper key, default layout, updates, IPC, animations, language
[focus]	Focus-follows-mouse and monitor-edge focus behavior
[mouseWarp]	Cursor warping between monitors
[routing]	macOS vs. custom routing and saved arrangements per connected display set
[monitors]	Optional ranking that decides which connected display is Main, Secondary, and so on
[gaps]	Inner and outer gaps
[niri]	Scrolling (Niri) layout options
[dwindle]	Dwindle (BSP) layout options
[borders]	Focused-window border
[overview]	Overview zoom and colors
[workspaceBar]	Workspace bar appearance and behavior
[gestures]	Mouse and trackpad gestures
[statusBar]	Menu bar icon extras
[hiddenBar]	Menu bar icon concealment
[clipboard]	Clipboard history limits
[quakeTerminal]	Drop-down terminal
[scratchpads]	Scratchpad slot labels
[appearance]	Light/dark appearance of OmniWM’s own UI
[[hotkeys]]	One entry per assignable action
[[workspaces]]	Workspace definitions
[[appRules]]	Per-app window rules
[[monitor*Overrides]]	Per-monitor bar, orientation, Niri, Dwindle, and gap overrides