Skip to content

Let apps read and change named shortcuts with omarchy shortcut - #16131

Draft
nchudleigh wants to merge 16 commits into
omacom:quattrofrom
nchudleigh:feat/omarchy-shortcut
Draft

nchudleigh wants to merge 16 commits into
omacom:quattrofrom
nchudleigh:feat/omarchy-shortcut

Conversation

@nchudleigh

@nchudleigh nchudleigh commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Apps need a way to change global shortcuts without writing Hyprland config. This adds omarchy shortcut so an app can read and change a named shortcut, and Omarchy itself binds it and resolves conflicts. It replaces the approach in #14629.

omarchy shortcut get omarchy.dictation.hold            # F9 and ALT + Alt_R, one per line
omarchy shortcut set omarchy.dictation.hold F9 "SUPER + R"
omarchy shortcut set com.superwhisper.shortcut.hold Super_R \
  --description "Push to talk" --command "superwhisper start" --release "superwhisper stop"
omarchy shortcut reset omarchy.dictation.hold          # back to the default keys
omarchy shortcut list --json
  • Omarchy declares its own shortcuts with o.shortcut(id, spec) and their default keys. Dictation is the first: omarchy.dictation.toggle and omarchy.dictation.hold. Apps register their own under reverse-DNS ids, and can change the keys of omarchy.* shortcuts but not what they run.
  • A changed shortcut is stored as field=value lines in ~/.config/omarchy/shortcuts/<id>. Other programs write these files, so they are read as data and never loaded as Lua.
  • set and reset apply at once with hyprctl eval 'o.shortcuts.apply({"<id>", ...})', with no reload. Only the shortcuts a change names are rebound, so anything the user or a dictation backend unbound since the config loaded is left alone. get, list and set ask the running compositor what is bound, so they never show stale keys. set needs Hyprland running, because only the running config knows Omarchy's default keys and every other binding.
  • Conflicts: set refuses keys that a live binding or another named shortcut already uses. It exits 2 and names who holds them. With --json it returns {keys, description, id, submap, can_take} per conflict, so an app's shortcut recorder can offer to take them.
  • --force takes keys from another named shortcut, which keeps the rest of its keys, or from one of Omarchy's defaults, which comes back when the shortcut moves off its keys. That one case uses a reload, since only the config knows what the default was. --force can't take keys bound in the user's own bindings.lua, by a dictation backend, or inside a submap. Those would come back at the next reload, or the submap would break.
  • --release makes a hold shortcut such as push-to-talk, built on o.bind_hold. A modifier pressed on its own (Super_R, Alt_R) is matched with the modifier mask ignored, so apps don't need to know that Hyprland quirk. Rebinding a hold while its key is down finishes the hold first, so dictation never keeps recording.
  • Mouse buttons work as ordinary chords (SUPER + mouse:275). Double-press is left to Support double-press actions in Hyprland bindings #13576.

How Hyprland's hl.unbind behaves shapes the design. It matches the text a key was bound with, not the chord. It removes the key from every submap. And hl.unbind("all") clears every binding. So keys are validated in the CLI and in Lua (all, catchall and empty chord parts are refused), and taking a default unbinds it by its own spelling, which o.bind now records.

The full reference is in docs/shortcuts.md.

Validation

  • test/shell.d/shortcuts-test.sh uses an hl.unbind stub that matches by text and treats all as Hyprland does. It covers:
    • Omarchy and app shortcuts, taking keys from defaults spelled differently, and the reload when a shortcut releases a default's keys
    • live applies touching only the named shortcuts, binding order, and finishing a held hold
    • reserved and malformed keys, and bash and Lua agreeing on chords
    • every CLI path against a stand-in hyprctl: conflicts by keysym, keycode, release-only binding and submap; --force and what it can't take; --none; reset; Hyprland not running; an unreadable snapshot; an unwritable registry; and the reload fallback for older configs
  • dictation-test.sh checks the dictation shortcut names. Its stub previously crashed in Lua and still reported ok.
  • The dictation, hold-binding, binding-conflict, default-config, keybindings-menu and i18n tests pass, and so does ./test/cli. The tests pass at every commit.
  • Live check on Hyprland 0.56.2: an app shortcut bound as a press/release pair, a second shortcut on the same keys was refused with its owner named, all was refused, and reset unbound it. The other 285 bindings stayed.
  • Not yet tested by actually pressing the keys.

🤖 Generated with Claude Code

nchudleigh and others added 2 commits October 21, 2026 11:24
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@nchudleigh
nchudleigh force-pushed the feat/omarchy-shortcut branch from bb84026 to 8a17da6 Compare October 21, 2026 15:25
nchudleigh and others added 14 commits October 21, 2026 11:37
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant