Razzi guide to keyd

When I switched my laptop to dual boot Ubuntu (and later Debian) one thing I hugely missed from MacOS was a key remapping utility.

Perhaps even more so because the default keyboard shorcuts on a Windows-oriented keyboard were foreign to me after using Mac for so long.

On MacOS there is the great Karabiner-Elements which I used constantly, except for a short stint where I upgraded to the latest MacOS which was not supported by the original Karabiner, wherein I furiously tried to port my config over to Hammerspoon¹.

Anyways, when I switched to Ubuntu I tried a couple options such as xmodmap and sxhkd, but either they didn’t work or were glitchy. I then found Interception Tools which worked (!) but was kinda cumbersome; its design is actually pretty elegant and it goes into great lengths to describe its functionality but it’s still pretty low level and requires you to write c code and compile your own executables. If I hadn’t discovered keyd I’d probably still be using Interception Tools today.²

enter keyd

keyd doesn’t have much fanfare and be pretty much a self-contained repository, which might be why I didn’t find it for a while.

Installation is pretty standard for a standalone C executable:

$ git clone https://github.com/rvaiya/keyd
$ cd keyd
$ make && sudo make install
$ sudo systemctl enable keyd && sudo systemctl start keyd

And then we get to their first configuration example for /etc/keyd/default.conf:

[ids]

*

[main]

# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)

Now we’re talking!! We already have caps lock mapped to control (good) and caps lock sending escape when pressed alone (cool but I don’t use this).

How I manage my keyd configuration

Rather than editing the /etc/keyd/default.conf file which is typically owned by root, I make /etc/keyd a symlink to my dotfiles:

$ git clone git@git.sr.ht:~razzi/.dotfiles ~/.dotfiles
$ ln -s (pwd)/keyd_config /etc/keyd

Now I can edit the user-writable keyd_config/default.conf and apply my changes like so:

$ vim ~/.dotfiles/keyd_config/default.conf
$ sudo systemctl restart keyd

What’s in my config?

[ids]

*

[main]
# Maps capslock to control
capslock = layer(control)

# Maps alt to escape when pressed alone and alt when held
alt = overload(alt, esc)

# c-h to backspace
[control]
h = backspace

# Rightalt+space to alt+tab
[altgr]
space = A-tab

# alt-q to alt-f4
[alt]
q = A-f4

The config is tracked as part of my dotfiles.