Doug Rudolph

Installing ChunkWM

Posted on July 26th, 2018

This blog post goes through the process of downloading a tiling window manager (TWM) on OS X, as well as how it can optimize your workflow.

  1. Introduction
  2. What is ChunkWM
  3. How do I Install ChunkWM
  4. How do I Install SKHD
  5. Closing


I recently had to start using OS X for work, and as a former Linux user, I felt something missing from my workflow. OS X is often thought of as the more capable and professional Linux machine, yet I still miss that ability to personalize the user experience to my liking. Sure, Linux is finicky, but having complete control is a privilege that you adjust to. So, while I can't use Linux at work, I can cover up its absence with ChunkWM.

What is ChunkWM

So this is ChunkWM:


ChunkWM is a Window Manager - which is just software that manages the layout of all your windows. The most obvious benefit that comes with using ChunkWM is navigation. ChunkWM allows you to move, open, close, and navigate to all windows on screen with just your keyboard.

Installing ChunkWM

Installing ChunkWM is not as simple as I hoped. The one thing you need before hand is homebrew - feel free to install that from here. Once homebrew is installed, we are going to need to install two pieces of software: SKHD and Homebrew-ChunkWM.

Quick overview: SKHD is a piece of software that listens to our keyboard inputs, while ChunkWM is what manages how our windows are laid out. Together, they listen to our keyboard for ChunkWM commands and relay the commands to a selected window.

To start, the first thing that we need to do is clone the ChunkWM repository from GitHub. To do this with homebrew, type out:

doug@root-user$ brew tap crisidev/homebrew-chunkwm

If all goes well when installing, you should see a message that prints something along the lines of:

Copy the example configuration into your home directory:

    cp /usr/local/opt/chunkwm/share/chunkwm/examples/chunkwmrc ~/.chunkwmrc

Opening chunkwm will prompt for Accessibility API permissions. After access
has been granted, the application must be restarted with:

    brew services restart chunkwm

This has to be done after every update to chunkwm, unless you codesign the
binary with self-signed certificate before restarting Create code signing
certificate named “chunkwm-cert” using Keychain

    codesign -fs “chunkwm-cert” /usr/local/opt/chunkwm/bin/chunkwm

NOTE: options “--with-logging” and “--with-tmp-logging” are deprecated since now
chunkwm supports logging through configuration:

    chunkc core::log_file 

NOTE: plugins folder has been moved to /usr/local/opt/chunkwm/share/chunkwm/plugins
To have launchd start crisidev/chunkwm/chunkwm now and restart at login:

    brew services start crisidev/chunkwm/chunkwm

Or, if you don’t want/need a background service you can just run:


That long output explains how to copy the default config file to our home directory, but before doing that, we want to make sure ChunkWM downloaded to the right directory. To check, try running:

doug@root-user$ ls /usr/local/Cellar/

If you don't see a directory, try going to Github and manually cloning the project to your homebrew folder. If you do see the ChunkWM directory, copy the first command that was printed after installing. I went ahead and copied the command you need here:

doug@root-user$ cp /usr/local/opt/chunkwm/share/chunkwm/examples/chunkwmrc ~/.chunkwmrc

This command will create a .chunkwmrc file inside your home directory. Just for good measure, we are gonna want to make sure our .chunkwmrc is executable. If that file is not exectuable, ChunkWM will not run correctly. To make sure things work, type out:

doug@root-user$ chmod +x ~/.chunkwmrc

Next, we are also going to want to system link the plugins folder to our home directory. Note - this isn't necessary in the latest build, but we're going to do this just in case the build is ever revereted.

doug@root-user$ ln -sf /usr/local/opt/chunkwm/share/chunkwm/plugins ~/.chunkwm_plugins

Congrats! You've installed ChunkWM. To make sure everything was done correctly, running ChunkWM should result in windows auto-scaling to your screen. To test this, type out:

doug@root-user$ brew services start chunkwm

Doing this should bring up an OS X prompt asking you to allow for ChunkWM to "be apart of the accessibility list." Allow ChunkWM to be in your accessibility list. Once you do so, restart ChunkWM by typing:

doug@root-user$ brew services restart chunkwm

Installing SKHD

Nice! The hard part is done. All that is left is to install SKHD. To do this, run:

doug@root-user$ brew install koekeishiya/formulae/skhd

And just like before, brew is going to output a message that defines where to copy a config file - just this time it's a .skhdrc file. To keep things brief, I'm going to give you the command directly:

doug@root-user$ cp /usr/local/Cellar/skhd/examples/skhdrc ~/.skhdrc

Next is to start running SKHD. Similar to how we ran ChunkWM, we are going to run SKHD with:

doug@root-user$ brew services start skhd

This will promt you to "add SKHD to your accessibility list" - do so and restart SKHD with:

doug@root-user$ brew services restart skhd

If all goes well, you should be able to rotate two or more windows with the following command: option + r. If option + r worked, you have completed everything!


Stay tuned for my next post where I'll go over how to navigate windows with ChunkWM. Thanks for reading! And as always, see you in the next blog :)