Key Promoter teaches you Omarchy shortcuts when you use the menu
Forrest Knight’s Key Promoter plugin watches for actions you launch from the Omarchy menu and shows the keyboard shortcut you could have used instead, based on your own Hyprland bindings.
Omarchy is built around the keyboard, but the menu is always there for the moments you forget a shortcut. Forrest Knight’s new plugin, Omarchy Key Promoter, turns those moments into a lesson. Its README describes it as JetBrains’ Key Promoter X, “but for your desktop.”
When you use the Omarchy menu to do something that already has a keybinding, a small toast shows you the shortcut. It reads your own bindings rather than Omarchy’s defaults, so every override in ~/.config/hypr/bindings.lua is reflected. The toast uses the shell’s theme tokens, so it matches the active theme and follows omarchy theme set instantly.
The plugin never sees key presses. It listens to Hyprland events for a few seconds after the menu closes and matches what happens next: a window or web app opening, a shell layer such as the emoji or clipboard picker, or an omarchy-* script like screenshot or lock. Dismissing the menu, or using the keybinding directly, shows nothing. When several bindings do the same thing, the one with the fewest modifiers wins, and media keys are never promoted.
Toast duration, screen position, the matching window and a promotion counter can be set in ~/.config/omarchy/shell.json. The README lists what is not covered yet: workspace switches, clicks on bar widgets, and menu actions that finish without opening a window or leaving a process, such as the nightlight toggle.
It needs nothing beyond a stock Omarchy install: no sudo, no network and no daemons. Install it with omarchy plugin add https://github.com/ForrestKnight/omarchy-key-promoter.git --enable --yes.
The plugin is at version 0.1.0 and MIT-licensed.
