# 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`](https://github.com/rvaiya/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

```bash
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`](https://github.com/rvaiya/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:

```bash
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)

```bash
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

```bash
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:

```bash
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.