Files
omarchy/docs/desktop/hyprland.md
T
root ffdc71b5cd wip(keys): macOS-style key layers for the Corne
Points dot_config/hypr at its mac-binding branch (Command layer on SUPER,
window management on ALT, screenshots on SUPER + CTRL + S, apps on the CAG
layer) and documents it, with the Ghostty side on prdlk/ghostty's
mac-binding branch. The scratchpad resident becomes a kitty
(kitty-scratch), skipped by terminal cycling. Work in progress.
2026-11-12 14:00:16 -05:00

33 KiB
Raw Blame History

Hyprland

Hyprland Lua config layered on Omarchy — scrolling layout, centered Ghostty master layout, terminal-only blur, monitors, and the omarchy-* helper scripts.

Hyprland is a dynamic tiling Wayland compositor. This config uses Hyprland's Lua configuration and sits on top of Omarchy, which provides the defaults, theme, menus, and omarchy-* commands. The files here only override.

Note

Linux desktop and laptop roles only. .chezmoiignore.tmpl skips ~/.config/hypr/** on other roles. The omarchy-* scripts are not listed there, so chezmoi applies them on every role and OS; they only take effect where Omarchy is installed.

dot_config/hypr is a git submodule (prdlk/hypr). Edit inside the submodule, commit there, then commit the updated pointer in the chezmoi repo.

Files

Source (repo) Target Purpose
dot_config/hypr/hyprland.lua ~/.config/hypr/hyprland.lua Entry point, workspace and window rules
dot_config/hypr/autostart.lua ~/.config/hypr/autostart.lua Extra autostart (empty)
dot_config/hypr/bindings.lua ~/.config/hypr/bindings.lua Keybindings
dot_config/hypr/command.lua ~/.config/hypr/command.lua Command layer: SUPER + key → the app's CTRL + key (macOS Command semantics)
dot_config/hypr/input.lua ~/.config/hypr/input.lua Key repeat, tablet/touch mapping
dot_config/hypr/looknfeel.lua ~/.config/hypr/looknfeel.lua Layout, decoration, blur
dot_config/hypr/monitors.lua ~/.config/hypr/monitors.lua Monitor modes and positions
dot_config/hypr/nav.lua ~/.config/hypr/nav.lua ALT [+ SHIFT] + H/J/K/L focus and move
dot_config/hypr/pip.lua ~/.config/hypr/pip.lua ALT + SHIFT + P picture-in-picture that follows the focused monitor
dot_config/hypr/master.lua ~/.config/hypr/master.lua Keeps Ghostty the master on master-layout workspaces
dot_config/hypr/hyprsunset.conf ~/.config/hypr/hyprsunset.conf Night-light profile
dot_config/hypr/xdph.conf ~/.config/hypr/xdph.conf xdg-desktop-portal-hyprland
dot_config/hypr/dot_luarc.json ~/.config/hypr/.luarc.json Lua language server settings
dot_local/bin/executable_omarchy-* ~/.local/bin/omarchy-* Helper scripts (see below)

None are templates. Hyprland and Omarchy are not in .chezmoidata/packages.yaml. They come from the Omarchy install.

Entry point

hyprland.lua loads Omarchy, then the personal files, then Omarchy's toggles:

~/.config/hypr/hyprland.lua

dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")
require("default.hypr.omarchy")

require("hypr.monitors")
require("hypr.input")
require("hypr.bindings")
require("hypr.looknfeel")
require("hypr.autostart")

require("default.hypr.toggles")

Omarchy's default bindings stay enabled. omarchy_default_bindings and omarchy_preinstalled_bindings are left commented. bindings.lua unbinds each default it replaces.

Workspace rules

Workspace Monitor
1 (default), 2, 3, 4 The main external display: desc:Apple Computer Inc StudioDisplay 0x984262A7 if connected, else desc:Samsung Electric Company S34CG50 HNTY501103 (Studio Display while neither is). Chosen at config load; monitors.lua reloads the config when the main external changes, and existing workspaces 1–4 are moved over
5 (default), 6, 7, 8 eDP-1
name:claude, name:fastmail, name:beeper, name:youtube eDP-1; created on demand, one per app (window rules below)

default marks the workspace each monitor shows when it connects.

Window rules

Class Rule
^brave-www\.tldraw\.com__-Default$ Workspace 3
^tldraw-offline$ Workspace 5, fullscreen
^kitty-scratch$ special:scratchpad silent
^com\.anthropic\.Claude$ name:claude, maximized (follows the window there)
^com\.fastmail\.Fastmail$ name:fastmail, maximized (follows)
^Beeper$ name:beeper, maximized (follows)
brave-(www\.)?youtube\.com__.*, title not matching .*Picture.?in.?[Pp]icture.* name:youtube, maximized (follows)
^(ai\.storyteller\.)?<app>$ for deckcraft, figcraft, filmcraft, gridcraft, pdfcraft, photocraft, vectorcraft, wordcraft (Craft AppImages in ~/Applications) name:<app>, one workspace per app on the focused monitor (follows). PdfCraft and PhotoCraft declare a bare StartupWMClass, hence the optional prefix
^io\.github\.lgse\.Strata$ (strata) +floating-window: Omarchy floats, centers and sizes it 875×600
^brave-home\.google\.com__.* special:home silent
^ai\.elementlabs\.lmstudio$ special:lmstudio silent
^(com\.nousresearch\.)?[Hh]ermes$ (Hermes desktop: Hermes from the packaged runtime, com.nousresearch.hermes after hermes update) special:hermes silent
^kitty(-.*)?$ (kitty and the kitty-tmux, kitty-herdr, kitty-goliath hosts) group = "set always": opens as a group; with group.auto_group on (the default), a kitty opened while a kitty group is focused joins it as a tab
^com\.mitchellh\.ghostty$ group = "set always", same as kitty; a Ghostty opened while a Ghostty group is focused joins it as a tab
^brave-origin$ group = "barred deny": never opens as a tab of the focused group; no window joins a group Brave starts

kitty and Ghostty are separate group families, and Brave Origin never shares a group with kitty. Listeners in hyprland.lua enforce this beyond what the rules can:

  • window.open_early: when the new window conflicts with the focused group, group.auto_group is switched off for that one map (restored by a 1 ms timer), so the window opens as a group of its own.
  • window.update_rules with a group of two or more: the group keeps the family of its first kitty or Ghostty tab that is not the focused window (the one that just arrived); conflicting members are moved out, kitty and Ghostty as a group of their own, Brave as a plain window. This catches the move-into-group dispatchers (SUPER + ALT + arrows, nav.lua) and groupbar drags.
  • window.update_rules on an ungrouped Ghostty: it becomes a group of its own again, so Ghostty is always tabbed, even after SUPER + ALT + G (move out of group) or ALT + ,.

Scratch residents are placed silent so that omarchy-toggle-scratch decides when to reveal them. The YouTube rule matches both youtube.com and www.youtube.com because Chromium's class changes once a video plays. It excludes the picture-in-picture overlay so Omarchy's own PiP rule still applies.

Input

input.lua:

  • repeat_delay = 250 (Omarchy's value), repeat_rate = 50 (raised from 40). The file's comments record that 200/50 felt too fast. The typing lag it was meant to fix came from the keyboard's firmware tap-hold handling and was fixed on the keyboard itself.
  • Tablet and touch devices are pinned to one output each:
Device Output Extra
elan9008:00-04f3:43c7-stylus (Flow Z13 pen) eDP-1
elan9008:00-04f3:43c7 (Flow Z13 touchscreen) eDP-1 Taps land on the panel instead of the focused monitor
wacom-intuos-bt-s-pen The main external display (Studio Display or Samsung ultrawide) active_area_size = { 152, 152 × height / width } (85.5 on the Studio Display, 63.6 on the ultrawide), active_area_position = { 0, 0 } — a full-width band with the display's aspect ratio

The layout, touchpad, and gesture examples in the file are commented out. Palm rejection is done by a libinput quirks file in /etc, which chezmoi does not manage.

Look and feel

looknfeel.lua loads after the Omarchy theme's hyprland.lua, so its values override the theme's. The theme sets colors. This file sets everything else. The approach is flat windows by default, with blur only behind terminals.

Setting Value
general.layout scrolling (instead of Omarchy's dwindle; per-workspace layouts saved by omarchy-hyprland-workspace-layout-toggle or omarchy-toggle-master still win)
master.orientation center: the master column sits in the middle, slaves split left and right of it
master.slave_count_for_center_master 0: centered from the first window on (Hyprland waits for 2 slaves by default); a lone window is centered at mfact width
master.new_status slave (Omarchy: master), so new windows never take the master column from Ghostty
decoration.rounding 0
decoration.dim_special 0.33 (darkens the desktop behind any open scratch workspace)
decoration.blur enabled; size 5, passes 2, brightness 0.8, contrast 1.1, vibrancy 0.15, noise 0.01, new_optimizations, popups = false
decoration.shadow disabled
group.groupbar.gradient_rounding 0
group.groupbar.disable_when_only true: no tab bar on a group of one (kitty and Ghostty always open as a group); it appears when a second window joins
Workspace animation disabled (hl.animation({ leaf = "workspaces", enabled = false }))

Blur must be enabled globally before any window can use it, so every window tagged default-opacity gets no_blur = true, and terminals get it back:

~/.config/hypr/looknfeel.lua

o.window({ tag = "default-opacity" }, { no_blur = true })
o.window(
  "^(kitty(-.*)?|Alacritty|com\\.mitchellh\\.ghostty|foot|org\\.codeberg\\.dnkl\\.foot|wezterm)$",
  { no_blur = false }
)

Omarchy's stock fade (0.985 active / 0.96 inactive) is kept. Terminals get their transparency from kitty's background_opacity 0.9 (see kitty). The comments give the reason for limiting blur: the cyberdream and Spectra themes enabled rounding, blur, and shadow on every window, and that costs frame time on an iGPU driving the laptop panel plus a 5K display.

Monitors

monitors.lua:

Output Mode Position Scale
any (fallback) preferred auto 3.2
desc:Apple Computer Inc StudioDisplay 0x984262A7 (Studio Display, Thunderbolt; connector name varies, e.g. DP-4) 5120x2880@60 0x0 2
eDP-1 (laptop) 2560x1600@180 <external width>x0: 2560x0 with the Studio Display, 3440x0 with the ultrawide, 0x0 undocked 2
desc:Samsung Electric Company S34CG50 HNTY501103 (ultrawide, USB-C to HDMI from the iGPU; shows up as a DP-n connector) 3440x1440@100 0x0 1

GDK_SCALE=3 is exported. The main external display always sits at 0x0, left of the laptop panel. eDP-1's x is computed at config load from the connected external's mode width divided by its scale, instead of auto-right, so the layout never depends on which monitor Hyprland configured first. Externals are matched by EDID description, because the Studio Display comes back as a different DP-n after a replug or on another port, and a connector-name rule would hand it the fallback (auto, scale 3.2). monitors.lua returns the "main external display" (Studio Display, else Samsung ultrawide) used by the workspace rules, the Wacom mapping, and omarchy-toggle-scratch, and reloads the config on hotplug when it changes, which also recomputes eDP-1's position.

~/.config/uwsm/env-hyprland (source dot_config/uwsm/env-hyprland, Linux desktop/laptop only) is sourced by uwsm before Hyprland starts. It sets AQ_DRM_DEVICES to the AMD iGPU, resolved from /dev/dri/by-path/pci-0000:c4:00.0-card, so Hyprland never opens the Thunderbolt eGPU (RTX 5060 Ti, compute only: AI models, CUDA). Every display, the Samsung ultrawide included, hangs off the iGPU. It leaves the variable unset if that path is missing. It also sets __EGL_VENDOR_LIBRARY_FILENAMES to Mesa's 50_mesa.json, so neither Hyprland nor session apps load libEGL_nvidia and hold /dev/nvidiactl; CUDA does not use EGL.

The system side (kernel cmdline, nvidia without KMS, thunderbolt host_reset=0) lives outside chezmoi.

hyprsunset and portal

~/.config/hypr/hyprsunset.conf

profile {
    time = 07:00
    identity = true
}

The identity profile stops hyprsunset from tinting the screen. A commented 20:00 / 4000 K night profile and an o.launch_on_start("hyprsunset") hint remain in the file.

~/.config/hypr/xdph.conf

screencopy {
    allow_token_by_default = true
    custom_picker_binary = hyprland-preview-share-picker
}

Screen-share requests get a restore token by default and use hyprland-preview-share-picker as the source picker.

.luarc.json

Configures lua-language-server for the Lua config: the library path is /usr/share/hypr/stubs, checkThirdParty is off, and hl and o are declared as globals.

autostart.lua contains only a commented o.launch_on_start example.

Keybindings

Every binding defined in bindings.lua and command.lua. Bindings not listed here are Omarchy defaults. The Replaces column gives the Omarchy default that was unbound first.

The Corne keeps its macOS keymap, and the layers follow a Mac running AeroSpace: right thumb RGui_T Space is SUPER here and Command on macOS, left thumb LAlt_T Tab is ALT / Option, left thumb LCtl_T Space is CTRL, and the one-shot OSM CAG key is CTRL + ALT + SUPER for the next key.

Layer Job
ALT [+ SHIFT] + key Window management: focus and move H/J/K/L, layout, size, workspaces on Q W E R Y U I O.
SUPER [+ SHIFT] + key The app's own shortcut, Command-style (command.lua, below). System keys left on it: Q, O / SHIFT + O, TAB, SPACE, ESCAPE, BACKSPACE.
SUPER + CTRL [+ SHIFT] + key System: screenshots, Omarchy panels and menus, a few apps.
SUPER + CTRL + ALT [+ SHIFT] + key Apps and numbered workspaces: tap OSM CAG, then the key (SHIFT held for the second set).

ALT chords never reach an app. tmux's M-h/j/k/l pane resize (tmux.conf) and fish's alt+h/j/k/l/c/t/m/x/z/a lose their keys; ALT + B/D/F, ALT + . and ALT + 1..9 (tmux windows) stay free on purpose. With dictation installed, Omarchy's ALT + Alt_R is push-to-talk, so ALT belongs on the left thumb.

hl.unbind matches the chord as it was written, modifier order included: an unbind of SUPER + CTRL + SHIFT + R leaves Omarchy's SUPER + SHIFT + CTRL + R bound. Unbinds copy Omarchy's spelling.

Command layer (command.lua)

SUPER + key arrives in the focused app as CTRL + key, SHIFT kept: Cmd+C/V/X/Z clipboard and undo, Cmd+Shift+Z redo, Cmd+T/W/Shift+T tabs, Cmd+L address bar, Cmd+R reload, Cmd+F find, Cmd+1..9 tab N, Cmd+=/-/0 zoom, Cmd+, settings, Cmd+/ comment, Cmd+Return send. Translated chords: SUPER [+ SHIFT] + A..Z except Q and O, and SUPER + 0..9, ,, /, -, =, Return (63 binds; each unbinds whatever Omarchy had there first, which is why it loads last). It is Omarchy's universal-clipboard mechanism (send_key_state down, then up 50 ms later, mods given explicitly so the held SUPER does not leak into the chord), applied to every key.

Terminals never get a bare CTRL chord (Ctrl+C is SIGINT, Ctrl+W deletes a word):

Focused window SUPER [+ SHIFT] + key becomes
Ghostty (com.mitchellh.ghostty) CTRL + SHIFT + key, Ghostty's tmux chords (Super+T new tmux window, Super+C copy, Super+1 window 1), only when ~/.config/ghostty/config binds that ctrl+shift chord; otherwise nothing, since Ghostty passes an unbound one on as a CSI-u key. The config is read when Hyprland loads: hyprctl reload after adding a Ghostty ctrl+shift bind. See Ghostty.
Other terminal (Omarchy's terminal tag: kitty, foot, Omarchy TUIs) CTRL + SHIFT + C / V for SUPER + C / V; every other chord as the SUPER chord itself, so kitty's own super maps keep working (kitty encodes an unmapped one as CSI-u).
Anything else (Brave Origin, web apps, Electron, GTK, Omarchy panels) CTRL [+ SHIFT] + key.

Omarchy's binds on those chords are gone: select all and universal clipboard (subsumed), SUPER + 1..0 workspaces (now CAG + 1..0), toggle floating (now ALT + T), grouping (now ALT + ,), input method (now CAG + I), Docker and Activity (now CAG + SHIFT + D / T), monitor scaling up (now SUPER + CTRL + /). The SUPER + SHIFT + letter browser, calendar, editor, Omawrite and X launchers are dropped; vicinae and the apps menu start them.

Windows

Keys Action Replaces
SUPER + Q Close window same (made explicit)
ALT + H / J / K / L Focus left / down / up / right (nav.focus); at the edge, the monitor that way —
ALT + SHIFT + H / L Move left / right (nav.move): swap the column; at the edge, carry the window to the monitor that way. Floating: bottom-left / bottom-right corner —
ALT + SHIFT + J / K Move down / up: swap within the column; at its bottom / top, carry the window to the next / previous workspace on this monitor. Floating: top-left / top-right corner —
ALT + / omarchy-toggle-layout — flip workspace layout —
ALT + SHIFT + / omarchy-toggle-master — master layout on/off for the active workspace —
ALT + X Toggle split (dwindle togglesplit) —
ALT + T Toggle floating/tiling —
ALT + , Toggle window grouping (tabs) —
ALT + C Center the window (floating) or its column (scrolling) —
ALT + M Maximize —
ALT + SHIFT + M Full screen —
ALT + SHIFT + P pip.toggle — toggle picture-in-picture (below) —
SUPER + CTRL + F Zen mode: Omarchy's full-screen-desktop toggle (bar hidden, gaps 0) tiled full screen
SUPER + BACKSPACE Toggle the Quake console (special:qconsole) toggle transparency
SUPER + TAB Birdseye overview: omarchy-shell shell toggle erasmus.birdseye (live thumbnails of every window on every workspace; Tab / arrows select, Enter jumps, Escape closes) next workspace
SUPER + SHIFT + TAB Previous window in the active workspace previous workspace

ALT + TAB / ALT + SHIFT + TAB keep Omarchy's next / previous window. SUPER + SHIFT + TAB walks a ring built only from the active workspace's mapped windows, ordered by stable_id. Grouped windows stay in the ring and hidden ones are skipped. It raises the focused window afterwards. It avoids cyclenext, which would pull in a hidden scratchpad. pip.lua makes the active window a picture-in-picture window: leaves maximized/fullscreen (a maximized window refuses to float or pin), tags it follow-pip, floats and pins it, resizes it to a 16:9 box 30% of the focused monitor's width (480×270 on eDP-1, 768×432 on the Studio Display), and places it in the bottom-left corner, 10 px (matching general:gaps_out) inside the reserved area. Pressing it on a tagged window removes the tag, unpins and re-tiles it. Being pinned, the window shows on every workspace of its monitor; a monitor.focused listener moves every follow-pip window to the newly focused monitor and refits it there one loop later (Hyprland keeps a floating window's pixel size and offset across monitors). Focus stays where it was. The tag survives hyprctl reload. Pin and float are dispatched with on/off because set toggles on Hyprland 0.56.

nav.lua picks the neighbor itself rather than using Hyprland's directional focus, which searches the whole layout: on the scrolling tape, J/K with nothing above or below jumped to an off-screen column. A neighbor must lie past the focused window's centre on the move axis and overlap it on the other axis; inactive group tabs share their group's cell and are skipped. So J/K stay in the column and H/L walk the columns.

  • Focus: H/L step through a group's tabs before leaving the group. At the tape's edge the key focuses the monitor that way (eDP-1 is right of the external); nothing past the outer edges. Floating windows use Hyprland's directional focus.
  • Move: a group on either side makes the move group aware (window.move with group_aware), merging into or leaving a group. Otherwise H/L on a scrolling workspace swap the whole column (swapcol), and other layouts and J/K swap windows. With no neighbor, H/L move the window to the monitor that way and J/K to the previous/next workspace by id on the same monitor, never wrapping; focus follows. Floating windows go to a corner of their monitor without resizing, inside the reserved area (the bar) and inset 10 px (general:gaps_out), clockwise from bottom-left.

binds.movefocus_cycles_groupfirst = true stays set for Omarchy's SUPER + arrows, which still use Hyprland's directional focus.

Workspaces and monitors

Keys Action Replaces
ALT + Q / W / E / R Switch to workspace 1 / 2 / 3 / 4 (main external display) —
ALT + Y / U / I / O Switch to workspace 5 / 6 / 7 / 8 (laptop panel) —
ALT + SHIFT + Q / W / E / R / Y / U / I / O Move window to workspace 1–8 —
SUPER + CTRL + ALT + 1..0 Switch to workspace 1–10 — (Omarchy's SUPER + 1..0)
SUPER + CTRL + ALT + SHIFT + 1..0 Move window to workspace 1–10 — (Omarchy's SUPER + SHIFT + 1..0, unbound)
ALT + A omarchy-toggle-scratch scratchpad: a scratch kitty (kitty --class=kitty-scratch --session=none) —
SUPER + O Focus next monitor pop window out
SUPER + SHIFT + O Move window to next monitor Obsidian
SUPER + SHIFT + CTRL + ALT + W Workspace name:w —
SUPER + SHIFT + CTRL + ALT + H Workspace name:h —
SUPER + CTRL + ALT + X Workspace name:x —

Named workspaces provide the per-app workspaces. SUPER + ALT + S (send to scratchpad) keeps its Omarchy default.

Sizing

Keys Action
ALT + Z omarchy-cycle-window-size — next preset size
ALT + SHIFT + Z omarchy-cycle-window-size prev
ALT + - / ALT + = Width −100 / +100 px
ALT + SHIFT + - / ALT + SHIFT + = Height −100 / +100 px
SUPER + ALT + C Fit active column (scrolling layout only)
SUPER + SHIFT + ALT + C Fit visible columns (scrolling layout only)

Applications

CAG is SUPER + CTRL + ALT: one tap of the Corne's OSM CAG, then the key.

Keys Action Replaces
SUPER + CTRL + A Claude Desktop: omarchy-launch-or-focus com.anthropic.Claude claude-desktop, on its own workspace name:claude on eDP-1 audio panel
SUPER + CTRL + H omarchy-toggle-scratch home (Google Home) toggle window gaps
SUPER + CTRL + L omarchy-toggle-scratch lmstudio (LM Studio) toggle window gaps
CAG + H omarchy-toggle-scratch hermes (Hermes desktop) —
CAG + J omarchy-cycle-terminal —
CAG + K omarchy-cycle-browser —
CAG + G omarchy-cycle ghostty —
CAG + O omarchy-cycle obsidian —
CAG + F strata: omarchy-launch-or-focus io.github.lgse.Strata "gtk-launch io.github.lgse.Strata" full screen desktop (now SUPER + CTRL + F)
CAG + E Fastmail: omarchy-launch-or-focus com.fastmail.Fastmail "gtk-launch com.fastmail.Fastmail", on name:fastmail on eDP-1 World clock (omarchy.elsewhen panel)
CAG + M Beeper: omarchy-launch-or-focus Beeper "gtk-launch beeper", on name:beeper on eDP-1 —
CAG + Y YouTube: omarchy-launch-or-focus 'brave-(www\.)?youtube\.com__' "gtk-launch YouTube", on name:youtube on eDP-1 web apps cycle
CAG + T tldraw offline: omarchy-launch-or-focus tldraw-offline "gtk-launch tldraw-offline" show time
CAG + W Unbound toggle weather
CAG + I / CAG + SHIFT + I omarchy-input-method cycle / cycle back —
CAG + SHIFT + G Goliath: kitty --class=kitty-goliath --title=goliath --session=none --config ~/.config/kitty/goliath.conf mosh goliath; new tabs and splits there are goliath sessions too (see kitty, SSH and mosh) —
CAG + SHIFT + D Docker TUI (omarchy-launch-docker-tui) —
CAG + SHIFT + T Activity (btop) —
SUPER + CTRL + / Monitor scaling up (SUPER + ALT + / scales down) —
SUPER + ALT + SHIFT + F uwsm-app -- "$HOME/.local/bin/strata" "$(omarchy-cmd-terminal-cwd)" — strata in the terminal's cwd unbound first (default unnamed)

strata is the default file manager: inode/directory in mimeapps.list and the org.freedesktop.FileManager1 D-Bus service both point at it (15-tools). The cwd bind uses the absolute path because ~/.local/bin may be missing from uwsm-app's PATH. A rule tagging com.thisisgm.flea.picker as +floating-window still sits between flea --picker marker comments, which the flea tool writes and removes itself.

Screenshots, session, menus

Keys Action Replaces
SUPER + CTRL + S omarchy-capture-screenshot region share menu
SUPER + CTRL + SHIFT + S omarchy-capture-screenshot windows —
SUPER + SHIFT + ALT + S omarchy-capture-screenshot fullscreen —
SUPER + CTRL + C Capture menu (screenshots and recordings), Omarchy default —
SUPER + SHIFT + Q omarchy-menu toggle system Calculator (XF86Calculator still opens it)
SUPER + SHIFT + BACKSPACE Dismiss last notification toggle window gaps
SUPER + CTRL + X omarchy-dictation toggle (only when o.dictation_installed()) —
F9 (hold) Push-to-talk: omarchy-dictation start on press, stop on release (only when o.dictation_installed()) —
SUPER + SPACE vicinae toggle (launcher; server is the vicinae.service user unit) Omarchy menu
SUPER + SHIFT + SPACE Unbound toggle top bar

SUPER + ALT + SPACE (apps menu) keeps its Omarchy default, as do the SUPER + CTRL panels (T theme, R / SHIFT + R reminders, B Bluetooth, N network, …). SUPER + RETURN and SUPER + SHIFT + RETURN lose Omarchy's terminal and browser launchers; terminals and browsers live on CAG + J / K, and SUPER + RETURN is Ctrl+Return in apps.

ScrollOverview plugin

When hl.plugin.scrolloverview is present, bindings.lua configures it:

Option Value
gesture_distance 300
scale 0.5
workspace_gap 100
layout vertical
wallpaper 2 (global and per-workspace)
blur true
shadow enabled, range 50

omarchy scripts

The scripts live in dot_local/bin/ as executable_omarchy-* and deploy to ~/.local/bin/. Each one calls the Lua dispatcher first (hyprctl dispatch "hl.dsp…") and falls back to the classic dispatcher name on older Hyprland.

omarchy-cycle

omarchy-cycle <app|browser|brave|terminal|ai|ghostty|kitty|kitty-CLASS|webapp|webapp-NAME>

Focuses an app's window, cycles to the next one on repeated presses, or launches the app when none is open. Windows are matched on class or initialClass (case-insensitive) and sorted by workspace, then address. If the focused window is not in the set, focus goes to the first one. Launches use setsid uwsm-app --.

Argument Matches Launches when none
webapp ^(webapp-|chrome-) re-runs as webapp-youtube
webapp-NAME webapp-NAME or ^chrome-.*NAME gtk-launch on the first WebApp-NAME*.desktop or *NAME*.desktop in ~/.local/share/applications
kitty ^kitty kitty
kitty-CLASS ^kitty-CLASS$ kitty --class kitty-CLASS (command from the empty KITTY_CMDS map, if set)
ghostty ghostty ghostty
browser zen, brave, chromium, google-chrome, firefox, librewolf, vivaldi, microsoft-edge, helium — excluding chrome-/webapp- web apps omarchy-launch-browser
brave ^brave (Brave Origin and its web apps) omarchy-launch-browser
terminal kitty, alacritty, ghostty, foot, wezterm (the kitty-scratch scratchpad kitty is excluded) omarchy-launch-terminal (xdg-terminal-exec: the OS default terminal from ~/.config/xdg-terminals.list, in the focused terminal's cwd)
ai claude|hermes hermes desktop
anything else ^APP$ the argument as a command

Bound to SUPER + CTRL + ALT + G (ghostty) and O (obsidian).

omarchy-cycle-browser / omarchy-cycle-terminal

One-line wrappers: omarchy-cycle brave and omarchy-cycle terminal. Bound to SUPER + CTRL + ALT + K and SUPER + CTRL + ALT + J.

omarchy-launch-browser

omarchy-launch-browser [--private] [url]

Shadows Omarchy's /usr/bin/omarchy-launch-browser (~/.local/bin comes first on PATH) and hands off to it. When Brave Origin is the default browser and not running, it prepends --restore-last-session --hide-crash-restore-bubble, so the first launch after a reboot or power-off reopens the last session's windows without the "Restore pages?" prompt. Chromium treats a killed browser as crashed and skips the restore; --hide-crash-restore-bubble clears that state. Private launches and launches into a running browser pass through unchanged.

omarchy-cycle-window-size

omarchy-cycle-window-size [next|prev]

Steps the focused window through preset widths 0.333, 0.5, 0.667 of the monitor.

  • Scrolling layout (tiled): sends colresize +conf / -conf, so the layout's own preset list is used.
  • Floating: resizes to the fraction × monitor width and 0.8 × monitor height, then centers. The index is stored per window.
  • Dwindle/master (tiled): sets splitratio to 2 × fraction, mirrored when the window is on the right or bottom half, clamped to 0.1–1.9. The index is stored per workspace.

Indices are stored in $XDG_STATE_HOME/omarchy/window-sizes/. Bound to ALT + Z and ALT + SHIFT + Z.

omarchy-toggle-layout

omarchy-toggle-layout [width]

Runs omarchy-hyprland-workspace-layout-toggle, then polls the workspace layout (6 × 50 ms). If it became scrolling, it runs colresize all <width> (default 0.75). Dwindle needs no widths. Bound to ALT + /.

omarchy-toggle-master

omarchy-toggle-master

Switches the active numbered workspace to the master layout through Omarchy's o.workspace_mode, saving it in ~/.local/state/omarchy/workspace-layouts/<id>.lua like omarchy-hyprland-workspace-layout-toggle, so it survives reloads and ALT + / sees it. The layout it replaced is kept in ~/.local/state/omarchy/master-toggle/<id>; the next press restores it (or the default layout if none was kept), and the saved-mode file is removed when that is the default. Named workspaces are skipped, as in Omarchy. Shares Omarchy's layout notification. Switching to master also runs require("hypr.master").enforce(), since a layout change fires no event. Bound to ALT + SHIFT + /.

master.lua makes every Ghostty node (a group counts once) a master and every other window a slave on the active workspace when it uses the master layout and holds a Ghostty window. It runs one loop after window.open, window.move_to_workspace, window.destroy, workspace.active, and config.reloaded. A Ghostty slave first swaps places with a non-Ghostty master (window.swap with window and target, focus untouched); Ghostty windows left over get addmaster and non-Ghostty masters left over get removemaster, both of which act on the focused window, so focus visits them and returns to the window that just opened, or else the one that was active. addmaster alone fails with two windows: Hyprland refuses to leave no slave while master:allow_small_split is off. Only the active workspace is fixed, because focusing a window elsewhere would switch workspace or monitor; other workspaces are fixed when they become active. Several Ghostty nodes stack in the center column.

omarchy-toggle-scratch

omarchy-toggle-scratch [scratchpad|home|lmstudio|hermes]
Profile Special workspace Home monitor Residents (class → launch)
scratchpad special:scratchpad Studio Display, else Samsung ultrawide kitty-scratch → kitty --class=kitty-scratch --session=none
home special:home focused brave-home\.google\.com__.* → gtk-launch 'Google Home'
lmstudio special:lmstudio focused ai\.elementlabs\.lmstudio → gtk-launch ai.elementlabs.lmstudio
hermes special:hermes focused (com\.nousresearch\.)?[Hh]ermes → gtk-launch hermes-desktop

If the workspace is visible, the script hides it. If not, it launches any resident with no window there, waits up to 8 s for the first new window, and reveals the workspace on the home monitor (or the focused one if the home monitor is absent). Launching only missing residents avoids duplicate web-app windows. Bound to ALT + A (scratchpad), SUPER + CTRL + H (Google Home), SUPER + CTRL + L (LM Studio), and SUPER + CTRL + ALT + H (Hermes).

  • Waybar: the bar used with this setup.
  • kitty: the herdr kitty config and the goliath kitty launched here.