My macOS Keyboard-Driven Setup: skhd + Yabai + Karabiner

September 15, 2022 (4y ago)

I touch type at 90+ WPM. I can navigate Vim without looking at my hands. Yet until 2022, I still reached for my mouse dozens of times a day.

That changed when I discovered the macOS keyboard automation stack: skhd, Yabai, and Karabiner.

The Problem

Every time you reach for your mouse:

  1. Your hands leave the keyboard
  2. You switch cognitive contexts (hands → eyes → different hand position)
  3. You lose flow state

For coding, that's fine. But for window management? Launching apps? Navigating tabs? The mouse was slowing me down.

The Solution Stack

1. Karabiner — Keyboard Remapping

Karabiner lets you remap keys at the system level. My essentials:

  • Caps Lock → Control — The most important remap. Vim uses Ctrl constantly.
  • Hyper key — I map Caps Lock to Hyper (Ctrl + Shift + Option + Cmd). One key = four modifiers.
  • Custom layers — Hold a key to switch to symbols layer.
{
  "from": "caps_lock",
  "to": [
    {
      "key_code": "left_control",
      "modifiers": ["left_command", "left_option", "left_shift"]
    }
  ]
}

2. Yabai — Window Management

Yabai is a tiling window manager for macOS. It controls window positions programmatically.

# Split window vertically
alt - space : yabai -m window --toggle split

# Fullscreen
alt - f : yabai -m window --toggle zoom-fullscreen

# Move to space 1
cmd - 1 : yabai -m space --focus 1

No more dragging windows. No more clicking maximize. Just keyboard commands.

3. skhd — Hotkey Daemon

skhd listens for key combinations and runs commands. Combined with Yabai:

# Create new space and move focused window
shift + cmd - n : yabai -m space --create && \
  index="$(yabai -m query --spaces --display | jq '[-1].index')" && \
  yabai -m window --space "${index}"

# Float/unfloat window
alt + shift - t : yabai -m window --toggle float && \
  yabai -m window --grid 4:4:1:1:2:2

# Balance windows
shift + alt - 0 : yabai -m space --balance

My Daily Workflow

| Action | Keys | What Happens | |--------|------|--------------| | New window | + 1-9 | Focus space | | Split | alt + space | Split vertical/horizontal | | Fullscreen | alt + f | Zoom to fill | | Move window | shift + alt + h/j/k/l | Swap north/south/east/west | | Float | alt + shift + t | Toggle floating | | Create space | shift + cmd + n | New workspace |

Why This Matters

The mouse is a precision tool. It's great for graphic design, video editing, or selecting text precisely.

But for navigation? It's slow.

With this setup, I can:

  • Move windows without leaving the keyboard
  • Create and manage 10 workspaces
  • Float/unfloat windows instantly
  • Run shell commands from anywhere

The Bigger Picture

This is part of a philosophy: keyboard-driven development.

It's not about being a keyboard purist. It's about flow. It's about keeping your hands where they need to be.

Once you build the muscle memory, you won't want to go back.

Next: Surfingkeys: Vim Keys in Every Browser