Omahub
← All plugins
M

Keybindings

by meviusisback

Graphical frontend to view, modify, create, and manage Hyprland keybindings with conflict detection.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
ad8199d
Scanned
1 week 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
ad8199d
Reviewed
1 week ago

The plugin is a local keybinding manager that writes to the user's Hyprland config and reloads Hyprland, which is expected functionality. The code is straightforward, includes input sanitization for Lua strings, and has no network access or telemetry. The only minor concern is a raw-Lua passthrough for action strings starting with '{' or 'hl.' noted in a development plan, but this requires user interaction and is not an external attack vector.

  • Potential raw-Lua passthrough for action strings starting with '{' or 'hl.' in write_user_bindings, which could allow Lua injection if a user enters malicious input, but this is user-initiated and not remotely exploitable.
  • The plugin modifies ~/.config/hypr/bindings.lua and invokes hyprctl reload, which is expected but should be clearly communicated to users.
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/meviusisback/keybinds-plugin --enable
Desktop #Hyprland #quickshell #system

Omarchy Keybindings Plugin (meviusisback.keybinds)

Omarchy Linux Quickshell Python 3.10+ License: MIT

A modern, intuitive graphical frontend plugin for Omarchy Linux to view, search, modify, and create Hyprland keybindings with live interactive key recording, smart free key recommendations, collision detection, and safe Lua synchronization.

✨ Features

  • 🚀 On-Demand Launch: Summon the floating manager anytime via omarchy-shell shell summon meviusisback.keybinds (or bind it to a key) — no top status bar clutter.
  • 🔤 Alphabetical Sorting: All active keybindings and catalog presets are strictly sorted in case-insensitive alphabetical order by action name.
  • ⭐ Dedicated Modified & Custom Section: Easily review and manage all personal shortcut overrides and custom keybindings in one place with 1-click ↺ Reset to Default and 🗑️ Delete.
  • 💡 Smart Free Key Recommendations: When creating or editing an action, the modal automatically scans for 100% free, unassigned shortcuts matching the action's first letter (e.g. SUPER + S, SUPER + SHIFT + S for Spotify) and offers 1-click suggestion chips.
  • ⌨️ Multi-Method Key Recorder:
    • Live keyboard capture: click to record and press any combination.
    • Modifier toggle pills: toggle <kbd>SUPER</kbd>, <kbd>CTRL</kbd>, <kbd>ALT</kbd>, or <kbd>SHIFT</kbd> with ease.
    • Quick-key chips: instantly select common special keys (<kbd>RETURN</kbd>, <kbd>SPACE</kbd>, <kbd>ESCAPE</kbd>, <kbd>TAB</kbd>, <kbd>F1-F12</kbd>).
  • ⚠️ Collision Detection & 1-Click Rebind: Detects shortcut collisions in real-time, displays detailed conflict cards, and offers 1-click rebind options for colliding actions.
  • 📜 Actions Catalog: Browse pre-configured Hyprland / Omarchy window management, workspace, media, and system presets ready to bind.
  • 🖱️ Mouse Scroll Sync: Automatically respects your configured scroll sensitivity multiplier (scroll_factor) and direction (natural_scroll) from the Mouse Settings plugin (meviusisback.mouse-settings).
  • 🔍 Record-to-Find Shortcut Lookup: Click Record to Find next to the search bar and press any key chord on your keyboard to instantly locate its assigned action (or reveal that it's unassigned with a 1-click + Create Keybinding shortcut).
  • 🔄 Safe Lua Sync & Live Reload: Writes directly to ~/.config/hypr/bindings.lua (with automatic .bak backups) and invokes hyprctl reload for instantaneous application without session restarts.

🚀 Installation

Install directly from the marketplace with the Omarchy CLI (it clones and links the plugin into ~/.config/omarchy/plugins/):

omarchy plugin add https://github.com/meviusisback/keybinds-plugin --enable

On first launch, the plugin will offer to add a Keybindings Manager entry to your Omarchy launcher (Setup → Keybindings → Keybindings Manager). You can accept or dismiss this — it only asks once per session. You can also toggle this anytime from the 📋 Add to Launcher / ✓ In Launcher button in the app's header bar.

📖 Usage

From the Graphical Desktop

  1. Summon the plugin via omarchy-shell shell summon meviusisback.keybinds (or your configured launcher/keybinding).
  2. Search by shortcut (e.g. SUPER + W), action name (e.g. Terminal), category, or command.

From the Terminal

The plugin's bin/ directory is not on PATH by default — Omarchy only puts /usr/share/omarchy/bin there. Either call the wrapper by its installed path:

~/.config/omarchy/plugins/meviusisback.keybinds/bin/omarchy-keybinds

or link it once into your personal bin (the wrapper resolves symlinks correctly):

mkdir -p ~/.local/bin
ln -s ~/.config/omarchy/plugins/meviusisback.keybinds/bin/omarchy-keybinds ~/.local/bin/omarchy-keybinds
omarchy-keybinds   # launch the GUI directly

Or summon via the shell IPC:

omarchy-shell shell summon meviusisback.keybinds '{}'

Note: as a panel plugin, nothing appears until it is summoned, and the raw IPC exits 0 even when the shell refuses it (it answers ok / unknown — e.g. while the plugin is disabled). The wrapper turns a refusal into a visible error with the matching omarchy plugin enable hint.

🛠️ CLI Command Reference

The plugin includes a full-featured CLI backend engine:

# One-time setup if you want the short command name (see "From the Terminal"):
#   ln -s ~/.config/omarchy/plugins/meviusisback.keybinds/bin/omarchy-keybinds ~/.local/bin/omarchy-keybinds

# List all active keybindings, presets, conflicts, and mouse settings in JSON
omarchy-keybinds list

# Create or modify a shortcut
omarchy-keybinds set "<KEY>" "<DESCRIPTION>" "<COMMAND>" "[ACTION_LUA]" "[OLD_KEY]"
# Example:
omarchy-keybinds set "SUPER + SHIFT + B" "My Browser" "omarchy-launch-browser"

# Reset a modified shortcut back to Omarchy default
omarchy-keybinds reset "SUPER + SHIFT + B"

# Disable / unbind a shortcut
omarchy-keybinds disable "SUPER + W"

# Re-enable a previously disabled default shortcut
omarchy-keybinds enable "SUPER + W"

# Reload Hyprland configuration
omarchy-keybinds reload

⚙️ Configuration & Lua Sync

The plugin manages personal overrides in ~/.config/hypr/bindings.lua:

  • Custom / Rebound Keybindings: Generated with standard o.bind(...) directives.
  • Disabled Keybindings: Generated with hl.unbind(...) directives.
  • Safety Backups: A backup (bindings.lua.bak) is created automatically before any write operation.
  • Comment Preservation: Personal comments and manual custom blocks in bindings.lua are preserved.

🧪 Testing

Automated unit tests cover key normalization, Lua parser safety, comment handling, unbind detection, and conflict evaluation:

python3 -m unittest discover -s tests -p "test_*.py"

🗑️ Removal

# Remove the plugin from Omarchy (keeps your personal ~/.config/hypr/bindings.lua untouched)
omarchy-shell shell hide meviusisback.keybinds >/dev/null 2>&1 || true
omarchy-shell shell removePlugin meviusisback.keybinds >/dev/null 2>&1 || true
rm -f ~/.config/omarchy/plugins/meviusisback.keybinds

🔒 Security & Privacy

  • Local-only: The plugin runs entirely on your machine. It has no network access, no telemetry, and reads only your Hyprland keybinding configuration (~/.config/hypr/bindings.lua and the Omarchy default bindings).
  • No keylogging: The interactive recorder captures keystrokes only in-memory to display the pressed chord; nothing is persisted to disk or transmitted.
  • Safe Lua writes: All key chords, descriptions, and commands are validated and escaped before being written to bindings.lua. Invalid chords (containing characters that could break out of a Lua literal) are rejected, and string values are escaped so a crafted binding description cannot inject arbitrary Lua.
  • Automatic backups: Every write first copies the existing bindings.lua to bindings.lua.bak and applies the change atomically via an atomic rename.

🏗️ Architecture

keybinds-plugin/
├── manifest.json                 # Omarchy plugin manifest (declares kind: ["panel"], keepLoaded: true)
├── KeybindsPanel.qml             # Main GUI window with search, category tabs, and active key list
├── EditKeybindDialog.qml         # Modal dialog for creating/editing shortcuts with smart free recommendations
├── KeyRecorder.qml               # Interactive keyboard event catcher, modifier pills, and live conflict check
├── KeyBadge.qml                  # Visual keyboard chord badge renderer
├── bin/
│   └── omarchy-keybinds          # CLI wrapper script
├── backend/
│   └── keybinds_manager.py       # Python engine for parsing defaults, user Lua config, conflicts, and mouse sync
├── tests/
│   └── test_backend.py           # Unit tests for parser and backend operations
└── README.md                     # Documentation

📄 License

Distributed under the MIT License. See LICENSE for details.