Omahub
← All plugins
R

NextKey

by Russell Morton

A contextual shortcut guide for Omarchy that reveals available actions as you hold Super and add modifiers.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
e02860f
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
e02860f
Reviewed
1 month ago

NextKey is a passive shortcut overlay that only observes keyboard events and displays binding information. The install/uninstall hooks are careful, idempotent, and validate all changes with backups. No destructive, obfuscated, or credential-harvesting behavior was found.

  • The install hook modifies the user's Hyprland bindings.lua and triggers a Hyprland reload, which is expected but could briefly disrupt the session.
  • The observer uses hl.exec_cmd to invoke omarchy-shell, but only with fixed, quoted arguments, so no command injection risk.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/russellmorton/next-key --enable
Productivity #Hyprland #quickshell

NextKey

NextKey is a passive, system-wide “which-key” overlay for Omarchy Quattro. Press Super to see the user's real Omarchy shortcuts immediately; add or remove Shift, Ctrl, or Alt to filter them live.

The plugin never binds, intercepts, or executes a shortcut. Hyprland remains the sole input and execution path. The observer only subscribes to Hyprland's raw keyboard event, reads logical modifier state, and sends meaningful display changes to the already-running Omarchy shell. There is no input polling, background daemon, /dev/input access, or replacement submap.

Requirements

  • Omarchy 4 / Quattro with its Quickshell plugin system
  • Hyprland 0.55 or newer with input.keyboard.key, config.reloaded, timers, hl.is_key_down, and active-monitor Lua APIs
  • omarchy-menu-keybindings, omarchy-shell, luac, and Quickshell

The install hook checks the exact runtime APIs before changing configuration. The observer defers each raw key event by one event-loop tick because current Hyprland emits input.keyboard.key immediately before updating the state read by hl.is_key_down. A disabled, self-stopping timer defers processing by the required one event-loop tick (1 ms); there is no intentional reveal delay and the timer remains disabled at idle. Omarchy 3.x is intentionally unsupported.

Install

omarchy plugin add https://github.com/russellmorton/next-key.git --enable
~/.config/omarchy/plugins/next-key/bin/install-hook

The second command adds one marked loader block to ~/.config/hypr/bindings.lua, after making a timestamped backup. It is safe to run again. The loader checks that the plugin file exists and evaluates it with pcall, so deleting or breaking the plugin cannot abort Hyprland startup.

The overlay loads bindings from:

omarchy-menu-keybindings --print

That command remains responsible for custom bindings, unbind, Lua and code: bindings, layout resolution, duplicate cleanup, and Hyprland output workarounds. The plugin only parses its normalized COMBO → Description display records. A Hyprland config reload automatically refreshes the model.

Uninstall

Run the uninstall hook before removing the plugin directory:

~/.config/omarchy/plugins/next-key/bin/uninstall-hook
omarchy plugin remove next-key

The hook removes only the marked block and is idempotent. If the directory was already removed, the guarded loader is harmless; restore the plugin temporarily or remove only the block between the two next-key markers.

Behavior

  • Press Super: the overlay appears immediately on Hyprland's active monitor.
  • Continue into a normal Super shortcut: the overlay hides as soon as its action key is pressed.
  • Add/remove Shift, Ctrl, or Alt: contents update immediately.
  • Press a non-modifier action key: the overlay hides and stays suppressed until all Super keys are released; the existing Hyprland shortcut executes normally.
  • Reload Hyprland: the overlay closes and reloads normalized bindings.

The default SUPER view promotes normalized SUPER SHIFT application bindings, such as SHIFT+A for ChatGPT, ahead of direct SUPER actions. When Shift is held, the same apps remain first with natural labels such as A. The five-row preview expands when its + N more control is clicked; the same control becomes − show less while expanded.

The visual surface uses Omarchy's popup colors, border, typography, spacing, and corner tokens. It has no keyboard focus; only the expansion control accepts pointer input, while the rest of the overlay remains click-through.

Development and checks

node tests/shortcut-model.js
lua tests/state-machine.lua
lua tests/observer.lua
tests/hooks.sh
luac -p hypr/shortcut-hints.lua hypr/ShortcutHintsState.lua
qmllint -I /usr/share/omarchy/shell ShortcutHints.qml components/*.qml
omarchy plugin validate .

See SPEC.md for the complete v1 behavior and safety contract.