OmaKeyboard on Omarchy

OmaKeyboard on Omarchy

OmaKeyboard is a visual keyboard remapper and shortcut manager for Omarchy — Caps Lock as Control, arrows under your right hand on a held layer, app-launching shortcuts — per keyboard, with no daemon running and no keymap files to hand-edit.

TL;DR

omarchy pkg add omakeyboard

Takes ~1 minute (v0.1.0-1 on the app-store page, MIT). Two caveats: it needs Omarchy 4 or newer (the version that configures Hyprland in Lua — earlier Omarchy won't work), and the maintainer's README notes new packages land on the edge channel first, reaching stable with the next Omarchy release — if the package is missing on your machine, either wait for the release train or sudo pacman -U the release tarball from GitHub.

Getting started (5 minutes)

1. Install and launch.

Run the command above (or the release package on stable, per the README). Launch from Super + Space — the binary is omakeyboard.

2. First launch — start from a recipe.

Don't start from a blank page — the app offers recipes, ready-made setups you can start from and tweak. You'll see four pages: Mappings (as a list), the keyboard view (mappings drawn on the actual keys), Shortcuts, and Settings. Switch pages with Ctrl+1 … Ctrl+4.

3. The 3 things you need to know:

• Your mappings are drawn on the keys — Click a key to change it, hold a layer key to see what that layer does while held, and use Ctrl+L to step through layers in the keyboard view (Ctrl+K toggles list/keyboard views). Ctrl+N adds a mapping; the key tester (Ctrl+T) shows you what your keys actually type, right now, as you press them.
• Nothing reaches your keyboard until you apply — and apply is safe — Ctrl+Return applies, and the app shows you what the apply did stage by stage. It takes a snapshot before every change, so an apply that goes wrong puts everything back. This is the feature that makes experimenting with remaps fun instead of terrifying: there's no "I bricked my keyboard layout" state.
• Shortcuts get collision detection — The Shortcuts page handles app launches, window actions, and setting toggles — and it reads what your system already uses, so it can warn you when two shortcuts would collide. Undo a deletion with Ctrl+Z; F5 re-reads everything from disk.

4. What it cannot do (know this before you plan your dream layout).

These are limits of XKB and Hyprland, not of the app — and the README says so in an Advanced section too:

• Tap for one thing, hold for another — XKB has no notion of time.
• Two keys pressed at once producing a third.
• A key that types a sequence.
• Different remaps per application.

"Nothing is installed to work around these, and nothing is suggested." That's honesty you can build on: what the app shows you is what XKB can actually do.

5. Config locations.

~/.config/omakeyboard/ holds your rules. ~/.local/state/omakeyboard/ holds the generated keymaps and the backups. And one marked block in ~/.config/hypr/hyprland.lua — that's the whole footprint in your Hyprland config; nothing else is touched, and "Restore defaults" takes all of it back out. Settings also exports your setup as one file you can hand to someone else.

Practical notes: This is an Omarchy-shaped tool through and through: it applies changes with hyprctl, reads the bindings already in your Lua configuration, themes itself in every Omarchy theme (the README shows it in all of them), and follows the desktop dark mode and text scale via xdg-desktop-portal. Ctrl+Tab moves between keyboards — mappings are per-keyboard, so your laptop board and your external board can have different layouts.

Common issues & fixes

omarchy pkg add omakeyboard finds nothing

New packages land on Omarchy's edge channel first and reach stable with the next Omarchy release (stated in the README's own Install section).

Fix: If you're on stable, either wait, or install the release package directly: sudo pacman -U the omakeyboard-0.1.0-1-x86_64.pkg.tar.zst asset from the GitHub releases page — or clone and ./bin/install. (x86_64 asset; aarch64 users should check the release page for their asset.)

The app launches but mappings don't apply, or it complains about your setup

OmaKeyboard requires Omarchy 4 or newer — that's the version that configures Hyprland in Lua, and the app reads and writes that Lua configuration. On older Omarchy (hyprland.conf era) the whole mechanism the app drives doesn't exist.

Fix: Upgrade Omarchy first; there's no compatibility mode.

You remapped Caps Lock as Control (or a layer) and now you can't type your password / something broke mid-apply

This is what the snapshot system is for: every apply snapshots first, and a bad apply rolls back.

Fix: If you're locked out of the GUI, the rollback state lives in ~/.local/state/omakeyboard/ (backups) and your hand-written config is untouched except the one marked block in ~/.config/hypr/hyprland.lua — "Restore defaults" removes that block entirely. (UNVERIFIED on-machine: confirm the exact recovery steps before publishing.)

You want tap-Caps-for-Escape / hold-Caps-for-Control, or a key that types a whole snippet, or different remaps in your editor vs your browser

Not supported — and it never will be through this app. XKB has no notion of time (no tap-vs-hold), no two-keys-to-one-action, no sequences, no per-application maps. These are the README's own "What it cannot do" bullets.

Fix: The usual workarounds live outside XKB (keyd, xremap, QMK firmware) — see the comparison table.

The Shortcuts page flags your new shortcut as colliding with an existing binding

That's the feature working: the app reads your system's current bindings and tells you when two would collide, rather than silently overriding one.

Fix: Change the shortcut, or find and remove the conflicting binding in your Hyprland config first.

Pairs well with / If you hate this, try

Pairs well with

• Your Omarchy theme — it's built to match all of them. A second physical keyboard: mappings are per-keyboard, so your laptop board and your external board can have different layouts. The key tester (Ctrl+T) for diagnosing "is this key even sending what I think" before you file anything.

If you hate this, try

• Editing ~/.config/hypr/input.lua by hand (the Omarchy manual's Keyboard/Mouse/Trackpad page documents kb_options like compose:caps and repeat settings) — zero new software, full XKB option power, but no GUI and no safety net. Or keyd/xremap if you need what OmaKeyboard can't do (tap-vs-hold, sequences, per-app maps).

Comparison: omakeyboard vs keyd vs xremap

Verdict: Use OmaKeyboard if you want a safe, visual way to remap within XKB's limits; use keyd or xremap if you need tap-vs-hold, sequences, or per-app maps; hand-edit input.lua if you only need XKB options like the compose key.