A keyboard-first macOS with Karabiner-Elements and yabai

Overview

My Mac has no window management muscle memory that involves the mouse. The tiling window manager is yabai ↗ in BSP mode, and every command reaches it through Karabiner-Elements ↗. Most yabai setups pair the WM with skhd for hotkeys; mine does not. Karabiner is the only hotkey layer, which means one config language, one rule system, and one place to look when a key stops doing what I expect.

The setup replaced BetterTouchTool ↗, which used to own my window snapping and custom shortcuts, and it retired the scripting layers from earlier experiments: Hammerspoon’s Lua engine and Übersicht. The rest of this post is the setup as it stands: the hyper key, the vi and mouse modes, and the full key map between Karabiner and yabai.

The complex_modifications layer

All the interesting behavior lives in ~/.config/karabiner/assets/complex_modifications/*.json: twelve hand-edited files, each a self-contained rule bundle that the Karabiner GUI imports. Edits here survive every GUI rewrite.

Per-device settings handle the smaller jobs alongside the rules. Two external keyboards swap command and option, because both are Windows-layout boards and muscle memory should not care which machine I am typing on. On the laptop, the built-in keyboard disables itself whenever that external board is connected. Four fn keys get back their macOS duties (mission control, launchpad, and the two illumination keys) for boards that ship without a media row.

The hyper key

The anchor of the whole setup is caps lock. When pressed with any other key it becomes hyper: command+control+option+shift all at once. That single decision turns one dead key into a prefix with no competition, since no macOS app binds all four modifiers.

The rule comes from the Karabiner complex modifications library ↗. Real caps lock did not die; it moved: shift+caps_lock stays actual caps lock, which I press roughly never, and caps lock alone still holds caps lock, which the app launcher relies on for chording.

The hyper layer launches apps straight from the keyboard:

One subtlety: hyper is exactly the chord macOS uses for its hidden system diagnostics, so a fumbled launcher key can pop a wifi diagnostic utility in the middle of a demo. Three rules defuse that by remapping the dangerous chords to harmless keys:

{ "from": { "key_code": "period",
            "modifiers": { "mandatory": ["command", "shift", "option", "control"] } },
  "to": [ { "key_code": "f19" } ] }

The comma and w variants map to F18 and F17 the same way. Function keys themselves get help too: fn+1 through fn+12 emit F1 through F12 for the boards that lack a function row, and F3 through F6 remap to mission control, launchpad, and keyboard illumination.

Escape, quit, and punctuation

Three small rules earn their keep daily:

• jk escapes. Pressing j and k within 200 ms of each other, in any order, emits Escape. The hands almost never leave the home row, in the editor or anywhere else.
• Esc is the backtick key. Escape with any modifier passes through as backtick with that modifier: command+esc cycles windows (command+backtick), command+shift+esc cycles in reverse, and plain shift+esc types a tilde. Escape sits in a better spot than the real backtick on most boards.
• command-q needs a hold. The quit shortcut requires holding command-q briefly before the app quits. Between the command/option swap on external boards and how often I mangle chords, accidental quits were a weekly event; now they are impossible.

And one for the typists: semicolon and colon swap characters. Unshifted semicolon types :, shifted types ;. Code likes colons far more than prose likes semicolons, so the common character gets the home position.

Vi mode and mouse keys

Two presets from the same library ↗ handle the cases where a key cannot just emit another key: Karabiner variables. In the Vi Mode rule, F+j pressed together latches vi mode, and until it clears, hjkl move the cursor, with variants for word-wise option-arrows and control+a/control+e. A companion chord latches visual mode, where the same movements carry shift and extend a selection.

Mouse Keys Mode v4 is the same idea for the pointer, using d as the mode key: d+hjkl moves the cursor, d+u/d+i/d+o click left, middle, and right, d+s toggles scroll wheel mode, and d+g/d+a drop or raise the speed to 0.4x and 2x. It rarely replaces the mouse, but for the occasional trackpad-unreachable click while my hands are on the keyboard, it is exactly right.

Karabiner as the yabai hotkey layer

Here is the whole trick in one manipulator: a complex modification rule whose output is a shell command.

{
  "type": "basic",
  "from": {
    "key_code": "h",
    "modifiers": { "mandatory": ["option"] }
  },
  "to": [
    { "shell_command": "/opt/homebrew/bin/yabai -m window --focus west" }
  ]
}

Option-h focuses the window to the west. Sixteen rules of this shape, grouped in one yabai-karabiner.json file, cover every window operation I use:

The focus rules deserve a note. opt+n runs yabai -m window --focus stack.next || yabai -m window --focus next || yabai -m window --focus first, so the same key walks a stack, then the flat layout, then wraps around. Stacks stop being a special case.

On the yabai side, ~/.config/yabai/yabairc is deliberately boring: BSP layout, a 6 px gap with generous top and bottom padding, window_border on at 6 px so the active window is obvious, auto_balance on, and ctrl-drag for move, resize, and stack-by-dropping. The bulk of the file is a long manage=off list: menu-bar apps, dialogs, utilities, picture-in-picture windows, anything that tiles badly stays floating, below everything else. There are commented-out rules that used to pin apps to numbered spaces; the space assignments now live entirely in my head and the shift+ctrl bindings.

Costs and gotchas

Every keypress in these rules spawns a shell. At human key rates that is invisible, but it is worth knowing that each option-h is a process, not a signal. The hand-edited rule files in assets/ are the safe layer to edit; the GUI only records that it imported them. Nothing in this stack needs a scripting engine: Hammerspoon and Übersicht from earlier setups are gone, because Karabiner already covers both the key remapping and the command dispatch.

One thing the move gave up: BetterTouchTool’s customization of the MacBook’s Touch Bar, the strip above the keyboard. I kept a quick compile button for Xcode there and used it plenty; Karabiner cannot touch that hardware, so the bar went back to Apple’s defaults.

Closing

The practical change is that my hands stay on the home row from login to shutdown. Window arrangement used to mean trackpad grabs and drag-to-snap; accidental quits were routine; now both are gone, and window management is a folder of plain JSON I can actually read. Moving over from BetterTouchTool took one long evening, and it has paid that back every workday since.