Omahub
← All plugins
B

Keyboard minimap

by Balázs Orbán

Keyboard map that highlights keys as you type, for learning the US layout. Switchable per board.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

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

The deterministic scan found nothing, and manual review found no obfuscated code, no install-time execution, no network access, and no persistence of keystroke data. The plugin intentionally reads global keyboard events from /dev/input while the minimap is visible, which is a genuine privacy consideration, but it is clearly disclosed in the README and the data is only used in memory to light up keys.

  • keywatch.py captures raw key events from all readable keyboard devices while the map is on screen, so every keystroke (including passwords) passes through this plugin process; this is inherent to the plugin's purpose and is disclosed, but it is the most sensitive part of the code.
  • The service defaults to visible and is kept loaded, so in the US layout the key reader can start automatically at login rather than only after the user explicitly opens the map.
  • No network calls, destructive commands, hidden persistence, or exfiltration were found; the plugin only writes a small state file with visibility, layout choice, and plate position.
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/balazsorban44/omarchy-keyboard-minimap --enable
Productivity #Hyprland #quickshell

Keyboard minimap

An Omarchy shell plugin for learning the US layout on a keyboard printed for another one.

<p align="center"> <img src="docs/screenshot.png" alt="The minimap with the F key held" width="619"> </p>

Each key shows the legend printed on your keyboard with the US character beneath it, only where the two differ — so the only keys that stand out are the ones you have to relearn. Hold Shift and the whole map flips to the shifted layer, the one you can't guess.

Keys light up as you press them. It appears only in the US layout, drags anywhere on any monitor, and toggles from the keyboard icon in the bar.

Boards

Two are built in: a Norwegian ISO board and a US-printed ANSI one (a Keychron). Right-click the bar icon to pick between them, or leave it on Auto, which follows the keyboard the last keystroke came from — so moving your hands to the docked board switches the map with them. The Auto entry names the board it currently resolves to.

On a US-printed board no key needs a second glyph, so that map is about the shape: a straight Enter, a long left shift, no <> key, and \ back on the QWERTY row, which is where your fingers actually are.

Install

omarchy plugin add https://github.com/balazsorban44/omarchy-keyboard-minimap --enable

Needs python3, Hyprland (for hyprctl), and membership of the input group.

[!NOTE] The plugin reads key events straight from /dev/input, so while the map is on screen it sees every keystroke, including ones going to other windows. Nothing is logged or written anywhere, and the reader process is not running while the map is hidden or you are in another layout.

Remove it with:

omarchy plugin remove balazsorban44.keyboard-minimap

Adding your own board

In Layout.js, copy ANSI_US_ROWS (or NO_ISO_ROWS) and add one line to LAYOUTS:

define("id", "My board", /my-keyboard/i, 15, MY_ROWS)
//     id    menu label  deviceMatch     rowUnits

Each key is [keycode, us, usShift, phys, physShift, widthUnits]. Set phys to null where your keycap already prints the US character. Every row must sum to rowUnits. deviceMatch is what Auto tests your keyboard's name against — run omarchy-shell keyboard-minimap status while typing on it and use the typedOn name. Then ./run-tests, which checks the geometry of every board.

MIT. See LICENSE.