Config

rift configuration reference

This document details the configuration of rift. Copy the example configuration from rift.default.toml into ~/.config/rift/config.toml (or $HOME/.config/rift/config.toml) and adjust to taste.

reference

The default configuration is available here and that is a great example in addition to the reference below.

---

[settings]

• animate (boolean)
  • Master switch for window animations. true/false.
• animation_duration (float)
  • Seconds per animation. Typical values: 0.15–0.35. 0.0 disables duration but keep animate = false to fully disable.
• animation_fps (float)
  • Frames per second for animations. Values > 0. Recommend 60–120.

Example:

[settings]
animate = true
animation_duration = 0.2
animation_fps = 100.0

• default_disable (boolean)
  • Controls whether newly-created macOS spaces are managed by rift by default.
  • If true, spaces start out disabled and must be activated; if false, spaces are managed by default and you can disable specific ones.
• mouse_follows_focus (boolean)
  • If true, when focus changes rift will move the mouse pointer to the focused window.
• mouse_hides_on_focus (boolean)
  • If true, hide the mouse pointer after focusing a window.
• focus_follows_mouse (boolean)
  • If true, moving the mouse into a window focuses it.
• focus_follows_mouse_disable_hotkey (Hotkey/object)
  • Optional: a hotkey which, while held, temporarily disables focus_follows_mouse. (Serialize as the same hotkey shape used in keybindings.)
• auto_focus_blacklist (array of strings)
  • Application bundle IDs (e.g. "com.apple.Spotlight") that should not trigger automatic workspace switching or steal focus behavior.
• run_on_start (array of strings)
  • Shell commands rift will run on startup. Useful for external integrations or launching helper scripts. When used with rift-cli subscribe, rift can send event data via environment variables available to those commands.
• hot_reload (boolean)
  • When true, rift will watch the configuration file and reload automatically when it changes.

---

[settings.layout]

Layout system and layout-specific options.

• mode (string)
  • "traditional" (container-based like i3/sway) or "bsp" (binary space partitioning). Defaults to "traditional" if omitted.

[settings.layout.stack]

• stack_offset (float)
  • How much stacked windows stick out (px). 0.0 means windows fully overlap. Typical 30–50 for visible stacked edges.
• default_orientation (string / enum)
  • Controls default stack orientation. Options:
    • "perpendicular" (default): choose orientation perpendicular to parent split
    • "same": use the same orientation as the parent split
    • "horizontal" / "vertical": force a specific orientation

[settings.layout.gaps]

• [settings.layout.gaps.outer]
  • top, left, bottom, right (floats): gap between windows and screen edges.
• [settings.layout.gaps.inner]
  • horizontal, vertical (floats): gaps between tiled windows.
• [settings.layout.gaps.per_display]
  • map keyed by display UUID. Each key may contain:
    • "<display-uuid>.outer"
      • top, left, bottom, right (floats): override outer gaps for that display.
    • "<display-uuid>.inner"
      • horizontal, vertical (floats): override inner gaps for that display.
  • Notes: an override may specify only outer, only inner, or both; any fields present replace the corresponding defaults for that display.

---

[settings.ui]

Warning

the following ui features are experimental

[settings.ui.menu_bar]

• enabled (boolean): show menu bar workspace indicators.
• show_empty (boolean): when true, include empty workspaces in the menu bar (can cause menubar overflow on macOS).
• mode (string / enum)
  • Controls which workspaces appear: all (default) or active.
• active_label (string / enum)
  • How to label the active workspace: index (default) or name.
• display_style (string / enum)
  • How to render a workspace: layout (default) or label.

[settings.ui.stack_line]

• enabled (boolean): enable experimental stack-line indicator.
• thickness (float): thickness in pixels when enabled.
• horiz_placement (string): "top" / "bottom" for horizontal stacks.
• vert_placement (string): "left" / "right" for vertical stacks.
• spacing (float): spacing in points between the window edge and the stack line.

[settings.ui.mission_control]

• enabled (boolean): enable mission-control related helpers.
• fade_enabled (boolean): whether mission-control fade helper is active.
• fade_duration_ms (float): fade duration in milliseconds.

---

[settings.gestures]

Trackpad gesture configuration.

• enabled (boolean): enable horizontal swipes to switch virtual workspaces.
• invert_horizontal_swipe (boolean): invert the direction of swipe actions.
• swipe_vertical_tolerance (float): maximum vertical delta allowed for a gesture to be considered horizontal.
• skip_empty (boolean): attempt to skip empty workspaces on swipe (if supported).
• fingers (integer): number of fingers required for swipe gestures.
• distance_pct (float): normalized horizontal distance (0..1) required to trigger a swipe.
• haptics_enabled (boolean): enable haptic feedback on swipe commit.
• haptic_pattern (string / enum): haptic pattern to use when haptics_enabled is true. Options: generic, alignment, level_change (default).

---

[settings.window_snapping]

• drag_swap_fraction (float)
  • Fraction threshold used when dragging a window over another to determine when they should swap positions in the layout.

---

[virtual_workspaces]

Virtual workspace controls.

• enabled (boolean)
  • If false, rift acts like a tiler with a single space.
• default_workspace_count (integer)
  • Number of workspaces rift creates on startup (recommended 1–32).
• auto_assign_windows (boolean)
  • When true, new windows can be auto-assigned using app_rules.
• preserve_focus_per_workspace (boolean)
  • When true, rift remembers the last-focused window per virtual workspace.
• workspace_auto_back_and_forth (boolean)
  • When true, switching to the previously active workspace will return you to the last active workspace (back-and-forth behavior).
• workspace_names (array of strings)
  • Optional human-readable names for workspaces in indexed order. If fewer names than default_workspace_count are provided, remaining names default to "Workspace X".
