Every binding that opened a menu or panel ran omarchy-menu or
omarchy-shell, which starts a qs client just to deliver one IPC call:
~60ms before the shell heard about the keypress.
The shell now registers a Hyprland global shortcut for each menu route
and panel in default/omarchy/shortcuts, and o.bind turns { menu = ... }
and { panel = ... } into hl.dsp.global for those, so a keypress spawns
nothing. A route or panel missing from the list binds through the
command as before. The default menu and panel bindings use the new form.
SUPER+SPACE opens the menu in ~31ms instead of ~94ms, measured from a
simulated keypress until the menu layer maps.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
3.8 KiB
Hyprland Configuration
Read this before changing keybindings, monitors, window rules, or any other Hyprland (window manager) configuration.
Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's defaults, so overrides go here:
~/.config/hypr/
├── hyprland.lua # Main config (loads Omarchy defaults, then user files)
├── bindings.lua # Keybindings
├── monitors.lua # Display configuration
├── input.lua # Keyboard/mouse settings
├── looknfeel.lua # Appearance (gaps, borders, animations)
├── autostart.lua # Startup applications
├── hyprsunset.conf # Night light / blue light filter
└── xdph.conf # Screen sharing / desktop portal
Key behaviors (the .lua files):
- Hyprland auto-reloads on config save (no restart needed for most changes)
- Use
hyprctl reloadto force reload - After ANY Hyprland Lua config change, validate with
hyprctl reloadfollowed byhyprctl configerrors - If
hyprctl configerrorsreports errors, address them and rerun validation until clean or until a real blocker is identified - Use
omarchy refresh hyprlandto reset the Lua config files to defaults
The two .conf files are read by separate processes, so hyprctl neither
applies nor validates them:
hyprsunset.conf(night light): apply changes withomarchy restart hyprsunset; reset withomarchy refresh hyprsunsetxdph.conf(screen-sharing portal): applies when the portal restarts, e.g. on next login
Keybindings
Edit ~/.config/hypr/bindings.lua. Format:
o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
o.bind("SUPER + B", "Browser", { launch = "chromium" }) -- launch wraps with uwsm-app
o.bind("SUPER + M", "Theme menu", { menu = "theme" }) -- toggle an Omarchy menu route
o.bind("SUPER + N", "Network", { panel = "omarchy.network" }) -- toggle a shell panel
Prefer { menu = ... } and { panel = ... } over running omarchy-menu toggle ... or omarchy-shell shell toggle ... as a command. Routes and panels listed in $OMARCHY_PATH/default/omarchy/shortcuts go straight to the running shell as Hyprland global shortcuts, with no process started on each press; any other route or panel still works, through the command.
View current bindings: omarchy menu keybindings --print
IMPORTANT: When re-binding an existing key:
- First check existing bindings:
omarchy menu keybindings --print - If the key is already bound, use
o.rebind(...)to remove the existing binding and add its replacement. It takes the same arguments aso.bind(...). - Inform the user what the key was previously bound to
Example - rebinding SUPER+F (which is bound to fullscreen by default):
-- Replace SUPER+F (was: fullscreen) with the file manager.
o.rebind("SUPER + F", "File manager", { launch = "nautilus" })
Tell the user which action was replaced. Use hl.unbind(...) to remove a binding without replacing it.
Display/Monitors
Edit ~/.config/hypr/monitors.lua. Format:
hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })
hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })
List monitors and supported modes: hyprctl monitors all
Window Rules
CRITICAL: Hyprland window rules syntax changes frequently between versions.
Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:
DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.
Window rules go in ~/.config/hypr/hyprland.lua or a required Lua module. Prefer Omarchy's o.window(match, rules) helper — see examples in $OMARCHY_PATH/default/hypr/windows.lua.