Omahub
← All plugins
F

Omacoach

by Filip

Helps you discover Omarchy with the keyboard, and coaches you to become even better at it

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
962262e
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
962262e
Reviewed
1 month ago

No malicious or deceptive behavior was found; the source matches the documented coaching/measurement purpose, and the config-editing hooks are transparent, back up the modified file, and roll back on failure. The main residual risks are that the plugin intentionally edits ~/.config/hypr/bindings.lua, watches modifier+key attempts to build local aggregate stats, and can send those aggregates to the user-configured agent when explicitly asked. The deterministic scan's 'none' rating is consistent with this review, though the legitimate key-attempt measurement and config mutation are worth noting.

  • bin/install-hook and bin/uninstall-hook modify ~/.config/hypr/bindings.lua and reload Hyprland; this is disclosed and protected by backups plus luac validation and rollback, but it is still a user-visiable config mutation.
  • The Hyprland observer (hypr/observer.lua) monitors global modifier+key events; only aggregate counts of recognized bindigs are persisted locally, but users should understand it is key-event monitoring.
  • The 'Add keybind' feature writes a commented draft into ~/.config/hypr/bindings.lua before opening the config editor; it is user-triggered and deduplicated, but it does edit a core config file.
  • The 'Talk about coach insights with agent' action sends aggregate measurements, including app names and menu labels, to whatever omarchy agent the user has configured; this requires an explicit user click but could disclose data if the agent is remote.
  • The optional experments/menu-search-event.patch is not part of the plugin runtime and requires explicit manual application, so it is not a runtime install 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/FilipHarald/omacoach --enable
Productivity #Hyprland #quickshell #launcher

Omacoach

⚠️ Omarchy search must be modified for search-selection coaching to work. Shortcut discovery and attempted-shortcut measurement work with stock Omarchy, but the Coach cannot observe menu selections unless the active Omarchy menu has the capability proposed in basecamp/omarchy#7372. experiments/menu-search-event.patch remains an app-only fallback. Omacoach detects the proposed capability automatically. Follow issue #17 for status.

Omacoach helps you discover Omarchy with the keyboard and coaches you to become better at using shortcuts. It is an experimental Omarchy Quattro plugin.

View Omacoach on Omarchy Plugins

Screenshots

Hold a configured modifier to open the passive, click-through shortcut overlay:

Passive shortcut overlay

Press SUPER+CTRL+K to open the permanent, interactive panel:

Permanent coaching panel

See GUIDE_PRINTSCREENS.md to reproduce or update these images.

Shortcut overlay

  • Reads effective, described bindings from omarchy-menu-keybindings --print.
  • Shows described keyboard bindings containing at least one supported modifier.
  • Opens after a 180 ms hold, avoiding flashes for shortcuts already in muscle memory.
  • Supports SUPER, SHIFT, CTRL, and ALT as independent passive triggers; all four are enabled by default and can be disabled separately.
  • Filters immediately when modifiers are added or removed.
  • Runs as a click-through, keyboard-focus-free layer-shell surface.
  • Starts around 50% screen height and grows downward, shifting upward only when required to fit the output.
  • Collapses numeric workspace and bar-panel families into presentation-only [nbr] rows while retaining independent underlying bindings and counts.
  • Supports source-order, alphabetical, or measurement-count sorting with row-first or column-first grid flow.

Mouse, wheel, XF86, code:, submap, and native multi-key chord bindings are not promised by this prototype. Hyprland does not expose a post-dispatch event, so Omacoach records attempted shortcuts rather than confirmed invocations.

Permanent panel

Press SUPER+CTRL+K to toggle the permanent panel. It starts 20% from the top of the active output and grows downward so the close control and modifier row stay in fixed positions.

The permanent panel:

  • Closes with Escape, SUPER+CTRL+K, or its top-right close button.
  • Uses the same live modifier filtering as the passive overlay.
  • Shows Coach, Data, and Settings controls below the shortcut inventory.
  • Opens the configured Omarchy agent with the current aggregate measurements and a prepared Coach discussion prompt.
  • Lets you pause collection, delete local data, configure passive triggers, change sorting, and reset coaching decisions.
  • Requests keyboard focus only while open; the passive overlay never does.

Local measurement

Measurement is local and enabled when the plugin is enabled. Omacoach resolves terminal key presses through the configured XKB keymap and stores aggregate counts when a chord matches the parsed binding inventory. It stores no raw keys, unmatched chords, timestamps, focused applications, or event history.

State is stored at:

${XDG_STATE_HOME:-~/.local/state}/omacoach/attempts.json

