tl;dr:

brew install yqrashawn/goku/goku
mkdir -p ~/.config && cd ~/.config
touch karabiner/karabiner.json
touch karabiner.edn
# update your edn file with a sample from here https://github.com/yqrashawn/GokuRakuJoudo/blob/master/tutorial.md
# or mine: https://gist.github.com/kaushikgopal/ff7a92bbc887e59699c804b59074a126
goku

Background

I’ve been messing with mechanical keyboards recently.¹ There was one in particular which is a 60% layout that I fell in love with.

The trouble with 60% keyboards though is that they can be pretty constraining for some basic operations (like navigation). Notice there aren’t dedicated keys for the up/left/down/arrows.

Given these constraints, you have to get a little creative with how you use a keyboard. I added a bunch of mods for the keyboard using the mechanical keyboard’s included software configurator. I liked these mods so much that I wanted to find a way to use these mods with any keyboard I use.

The easiest way I’ve found on the Mac to do this is using Karabiner. Karabiner intercepts every keystroke and allows you to send alternative signals.

For example, a common mod that a lot of programmers like to do is remap their Caps Lock key -> Escape. So if I tap the Caps Lock key, it instead emulates hitting the Escape key. You can do this pretty easily with Karabiner but it barely scratches the surface of Karabiner’s true power.

Complex modifications:

Where Karabiner will truly shine is when you want to do slightly more complex things: for example, take the case of navigation with 60% keyboards. While they don’t come with dedicated arrow keys you can emulate navigation in a pretty slick way (especiallly for us vim users).

Instead of moving my fingers all the way to the bottom right of my keyboard and aiming for the arrow keys what if I could just keep my fingers on my home row and navigate like so:

tap caps lock once         -> Escape key
hold caps lock             -> left_control
hold caps lock and press h -> left arrow
hold caps lock and press j -> down arrow
hold caps lock and press k -> up arrow
hold caps lock and press l -> right arrow

You can of course choose to map any key combo (for example right shift key + W/A/S/D). I chose H/J/K/L cause I’m a vim user and I love just using h/j/k/l to navigate anywhere on my Mac!

More Complex modifications:

Even that, just scratches the surface of what you can do with Karabiner. Another quick hack I use and love (as a programmer):

tap  [ once                -> type "["
hold [ and tap ] key once -> type "{"
tap  ] once                -> type "]"
hold ] and tap [ key once -> type "}"

If you’re a programmer this makes it easier to type curly braces without contorting your fingers and flaring up that RSI. For typing paranthesis there’s an even better one:

left_shift once     -> type "("
hold left_shift     -> use as a regular shift key modifier
right_shift once    -> type ")"
hold right_shift    -> used as a regular shift key modifier

But there’s more!

Apart from just modifying your key strokes, you can do advanced stuff like launching programs too. For example I typically switch between 3 applications pretty often: iTerm, Firefox, Things. With Karabiner, I use the same technique but switch programs pretty quickly:

hold o (for "open") + tap i -> launch "iTerm"
hold o              + tap f -> launch "Firefox"
hold o              + tap t -> launch "Things"
tap o once                  -> type "o"

This makes switching between apps almost instant. I don’t have to carefully Cmd + Tab, visually recognize each icon (adding one extra cognitive step 😁) and then launch it. This might seem frivolous at first but once you start using this quick open mode like functionality, it’s hard to go back to Cmd Tabbing.

Turbocharge mode (Karabiner + Keyboard Maestro)

I swear by Keyboard Maestro and use a lot of my macros pretty often. With Karabiner, I can map certain keyboard strokes to instead launch macros. For example, if I want to quickly Google something, I hold “o” then tap “g” -> this shows an input dialog to take in my text, then launches a new tab in firefox with a url to google prepoulated with my query.

hold "s" + tap g    -> google for something on the web

This kind of usage in conjunction with Keyboard Maestro basically unleashes the power of your Mac.

How do I do this?

Before you head to the races and start using Karabiner though there’s one caveat:

Use Goku to organize your Karabiner

See the problem with Karabiner is that if you want to start doing the tricks I mention above, you pretty much have to start meddling directly with this file called karabiner.json. Let’s just say json is not the most maintainable format for this kind of stuff.

After meddling with Karabiner for a few days, it was clearly getting unwieldy to maintain the json file. So on an exaseperated whim, I went searching for a way to make it easier to deal with Karabiner and found the wonderful Goku.

Enter Goku

Goku basically is a DSL where you can write a nice and condensed form of the same code you would otherwise wrangle up in your karabiner.json. You write the code in this special format called “extensible data notation” (edn). Goku then reads that edn format and generates the karabiner.json file for you.

For context:

• my karabiner.json file currently has about 920 lines
• my karabiner.edn file on the other hand has 140 lines (and most of it is liberal commenting and whitespace to combat edn’s terseness)

{:des "o-mode: quick open"
 :rules [:o-mode
            [:f [:open "/Applications/Firefox.app"] ]
            [:g [:km "0) Search Google"] ]
            [:i [:open "/Applications/iTerm.app"] ]
            [:q [:km "open: Quip"] ]
            [:t [:open "/Applications/Things3.app"] ]
]}

{:des "right cmd -> right ctrl"
 :rules [
   [:##right_command :right_control [:apl-usb-int :apl-bt :ap2] ]
 ]}

{:des "left shift once -> ("
 :rules [
   [:##left_shift :left_shift nil {:alone :!S9} ]
 ]}

{:des "right shift once -> )"
 :rules [
   [:##right_shift :right_shift nil {:alone :!S0} ]
 ]}

Speaking as a programmer the edn format is quite possibly the most terse, terrible format I’ve encountered. I gave a quick look at some of the examples and almost abandoned my Goku effort half way.

But after spending an 11 hour flight back home fiddling and learning how to use Goku, I’ve gotten a decent hang of the format and I admit it’s super mantainable.

How to read and use Goku

I’m not going to explain how to use Goku, but I’ll tell you what helped me pick it up:

1. Read this fantastic blog post by Nikita Voloboev once
2. Follow along then with the official tutorial as they explain the basics
3. Read the blog post from step 1 again, given you’re a little more familiar with the format
4. Read my karabiner.edn file

I spent a lot of time commenting my edn file with the hope of making it more readable, so hope that helps. I plan on making a youtube video at some point demoing all this but until that happens, hope this blog post is helpful.

Hit me up on Twitter for queries or comments. Super curious to see other creative hacks people can come up with this technique.

Example edns

• goku repo example’s in the wild
• k-goku
• nikitavoloboev
• examples.org