Let plugins declare keyboard shortcuts; have the shell bind them with confirmation and conflict handling

[falser101]

Summary

Plugins should be able to declare default keyboard shortcuts in manifest.json. The shell (and omarchy plugin enable) should own binding, confirmation, conflict detection, and rebinding. Plugins should not edit ~/.config/hypr/bindings.lua.

This is a plugin-contract request, not a request for another settings overlay.

Problem

Global hotkeys belong to Hyprland (o.bind → hl.bind). First-party panels already have hardcoded defaults:

o.bind("SUPER + CTRL + A", "Audio", "omarchy-shell shell toggle omarchy.audio")

Third-party plugins have no equivalent. Today they either:

• tell the user to add a bind by hand, or
• rewrite bindings.lua themselves (Todoist, Keysmith, and similar).

That leaks lifecycle into every plugin: disable/remove can leave dead binds, updates can clobber user remaps, Super+K only sees whatever happened to land in Hyprland, and conflict checking is duplicated poorly.

Two related gaps in the current contract:

1. No shortcuts field. schemaVersion: 1 has kinds, entry points, and barWidget.schema / settingsForm, but nothing for global hotkeys.
2. Plugins cannot contribute Setup/menu rows. The menu only merges ~/.config/omarchy/extensions/omarchy-menu.jsonc, which the plugin manager cannot write. Modifier Keys has to ship a separate install.sh for that.

omarchy plugin add already warns that plugins are unsandboxed and lands them disabled. omarchy plugin enable is a silent IPC call (enablePlugin). That is the right moment to confirm shortcuts, and it currently does not.

Proposal

Keep the existing split:

• The plugin declares intent (id, label, default combo, action).
• The shell owns authority (confirm, conflict-check, persist, bind, unbind).
• The user owns the actual combo.

Manifest

Unknown extra fields already survive validation, so this can stay on schemaVersion: 1 with a new optional object:

{
  "schemaVersion": 1,
  "id": "io.github.example.todoist",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "BarWidget.qml" },
  "shortcuts": [
    {
      "id": "toggle",
      "label": "Open Todoist",
      "default": "SUPER + CTRL + Y",
      "action": "toggle"
    }
  ]
}

action should be a closed set that maps to existing shell IPC, for example toggle, summon, hide, call:<method>. Do not let a plugin’s default shortcut run an arbitrary shell command.

omarchy plugin validate should check: unique ids, o.bind-compatible key syntax, and a legal action.

This is for global hotkeys only. In-panel keys (Escape, j/k, Enter) stay inside the plugin’s PanelKeyCatcher.

When to confirm

Confirm on enable, not add. Add already asks “do you trust this unsandboxed repo?” and leaves the plugin off so the user can read it. Binding a key is a second, separate grant.

Interactive omarchy plugin enable (and Setup → Plugins → Enable) would:

1. List the shortcuts the plugin wants (label + default combo).
2. For each: accept, change, or skip.
3. On conflict, stop and show the occupant, e.g. SUPER + CTRL + Y is already Clipboard manager.
4. Offer: pick another combo, steal it (hl.unbind first, then bind — same rule as editing bindings.lua today), or skip.
5. Persist the result, then enablePlugin.

--yes / non-interactive must not steal keys. Suggested policy: apply defaults only when free; skip conflicts and print them.

Persistence and binding

User choices belong in shell.json (or a shell-owned sidecar), never back in the plugin checkout:

{
  "plugins": [
    {
      "id": "io.github.example.todoist",
      "shortcuts": { "toggle": "SUPER + CTRL + T" }
    }
  ]
}

Plugin updates may change default. Confirmed or remapped combos stay put.

The shell should generate a file it owns, for example ~/.local/state/omarchy/plugin-binds.lua, and have Hyprland load it. Do not append to the user’s ~/.config/hypr/bindings.lua. That file is the user’s override surface; a generated table can be rewritten on enable/disable/remove.

Apply live as well so a compositor restart is not required. Super+K then sees plugin shortcuts because they are real Hyprland binds.

Disable/remove unbinds and drops the record. Clone routing should follow today’s IPC identity (resolveEnabledId): callers keep using the built-in id, the enabled clone receives the shortcut.

Conflict detection

Compare against:

• current Hyprland binds (hyprctl binds / omarchy menu keybindings --print)
• other plugins’ already-confirmed shortcuts (including ones not yet flushed to Lua)
• first-party defaults, labelled as “taken, can steal if you say so” rather than silently overwritten

Normalize before comparing: SUPER + CTRL + Y vs CTRL + SUPER + Y, code: vs keysym, and loop-generated binds such as workspace SUPER + 1..9. #7627 is relevant: --print currently does not use the same syntax as o.bind / hl.unbind.

Why this should not be a third-party plugin

A community “shortcut manager” can get about 80% of the way there: a service can watch pluginRegistry, read extra shortcuts fields, show an overlay, and write a marked block in bindings.lua (Keysmith already does the last part).

It cannot:

• hook omarchy plugin enable or Setup → Enable
• make Hyprland require a generated file (hyprland.lua only loads the stock user modules)
• contribute a Setup row without patching omarchy-menu.jsonc
• guarantee unbind on disable/remove unless that manager stays enabled
• make the convention work for plugins whose authors never heard of it

So this belongs in the plugin contract, next to barWidget.schema, not as another overlay people have to install first.

Related work

Closest existing proposals, none of which implement declarative shortcuts + confirm + conflict UI:

• #7724 / draft PR #8396 — plugins contribute raw Hyprland Lua, plus optional menu entries and toggles. The discussion even asks whether bindings should later be data rather than Lua. This proposal is that later slice, scoped to shortcuts.
• PR #7946 — menuItem in the manifest; the shell merges a launcher and does not mutate the user’s menu file. Same ownership model, different surface.
• PR #9557 / #7382 — plugins declare package deps; install asks before applying. Same confirmation shape.
• Draft PR #7252 — Input panel writes a generated Hyprland override and leaves input.lua alone. Same persistence shape as plugin-binds.lua.
• PR #6100 — user-defined Super+K entries via an extension file, not plugin registration.
• #7627 — --print vs o.bind syntax, needed for reliable conflict checks.
• #8729 — in-panel clipboard keys in Super+K. Out of scope here (not global binds).

Suggested first slice

1. Optional shortcuts on the manifest + validate.
2. Interactive enable: confirm / skip / rebind, with conflict prompt.
3. Persist on the plugin entry in shell.json.
4. Generated plugin-binds.lua (or equivalent) loaded by Hyprland; unbind on disable/remove.
5. --yes never steals; print skipped conflicts.

Menu contribution (menuItem / Setup rows) is useful and #7946 already covers it. Config widgets can keep using barWidget.schema. Neither should block shortcuts.

Happy to adjust the manifest shape if a hyprland kind from #8396 is the preferred place for binds instead of a top-level shortcuts array.