Inspect or control measurement through the permanent panel or IPC:

omarchy-shell omacoach measurement off
omarchy-shell omacoach measurement on
omarchy-shell omacoach attempts
omarchy-shell omacoach resetAttempts

Search-selection coaching

With the modified menu integration, Omacoach records a stable item ID, item kind, label, and canonical menu path only when the user explicitly selects a static action, app, menu, or link after a non-empty search. App events additionally include the desktop-entry ID. It does not receive or retain the search query, command, result rank, timestamp, or dmenu value. Dynamic provider rows and dmenu selections are excluded. Inspect the aggregates with:

omarchy-shell omacoach menuSelections
omarchy-shell omacoach searchedApps

searchedApps is the app-only compatibility view. For app selections, the matcher cross-checks desktop-entry identity, launcher-capable o.bind definitions, and the effective binding list. It reports URL, command, Omarchy launcher, and default-application evidence rather than trusting labels alone:

./scripts/match-searched-app-bindings
./scripts/match-searched-app-bindings --json

App Coach rows expose three actions:

  • Ignore hides an app until Reset coach decisions is used.
  • Add keybind prepends a commented, deduplicated app-specific draft to ~/.config/hypr/bindings.lua, then opens the normal Omarchy config editor.
  • Show keybinding opens the Omarchy keybinding selector narrowed to effective launcher bindings matched for that app.

Static action rows expose Show keybinding when their effective menu command matches an effective o.bind definition, such as Learn › Keybindings and its locally remapped SUPER+U binding. Static action, menu, and link rows expose Ignore, but Omacoach does not suggest or generate new keybindings for those item kinds.

Use Talk about coach insights with agent to open the configured Omarchy agent with the prepared prompt in prompts/coach-insights.md. The prompt receives all current aggregate binding-attempt, searched-app, and searched-menu measurements. It does not include search queries, commands, timestamps, result ranks, unmatched or raw keys, focused applications, event history, UI preferences, or ignored-item decisions. Configure a default agent with omarchy default agent <name> before using the button.

The native event and capability contract is tracked in issue #17 and proposed in basecamp/omarchy#7372. Omacoach accepts the proposed semantic event and detects its declared capability. Unsupported menus disable only search-selection coaching; shortcut hints and attempted-shortcut measurement are independent and continue working.

Requirements

  • Omarchy Quattro with omarchy-shell, omarchy-menu-keybindings, omarchy-menu-select, and omarchy-launch-config-editor.
  • Hyprland with the Lua APIs validated by bin/install-hook.
  • hyprctl, luac, jq, xkbcli, and Node.js available on PATH.
  • qmllint for development checks only.

Search-selection coaching additionally needs the menu hook described at the top of this README. Shortcut discovery and attempted-shortcut measurement work without it.

Install

Install and enable the public plugin, then install its Hyprland observer and SUPER+CTRL+K panel binding:

omarchy plugin add https://github.com/FilipHarald/omacoach.git --enable
~/.config/omarchy/plugins/io.github.filipharald.omacoach/bin/install-hook

The hook validates the plugin and Hyprland Lua APIs, makes a timestamped backup of ~/.config/hypr/bindings.lua, adds marked observer and panel-binding blocks, reloads Hyprland, and restores the backup if validation fails.

Remove

Run the uninstall hook before removing the plugin checkout:

~/.config/omarchy/plugins/io.github.filipharald.omacoach/bin/uninstall-hook
omarchy plugin remove io.github.filipharald.omacoach

Uninstalling disables the plugin when possible, transactionally removes the observer and panel binding, and permanently deletes ${XDG_STATE_HOME:-~/.local/state}/omacoach. Configuration is restored from the timestamped backup if Hyprland rejects the change.

Development install

ln -s "$PWD" ~/.config/omarchy/plugins/io.github.filipharald.omacoach
omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.filipharald.omacoach
./bin/install-hook

Use ./bin/uninstall-hook before removing the development symlink.

Development

Run all model, observer, lifecycle, plugin, Lua, and QML checks with:

./scripts/check

Preview or hide the passive UI without holding a modifier:

monitor=$(hyprctl activeworkspace -j | jq -r '.monitor // ""')
omarchy-shell omacoach preview SUPER "$monitor"
omarchy-shell omacoach hide "$(date +%s%3N)"

Attribution

The passive Hyprland observer and contextual overlay architecture were informed by NextKey, Copyright (c) 2026 Russell Morton, available under the MIT License. See THIRD_PARTY_NOTICES.md.