cadmus

cadmus

Cadmus, the mythological prince who brought the Phoenician alphabet to Greece — now reduced to a one-tap spell picker on your keyboard.

A tiny opinionated spell-check popup for Linux Wayland. Tap Right Alt anywhere, type a word (or pre-select one), pick the right spelling, and it lands on your clipboard. Paste it back where you came from.

• Single popup, dark UI, live filtering as you type
• Powered by fuzzel + hunspell + the system word list
• Right Alt tap = open popup. Right Alt hold = normal AltGr
• ~80 lines of Bash, no daemon, no GUI framework

Why

Built for KDE Plasma 6 on Wayland where modifier-only global hotkeys (like "tap Right Alt by itself") aren't first-class. The trick is to use keyd at the kernel/evdev layer for the hotkey, and a small Bash script for the popup. Works in any app, in any desktop environment that supports wl-copy.

Quick start

git clone <this-repo> ~/Projects/cadmus
cd ~/Projects/cadmus
./install.sh

That's it. Tap Right Alt to try it.

What install.sh does

1. Verifies runtime deps: fuzzel, hunspell, wl-clipboard, libnotify.
2. Installs the two scripts to /usr/local/bin/:
   • cadmus — the spell picker itself
   • cadmus-launch — env shim for launching from the root-owned keyd
3. Builds and installs keyd from source if it's not already on PATH (no keyd in Fedora's default repos).
4. Drops a config at /etc/keyd/cadmus.conf mapping Right Alt.
5. Enables and starts the keyd systemd service.

Manual install

If you'd rather skip the script:

sudo install -D -m 755 bin/cadmus        /usr/local/bin/cadmus
sudo install -D -m 755 bin/cadmus-launch /usr/local/bin/cadmus-launch

# build keyd from source if your distro doesn't ship it
git clone --depth 1 https://github.com/rvaiya/keyd.git /tmp/keyd
make -C /tmp/keyd -j"$(nproc)"
sudo make -C /tmp/keyd install

# install + load the keyd config (replace YOURUSER)
sed "s/__USER__/$USER/g" keyd/cadmus.conf | sudo tee /etc/keyd/cadmus.conf >/dev/null
sudo systemctl enable --now keyd
sudo keyd reload

Dependencies (Fedora)

sudo dnf install fuzzel hunspell hunspell-en-US wl-clipboard libnotify

keyd is built from source by install.sh (it's not in Fedora repos). On Arch, Debian 13+, Ubuntu 25.04+, Alpine, openSUSE, and Void it's a package.

How it works

Right Alt tap ──► keyd ──► /usr/local/bin/cadmus-launch ──► cadmus
                                                              │
                                            fuzzel  ◄─────────┤
                                            hunspell ◄────────┤
                                            wl-copy  ◄────────┘

• keyd watches /dev/input/* at the evdev level and decides "tap vs hold" for Right Alt. On tap, it runs a shell command (as root); the launcher immediately drops to your normal user with runuser and sets the Wayland/DBus env vars so GUI tools work.
• cadmus builds (and caches) a filtered word list from /usr/share/dict/words.
• fuzzel shows a dark popup with that list, prefilled from your primary selection if any. As you type, it fuzzy-filters live.
• The chosen word goes through hunspell to confirm + suggest, then ends up on the clipboard via wl-copy. A notify-send toast tells you what happened.

Configuration

Environment variables read by cadmus:

Var	Default	Purpose
CADMUS_DICT	en_US	Hunspell dictionary (e.g. en_GB, de_DE)
CADMUS_WORDS_FILE	/usr/share/dict/words	Source word list for the picker

Theme/colors live inline in bin/cadmus (the fuzzel --*-color flags). Edit and re-run install.sh (or just the sudo install step) to update.

Uninstall

sudo systemctl disable --now keyd
sudo rm -f /etc/keyd/cadmus.conf
sudo rm -f /usr/local/bin/cadmus /usr/local/bin/cadmus-launch
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/cadmus"

If keyd was only installed for cadmus, you can remove it too:

sudo make -C /tmp/keyd uninstall   # or via your distro's package manager

Troubleshooting

• Hotkey doesn't fire — check sudo systemctl status keyd and sudo keyd monitor (tap Right Alt; you should see events).
• "missing dependency" toast — install the deps from the table above.
• Wrong language suggestions — set CADMUS_DICT=en_GB (or whatever) in your shell rc and in /etc/keyd/cadmus.conf if launched via keyd.
• Popup opens on the wrong monitor — tweak --output / --anchor in bin/cadmus.

License

MIT. Do whatever Cadmus would have done.