OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config medium occasional DISPUTE

Stop the screenshot window picker deleting your own TAB, RETURN and arrow binds

omarchyhyprland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

The mechanism is real. utilities.lua on 4.0.4-1 and on quattro binds the picker keys on layer.opened and calls keybind:unbind() on each handle. Issue #12546 (open) reports the loss with a reproduction. Reading Hyprland v0.56.2 source sharpens the cause. LuaKeybind.cpp keybindRemove calls removeKeybind(modmask, {key, keycode, catchAll}), and that function erases every bind whose key string is exactly equal, case included. hl.unbind normalises case, but this path does not. So a user bind spelled CTRL + TAB is removed and one spelled CTRL + Tab survives. The record missed this, and it gives a simpler mitigation. The cause and fix were rewritten to say so. The timer workaround is kept, and hl.timer's {timeout, type = "oneshot"} signature was confirmed in LuaBindingsToplevel.cpp. The case-sensitivity was read in source and not exercised. Running slurp here would have touched the operator's session.

The cause above was rewritten on 2026-10-05 to match this note; the fix was corrected by the audit itself.

Symptom

A custom binding on CTRL+TAB, TAB, RETURN, CTRL+RETURN or an arrow key (for example a window switcher on CTRL+TAB) randomly stops working. Nothing in the logs, hyprctl binds simply has no entry for it any more. It comes back after hyprctl reload or a re-login, then vanishes again later. It disappears right after you take a screenshot with the window picker (PRINT).

Cause

Omarchy 4.0.4's default/hypr/bindings/utilities.lua binds RETURN, CTRL + RETURN, TAB, CTRL + TAB and LEFT, RIGHT, UP, DOWN whenever a layer named selection opens (slurp's picker). It keeps the handles and calls keybind:unbind() on each when the last such layer closes. Its comment says this protects same-key user binds. It does not. In Hyprland 0.56.2 a handle's unbind() calls CKeybindManager::removeKeybind(modmask, key). That erases every bind whose modifier mask, key text and keycode equal the handle's, not only the bind the handle refers to. The key text comparison is exact and case-sensitive. A user bind spelled the way Omarchy spells it (CTRL + TAB, RETURN, LEFT) is removed, and one spelled CTRL + Tab, Return or Left is not. The bind stays gone until the next config reload. Any layer-shell client that names its layer selection triggers it, not only the screenshot tool. Confirmed by reading /usr/share/omarchy/default/hypr/bindings/utilities.lua on 4.0.4-1 (unchanged on quattro), and src/config/lua/objects/LuaKeybind.cpp and src/managers/KeybindManager.cpp at Hyprland v0.56.2. The case behaviour was read in source and not exercised.

Fix

**Omarchy 4 on Hyprland 0.56.2.** Use one of these three options in ~/.config/hypr/bindings.lua.

  1. Move your binding to a chord the picker does not borrow. The picker borrows RETURN, TAB, LEFT, RIGHT, UP and DOWN, both bare and with CTRL. Anything else is safe.
  1. Keep the chord and spell the key in different case from Omarchy's upper-case names. The picker's removal compares key text exactly, so this bind survives it:

o.bind("CTRL + Tab", "Window switcher", "my-window-switcher")

Use Return, Left, Right, Up and Down the same way. This depends on how 0.56.2 compares key text, so check it again after a Hyprland update.

  1. Re-add the bind after the last selection layer closes. Replace the command with yours. The short timer matters, because Omarchy unbinds from its own handler for the same event and the order of the two handlers is not fixed.

local function bind_window_switcher()
  hl.unbind("CTRL + TAB")
  o.bind("CTRL + TAB", "Window switcher", "my-window-switcher")
end
bind_window_switcher()

local my_selection_layers = 0
hl.on("layer.opened", function(layer)
  if layer.namespace == "selection" then
    my_selection_layers = my_selection_layers + 1
  end
end)
hl.on("layer.closed", function(layer)
  if layer.namespace ~= "selection" or my_selection_layers == 0 then return end
  my_selection_layers = my_selection_layers - 1
  if my_selection_layers > 0 then return end
  hl.timer(bind_window_switcher, { timeout = 50, type = "oneshot" })
end)

To get the bind back right now without editing anything, reload the config from a terminal: hyprctl reload.

Verify


hyprctl binds -j | grep -c '"description": "Window switcher"'   # 1
slurp & sleep 1; pkill slurp; sleep 1
hyprctl binds -j | grep -c '"description": "Window switcher"'   # still 1

Sources

screenshot-picker-removes-user-binds-on-tab-return-arrows