Omahub
← All plugins
C

Keybinding Guide

by ctl0v0

Browse active shortcuts in a right-side guide that filters as modifiers are held.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
c40c36f
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

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

The plugin is a transparent keybinding guide that reads and displays active shortcuts, with a learning mode that temporarily pauses conflicting bindings while the pointer is over the guide. All functionality is clearly documented, requires explicit user consent to modify Hyprland configuration, and contains no obfuscated code, credential theft, or destructive operations.

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/ctl0v0/omarchy-keybinding-guide --enable
Productivity #Hyprland #bar #quickshell

Keybinding Guide

Keybinding Guide for Omarchy Quattro

Keybinding Guide is an Omarchy Shell plugin that makes shortcuts easier to discover while you work. Hold Super, Ctrl, Shift, or Alt briefly and a compact guide appears at the right edge with only the bindings for that exact modifier combination.

Add or release a modifier and the list updates immediately. Move the pointer over the guide and use the Up and Down arrow keys to scroll one row at a time. While the pointer is over the guide, only conflicting arrow and pointer bindings are paused; every other shortcut remains available. The paused bindings resume immediately when the pointer leaves. The guide never requests keyboard focus or resizes the workspace, and releasing every modifier dismisses it. Omarchy's searchable keybinding menu remains unchanged: Super + K and Learn > Keybindings continue to use the built-in interface.

The plugin reads the bindings Omarchy exposes from the active Hyprland configuration, including custom bindings. On Omarchy builds with the structured keybinding API, clickable rows invoke their registered dispatcher directly rather than synthesizing a keypress, and active submaps are respected. Stock Quattro remains fully usable as a read-only guide through its existing printable keybinding inventory.

Demo

Modifier filtering and arrow-key scrolling on the Omarchy desktop

The small keystroke display in the recording is a capture aid only. It is not included with, installed by, or required by Keybinding Guide.

Requirements

  • Omarchy Quattro.
  • jq, lua, flock, and xkbcli, provided by a standard Omarchy installation.

The plugin does not patch Omarchy during installation. Structured inventory and direct row actions are detected automatically when the running Omarchy version provides them; otherwise rows are reference-only while modifier filtering and hover-scoped arrow-key scrolling continue to work. Pointer input is accepted only over the visible guide. Existing Super mouse bindings remain active elsewhere and are paused while the pointer is over the guide.

Install

OMARCHY_SHELL_IPC_TIMEOUT=15s omarchy plugin add https://github.com/ctl0v0/omarchy-keybinding-guide.git --enable

The longer one-command timeout gives Omarchy's shell time to load the plugin's QML during its first enable; it does not change persistent shell settings. Enabling the plugin adds its keyboard icon to the bar with Learning Mode on by default. It does not change Super + K or Omarchy's Learn menu.

Learning Mode needs a passive Hyprland key-state bridge. Replace the existing require("default.hypr.omarchy") line in ~/.config/hypr/hyprland.lua with this guarded loader:

local guide_root = (os.getenv("HOME") or "") .. "/.config/omarchy/plugins/io.github.ctl0v0.keybinding-guide/hypr"
local function load_guide_file(name)
  local path = guide_root .. "/" .. name
  local file = io.open(path, "r")
  if file then
    file:close()
    dofile(path)
  end
end

load_guide_file("keybinding-guide-preload.lua")
require("default.hypr.omarchy")
load_guide_file("keybinding-guide.lua")

Reload Hyprland to start the modifier-key bridge:

hyprctl reload

The bar icon toggles Learning Mode. A crossed-out keyboard means it is disabled; click the icon again to resume the guide when modifier keys are held.

Remove

Disable Learning Mode before removing the repository:

~/.config/omarchy/plugins/io.github.ctl0v0.keybinding-guide/bin/keybinding-guide-toggle off

Replace the guarded Hyprland loader block above with require("default.hypr.omarchy") (or leave it in place, where it safely becomes a no-op), run hyprctl reload, then uninstall the plugin:

omarchy plugin remove io.github.ctl0v0.keybinding-guide
rm -f ~/.local/state/omarchy/toggles/keybinding-guide{,-disabled,.lock}

The plugin stores an explicit disabled preference at ~/.local/state/omarchy/toggles/keybinding-guide-disabled. Removing it after uninstall restores the default-on state for a future installation.

Development

Validate the package and run its tests from the repository root:

omarchy plugin validate .
./test/all

License

MIT