The death of the touchbar has brought back not just a glorious escape key, but a whole row of old school mac function keys.

Photo of a modern macbook function keys.
So beautiful 🥹

However, the functions that these key keys perform are no where near as useful to me.

  • Dashboard & Spotlight: Already have more familiar shortcuts; swipe up on the trackpad and ⌘-space.
  • Dictation & Do not disturb: I don’t use these features at all.

Also, where the fuck are my keyboard brightness buttons?!. A slider in control panel does not cut it. I need them to be alongside display brightness.

Photo of old macbook keyboard highlighting the brightness keys, followed by a very sad cat with the caption 'I just miss you'

Can I change what these buttons do? There are apps like Karabiner Karabiner-Elements, but they need to run as daemons and use accessibility functions to intercept keypresses. It feels a bit much to change two keys.

Turns out since MacOS 10.12 Sierra, there is a builtin tool that can remap keys, hidutil. Adam Strzelecki wonderfully documented it on his blog, achieving his dream function key row. Amar Syla made an amazing web tool that generates a command for hidutil and wraps it in a LaunchAgent plist ready to copy/paste.

It includes some of the mac function keys but not all. See it gets a bit tricky, different apple keyboards have a different arrangement of function keys. Some even use different codes for the same function! There’s a way to get the current physical keyboard’s function key mapping with ioreg, but you need to rearrange the output and add extra padding 0s so that hidutil accepts them. There’s a github issue to add more of these keys to Amar’s tool, with an excellent gathering of the codes that these keys use. Unfortunately the project appears abandoned, not to mention implementing the extra codes would be tricky; how would a user know which display_brightness_increment they need to use?

Enter funcremap.py⌗

Screenshot of my python script running, showing a menu of keys to remap
With all of this information I managed to remap my keys a while ago but it was a bit finicky. It really felt like just a touch of scripting could make it way easier. So I wrote a lil python file that does just that. It can grab your keyboard’s keys with ioreg, jumbles around the hex codes, then uses hidutil to perform the remap. It even both saves a login LaunchAgent while also setting the new binding to the current session, so the change is immediate and persistent.

You can remap whatever function to to any of the other mac functions. Finally my beloved keyboard brightness keys are back! You can also remap to any of the standard F keys, 1 through to 19. Most mac software doesn’t respond to the normal F keys, since the media keys are the default. Going past 12 is really entering uncharted territory, making them perfect as single key shortcuts. I remapped my F6/Do not Disturb key to F13, and made it open Terminal with a simple shortcut:

Screenshot of Apple Shortcuts App showing a shortcut with a single 'Open Terminal' action.
I can tap a key and Terminal will either open or come to focus. It's nice and quick too.

Or you can make use of the wonderful Application specific shortcuts if you want something specific to an App.

As a bonus I added options for escape, caps lock and the touch id button. Turns out the touch id is a button too if you press it hard. By default it performs Consumer Menu, a very oddball key that on macOS seems to lock the screen. There’s already control-command-Q for that, and pressing the key with a registered finger can just unlock it again straight away, so seems another good candidate for remapping to something more useful to you.

The script only uses builtin python modules so it should be easy to run, once you sort out the permissions:

wget https://bleepitybloopity.com/files/funcremap.py
sudo chmod +x funcremap.py
./funcremap.py

Or if you’re brave:

curl https://bleepitybloopity.com/files/funcremap.py | python

I thought about making it even easier to use with a whole GUI and more options for keys, but I don’t have an Apple developer certificate so it’s always going to be a pain for non technical people to run. Currently it fills a niche between ’lookup hex codes and write your own config’ and ‘just install karabiner’.