Superkey

Learn Omarchy shortcuts by doing. Superkey is a free plugin for the Omarchy 4 desktop. Kappy, a small robot in the corner of your screen, asks you to press real shortcuts on your real desktop and confirms each one actually worked — no videos, no quizzes, no pretending.

Ten lessons, 70 steps, across three tracks:

• Hyprland — Essentials · Windows I–III · Workspaces · Scratchpad · Panels & tools
• Tmux — Sessions & windows · Panes
• Neovim (LazyVim) — Editor basics

Every lesson links back to the matching module of the free Stevinator Omarchy course.

Install

Requires Omarchy 4.0.4 or newer. Nothing else — Quickshell, Hyprland, tmux and Neovim are already part of Omarchy.

omarchy plugin add https://github.com/smanookian/superkey.git
omarchy plugin enable stevinator.superkey

Omarchy installs every third-party plugin disabled so you can read the code first; the second line turns it on. An SK button appears in the bar. Click it and Kappy says hello.

Update and remove the same way you'd expect:

omarchy plugin update stevinator.superkey
omarchy plugin remove stevinator.superkey

Use

• Click SK in the bar (or run omarchy-shell shell toggle stevinator.superkey '{}'). Settings can copy a keybinding line for you — Super + Ctrl + Shift + K is free on stock Omarchy — to paste into ~/.config/hypr/bindings.lua.
• Pick a lesson. Kappy shows the keys; you press them on the real desktop. When Hyprland, tmux or Neovim report the effect, the step is verified and the next one loads.
• Hint rephrases. Show me performs the action, puts things back, and says "Now you." Skip moves on. A few steps can't be observed; Kappy says so and asks you to press Continue.
• Close hides Kappy. Quit (in Settings) disables the plugin entirely; omarchy plugin enable stevinator.superkey brings it back.

Progress is saved in ~/.local/state/superkey/progress.json. Settings has Sound, Motion, Reset progress.

What Superkey never does

• Edit your Hyprland, tmux, Neovim or Omarchy configuration.
• Close, move, float or fullscreen a window it didn't open. Its own windows are titled Superkey practice.
• Use your tmux sessions or your files. Tmux lessons run on a private server (tmux -L superkey); Neovim lessons open a throwaway sample project.
• Install anything, or go online.
• Keep running in the background. Between lessons it is a bar button.

Window lessons run on an empty workspace and return you to where you were.

How verification works

Superkey observes effects, never keystrokes. Hyprland's event stream and hyprctl snapshots for windows, workspaces and panels; a tmux control-mode client for sessions, windows and panes; nvim --remote-expr for pickers, the explorer and Lazygit. If something isn't observable, the step is marked "confirmed by you", not "verified". Details, per binding, in DESIGN.md.

Develop

git clone https://github.com/smanookian/superkey.git
ln -sfn "$PWD/superkey" ~/.config/omarchy/plugins/stevinator.superkey
omarchy-shell shell rescanPlugins && omarchy plugin enable stevinator.superkey

Superkey is keepLoaded, so after editing QML run omarchy-restart-shell. Drive it without clicking:

omarchy-shell shell summon stevinator.superkey '{"lesson":"hyprland.workspaces"}'
omarchy-shell shell call stevinator.superkey state ''
omarchy-shell shell call stevinator.superkey hint|showme|skip|confirm|stop ''

Lessons are JSON in lessons/; verifier types are listed in DESIGN.md. Platform findings from building this (Lua-form dispatch, scrolling-layout workspaces, panels without openlayer, tmux commands that emit no notification, …) are in NOTES.md.

Credits

Kappy was generated by the author with Gemini from the brief in MASCOT.md and normalized by hand; sounds are synthesized. No third-party assets. MIT license.