Design useful keybindings and diagnose shortcut conflicts

You open the same folder several times a day. A useful shortcut should open that folder reliably, be easy to remember, and leave important desktop controls available. This guide adds that action, then shows how to replace an existing file-manager shortcut deliberately.

Use this with the Lua configuration described in configuration loading. Check omarchy version and Setup → Keybindings: the file should be ~/.config/hypr/bindings.lua. A .conf installation needs its own syntax. The examples use a source baseline, not a claim that the proposed key is free on your machine.

1. A shortcut has more than one possible owner

keyboard and layout → compositor binding → action or launched process
                    → application shortcut when the key reaches the app

Omarchy’s desktop bindings belong to Hyprland. Your browser, editor, terminal and Tmux each have their own bindings too. A compositor binding can prevent an application receiving the key. Applications that inhibit shortcuts, special modes and different layouts can change what you observe.

Choose a frequent action before choosing a key. Keep launch actions, window movement and temporary toggles in recognisable groups. Do not redesign the whole default map at once: the menu, terminal, window closing and workspace navigation provide recovery routes while you learn.

2. Inventory the existing behaviour

omarchy menu keybindings --print
hyprctl binds

The first is the Omarchy view of bindings; the second lets you inspect Hyprland’s loaded state. Lua actions can have a different low-level representation from a shell command, so do not expect identical text. Inspect your personal binding file as well, including any files it loads.

This exercise proposes Super + Ctrl + Alt + E for Documents. Check the actual loaded list for the whole modifier combination and key before using it. If occupied, choose another combination or postpone the addition. Do not treat a visually different spelling or modifier order as proof that it is unused.

Proposed key	Current action	Intended action	Scope
Super + Ctrl + Alt + E	Verify locally	Open Documents	New personal binding
Super + Shift + F	File manager in the documented defaults; verify locally	Open Documents	Optional replacement

The second row is a later exercise. Add the first before deciding whether replacement is worthwhile.

3. Test the command independently

command -v nautilus
xdg-user-dir DOCUMENTS

xdg-user-dir may identify a localized folder or a location outside ~/Documents. Use the actual existing directory you want. If it is ~/Documents, test:

nautilus "$HOME/Documents"

If that does not open the intended folder, fix the application or path before editing keys. A shortcut cannot repair a missing executable. The quotes preserve spaces in the path. Do not put private tokens or destructive commands into a binding just to test whether the key works.

4. Add the personal binding

Back up the existing file using a fresh name:

cp -i ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-shortcuts

Open Setup → Keybindings, add the following only after checking the key and path, then save and quit the editor (:wq in Neovim):

o.bind("SUPER + CTRL + ALT + E", "Open Documents", {
  launch = 'nautilus "$HOME/Documents"',
})

This is a Lua table passed to Omarchy’s helper. launch wraps the graphical application in its session launch path; the command’s inner double quotes protect the expanded directory. Substitute your actual directory if different. A raw command string and a tui launch have different purposes; use tui for an interactive terminal program rather than a GUI file manager.

Press the key on the desktop, then with a browser focused. Confirm the destination, not merely that some file-manager window appeared. Test a path containing spaces if that is your real use case.

5. Replace a default without adding a second action

If you decide that your existing Super + Shift + F should open this folder, first record its current action. Then use a replacement, not another ordinary addition:

o.rebind("SUPER + SHIFT + F", "Open Documents", {
  launch = 'nautilus "$HOME/Documents"',
})

The helper removes the existing binding for that key before adding the new one. o.bind only adds; it does not mean “replace anything already there.” hl.unbind removes without adding a replacement.

Keep only one deliberate final definition for a replaced key. Once the replacement is working, remove the extra Documents binding if you do not need two routes. Do not remove your terminal or menu shortcut as part of this exercise.

6. Diagnose the stage that failed

Observation	Next check
File saved, new binding absent from loaded list	Lua errors, file loading and editor exit
Binding loaded, direct command fails too	Executable, path and application
Direct command works, key does nothing	Actual key/layout, modifiers, focus and inhibition
Two actions fire	Duplicate additions or definitions in another loaded file
One keyboard works and another does not	Layout, physical key and key-name mapping
Terminal opens but interactive program exits	Correct TUI launch and command arguments

Use hyprctl configerrors when available to inspect parser errors. Correct the error nearest your changed lines rather than refreshing all configs. Search loaded bindings again after saving through the menu. If a key works outside one application, inspect that application’s modes and shortcut-inhibition behaviour before rebinding globally.

7. Undo and retain a small personal map

For this exercise, remove the lines you added and let the menu apply the saved file. Defaults load again through the normal configuration path; check that the original action returns. If you had earlier personal definitions for the same key, restore those from your checkpoint rather than guessing the original behaviour.

Restoring the whole saved file also removes later changes to that file, so compare it first. Never reset the entire desktop to undo one shortcut.

Your final record should contain the key, command, changed file, original action and reason. After a future update, compare this record with loaded bindings and rerun the real task. A shortcut is complete when it works in normal focus conditions and still leaves a route to recover.

Sources and related guides

Omarchy binding helpers · Official configuration guide · Hyprland bindings

Continue with window rules or keeping configurations through updates.