The problem

You’ve played with a tiling window manager such as i3 on a Linux distribution before and want something like this on your Mac. Fortunately there are a few options and we’ll be covering Yabai.

Warning

Some of the features require you to disable parts of System Integrity Protection on your Mac. To some people (e.g. those using a work machine), this is not possible. Please know that this isn’t needed but you will not be able to use borders properly. I think this is the biggest drawback but you will also not get animation-free desktop transitions. This can be partially fixed by enabling Reduce Motion in your accessibility settings.

SIP disabled features will be marked in the config so you can see what features you won’t get.

Disabling System Integrity Protection

As per the official docs:

  1. Turn off your device
  2. Hold down command ⌘R while booting your device. (takes a while)
  3. Continue until you see Utilities in the menu bar

  4. Select Terminal

    # If you're on macOS 10.14 and above
# (printed warning can be safely ignored)
csrutil enable --without debug --without fs

# If you're on macOS 10.13
# (disables SIP completely)
csrutil disable
  5. Reboot

You can verify that System Integrity Protection is turned off by running csrutil status, which returns System Integrity Protection status: disabled. if it is turned off

Prerequisite

If you don’t already have the Xcode CLI tools installed, you’ll need to do this.

  1. Check if Xcode is already installed 
    $ xcode-select -p
  2. If that doesn’t output a path, install Xcode from the app store
  3. Install the CLI tools 
    $ xcode-select --install

Install Yabai

  1. Install it from homebrew

    $ brew install koekeishiya/formulae/yabai

# If you disabled SIP
$ sudo yabai --install-sa
$ killall Dock

Configure Yabai

  1. Create the config file 
    $ mkdir -p ~/.config/yabai
# Use the editor of your choice
$ [code|vim|emacs] ~/.config/yabai/yabairc

  2. Use my config your make your own. You can see all the settings documented here.

    #!/usr/bin/env sh

# global settings
# focus window that your mouse hovers on (disabled due to right click bugs)
yabai -m config focus_follows_mouse          off
# move mouse to focused window
yabai -m config mouse_follows_focus          on
yabai -m config window_placement             second_child
# floating windows always stay on top
yabai -m config window_topmost               on
# enable borders
yabai -m config window_border                on
# no clue what this is
yabai -m config insert_feedback_color        0xffd75f5f
yabai -m config split_ratio                  0.50
# don't automatically rebalance windows
yabai -m config auto_balance                 off
# swap windows if moved with mouse
yabai -m config mouse_action1                move
# resize windows if resized with mouse
yabai -m config mouse_action2                resize
yabai -m config mouse_drop_action            swap

# general space settings
yabai -m config layout                       bsp
yabai -m config top_padding                  5
yabai -m config bottom_padding               5
yabai -m config left_padding                 5
yabai -m config right_padding                5
yabai -m config window_gap                   06

# SIP Required
# prevent border from being under the active window
yabai -m config active_window_border_topmost on
yabai -m config window_shadow                on
yabai -m config window_opacity               off
yabai -m config window_border_width          6
yabai -m config active_window_border_color   0xffff3050
yabai -m config normal_window_border_color   0xffaaaaaa
  3. Make the config executable 
    $ chmod +x ~/.config/yabai/yabairc

Install skhd

  1. Install it from homebrew 
    $ brew install koekeishiya/formulae/skhd

Configure skhd

  1. Create the config file 
    $ mkdir -p ~/.config/skhd
$ [code|vim|emacs] ~/.config/skhd/skhdrc

  2. Copy my config. You can see a list of commands here.

    # Navigation
alt - h : yabai -m window --focus west
alt - j : yabai -m window --focus south
alt - k : yabai -m window --focus north
alt - l : yabai -m window --focus east

# Moving windows
shift + alt - h : yabai -m window --warp west
shift + alt - j : yabai -m window --warp south
shift + alt - k : yabai -m window --warp north
shift + alt - l : yabai -m window --warp east

# Move focus container to workspace
shift + alt - 1 : yabai -m window --space 1
shift + alt - 2 : yabai -m window --space 2
shift + alt - 3 : yabai -m window --space 3
shift + alt - 4 : yabai -m window --space 4
shift + alt - 5 : yabai -m window --space 5

# Resize windows
ctrl + alt - h : \
    yabai -m window --resize left:-100:0 ; \
    yabai -m window --resize right:-100:0

ctrl + alt - j : \
    yabai -m window --resize bottom:0:100 ; \
    yabai -m window --resize top:0:100

ctrl + alt - k : \
    yabai -m window --resize top:0:-100 ; \
    yabai -m window --resize bottom:0:-100

ctrl + alt - l : \
    yabai -m window --resize right:100:0 ; \
    yabai -m window --resize left:100:0

# Float and center window
shift + alt - c : yabai -m window --toggle float;\
                yabai -m window --grid 4:4:1:1:2:2

# Set insertion point for focused container
shift + ctrl + alt - h : yabai -m window --insert west
shift + ctrl + alt - j : yabai -m window --insert south
shift + ctrl + alt - k : yabai -m window --insert north
shift + ctrl + alt - l : yabai -m window --insert east

# Float / Unfloat window
shift + alt - space : yabai -m window --toggle float

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

# Change desktop
ctrl - 1 : yabai -m space --focus 1
ctrl - 2 : yabai -m space --focus 2
ctrl - 3 : yabai -m space --focus 3
ctrl - 4 : yabai -m space --focus 4
ctrl - 5 : yabai -m space --focus 5

Start services

  1. Start Yabai and skhd through homebrew. These will now launch on startup. 
    $ brew services start skhd
$ brew services start yabai
  2. You will probably be asked to give accessability permissions. Do it.

You’re done! 🎉

Please look at the skhd config for keyboard shortcuts. It takes a bit of practice but once you get used to it you can’t go back.