Remapping keys on macOS

I ramble a bit here - you may want to skip to how to remap keys on macOS.

I attended WWDC for the first time ever (making lemonade in the COVID-19 situation), and after watching the keynote, got pretty excited about macOS Big Sur.

I wanted to install the macOS Big Sur developer beta but not at the expense of making my main development MacBook Pro virtually unusable. One of the things I thought I really needed working was Karabiner-Elements, which I use to remap keys, specifically:

• Caps Lock to Esc
• Esc to `

This particular remapping is really because I use ` (backtick) as my tmux prefix key. I picked this up from an ex-colleague after watching him fly while switching tmux panes. And I use either a compact 60% or 65% keyboard which meant I didn't have a dedicated ` key - I'd have to hit Fn-Esc which is even more terrible than the default of Ctrl-B.

Unsurprisingly, Karabiner-Elements was not working in Big Sur. Not satisfied with that, I quickly found that macOS has supported native key remapping since macOS Sierra via the hidutil command-line tool. If you're not beyond scrappily writing some JSON and XML, this just works:

1. Decide what keys you want to remap. In my case, I wanted to remap Caps Lock to Esc.
2. Apple's docs say:

   The keys take a hexadecimal value that consists of 0x700000000 or’d with the desired keyboard usage value

   Pretty cryptic, but what it really means is you just have to add 0x700000000 to your key's "usage ID" in this table (techically, this is a bitwise OR, which is not addition, but the usage IDs are small enough for it to not matter).
3. Caps Lock's usage ID is 0x39. Adding 0x700000000 to that gives 0x700000039.
4. Esc's usage ID is 0x29 - we'll use 0x700000029.
5. Caps Lock (0x700000039) is the source, so we will specify "HIDKeyboardModifierMappingSrc": 0x700000039.
6. Esc (0x700000029) is the destination, so we will specify "HIDKeyboardModifierMappingDst": 0x700000029.
7. Repeat for each pair of keys you want to remap.
8. Try it out in the command-line:

   hidutil property --set '{"UserKeyMapping":[
     {
       "HIDKeyboardModifierMappingSrc": 0x700000039,
       "HIDKeyboardModifierMappingDst": 0x700000029
     },
     {
       "HIDKeyboardModifierMappingSrc": 0x700000029,
       "HIDKeyboardModifierMappingDst": 0x700000035
     }
   ]}'

9. This remapping will be undone whenever you reboot your Mac, so one way to persist the remapping is to run the hidutil command every time your Mac boots. For that, we can rely on Launch Agents.
10. Create a file named ~/Library/LaunchAgents/com.example.KeyRemapping.plist: This file basically tells macOS to run the hidutil tool when it starts up.
11. You're all set!

A vast improvement would be to generate the key remappings from an HTML form #ideas-are-free.

I really love Karabiner-Elements, but my use of it has become less complex of late. There's also something to be said about running less software. And that brings me a tiny step closer to trying out Big Sur - yes, I can't take the plunge yet! You can evaluate whether you are ready after taking a look at this list of apps that are not working on macOS.