• default_workspace (integer)
  • Index of the workspace to use as the default active workspace on startup (0-based).
• reapply_app_rules_on_title_change (boolean)
  • When true, app rules are reapplied if a window title changes (useful with title_regex/title_substring rules).
• app_rules (array of objects)
  • Rules that match windows and optionally assign them to workspaces or mark them floating.

app_rules object fields

• app_id (string, optional): application bundle identifier (e.g., "com.apple.Safari").
• app_name (string, optional): substring match on application name.
• title_regex (string, optional): regex applied to the window title. If present it must be a valid regex or the rule will be ignored with a warning.
• title_substring (string, optional): literal substring match (case-sensitive) on window title.
• ax_role (string, optional): exact match for the macOS Accessibility AXRole (e.g., "AXWindow", "AXDialog").
• ax_subrole (string, optional): exact match for the macOS Accessibility AXSubrole (e.g., "AXSystemDialog").
• workspace (integer or string, optional): target workspace (0-based index) or workspace name. If omitted or invalid, defaults to the active workspace.
• floating (boolean, optional): whether new windows matched by the rule should float.

Matching semantics:

• All non-empty fields in a rule are combined with logical AND. A rule only matches if every specified field matches.
• Multiple rules may match a window:
  • If multiple matching rules share the same non-empty app_id, the rule with more specified conditions (more specific) wins.
  • Otherwise, the rule with the highest specificity (most fields set) is chosen; ties are broken by earlier config order.

Examples:

• Float dialogs for a specific app but tile others:

app_rules = [
  { app_id = "com.example.X", title_regex = "Dialog", floating = true },
  { app_id = "com.example.X", floating = false },
]

• Float any "Preferences" window for any app:

app_rules = [
  { title_substring = "Preferences", floating = true },
]

---

[modifier_combinations]

Define reusable modifier combinations to avoid repetition in the keybindings table.

• Example:

[modifier_combinations]
comb1 = "Alt + Shift"

Then use comb1 in [keys] entries like "comb1 + H" = { move_node = "left" }.

---

[keys]

Keybindings map strings (modifier + key) to commands or command objects.

• Syntax: use quotes around the key combination: "Alt + Shift + H" = ...
• Supported modifiers: Alt, Ctrl, Shift, Meta (Meta is Command on macOS).
• Available modifier tokens (generic or side-specific): Alt/Option, AltLeft/OptionLeft, AltRight/OptionRight, Ctrl/Control, CtrlLeft/ControlLeft, CtrlRight/ControlRight, Shift, ShiftLeft, ShiftRight, Meta/Cmd/Command, MetaLeft/CmdLeft/CommandLeft, MetaRight/CmdRight/CommandRight.
• Arrow keys can use ArrowUp/Up, etc. Spacing is flexible.

The configuration parses key strings into the internal hotkey structure; modifier combinations defined in [modifier_combinations] will be expanded before parsing.

Example bindings:

"Alt + H" = { move_focus = "left" }
"Alt + Shift + Left" = { join_window = "left" }
"Alt + 1" = { switch_to_workspace = 1 }
"comb1 + S" = { switch_to_workspace = 2 }

Note about comb1 usage: define comb1 in [modifier_combinations] and reference it in [keys].

commands

• toggle_space_activated — Toggle whether the focused macOS space is activated (managed) by rift.
• next_workspace / prev_workspace — Switch to next / previous virtual workspace.
• switch_to_workspace — Switch to a specified workspace (argument: index).
• move_window_to_workspace — Move the focused window to a specified workspace.
• create_workspace — Create a new virtual workspace.
• switch_to_last_workspace — Switch to the last active workspace.
• next_window / prev_window — Focus the next/previous window in the current workspace (e.g. "Alt + J" = { next_window = true }, "Alt + K" = { prev_window = true }).
• ascend / descend — Move focus up/down the layout tree hierarchy (e.g. "Alt + Shift + J" = { ascend = true }, "Alt + Shift + K" = { descend = true }).
• move_focus — Move focus in a direction: "left", "right", "up", "down".
• move_node — Move the focused node/window in a direction within the layout.
• join_window — Join the focused window into the branch in the given direction.
• toggle_stack — Toggle stacked state for the selected container (replaces older stack_windows / unstack_windows).
• toggle_orientation — Toggle global split/stack orientation behavior.
• unjoin_windows — Unjoin previously joined windows (separate joined nodes).
• toggle_window_floating — Toggle the focused window between tiled and floating.
• toggle_focus_floating — Raises floating windows from the current workspace so they can be accessed.
• toggle_fullscreen — Toggle full-layout fullscreen for the current window (ignores outer gaps).
• toggle_fullscreen_within_gaps — Toggle fullscreen that respects configured outer gaps (fills tiling area but keeps outer gaps).
• resize_window_grow / resize_window_shrink — Smartly resize the current selection.
• resize_window_by — Resize the current selection by a specific amount (float) (e.g. "Alt + \\" = { resize_window_by = { amount = 25.0 } }).
• debug — Print the active layout tree / debug information to the console.
• serialize — Dump rift's internal state to stdout (useful for bug reports and debugging).
• show_mission_control_all — Show all workspaces in mission control.
• show_mission_control_current — Show current workspace in mission control.
• exec — Execute an external command. Argument: a string or an array of strings. Example: "exec" = "alacritty" or exec = ["sh", "-c", "echo hello"].
• move_mouse_to_display = N or UUID. Examples: "Alt + Shift + A" = { move_mouse_to_display = 0 } or "Alt + Shift + S" = { move_mouse_to_display = 1 }
• move_window_to_display — Move a window to a display by direction/index/UUID (optionally specify window_id) (e.g. "Ctrl + Alt + D" = { move_window_to_display = { selector = "right" } }).