Edit: I am now using Hammerspoon which is a fork of Mjolnir that is basically the same except it comes with the modules (no luarocks), it’s under active development and the naming is slightly different and more consistent. Most of this article still applies.
Recently I started using the amazing and highly configurable window manager called Mjolnir.
But really it isn’t a window manager, it’s an OSX wrapper around a Lua configuration file and event loop that
has a constellation of modules that allow you to configure all sorts of computer control tasks. The most common use
for Mjolnir is managing Windows but there are all sorts of modules that allow you to use it for doing things like
unmounting your USB drives when you switch to battery power.
Two years ago I wrote a blog post about configuring Slate, the configurable window manager
that I had been using until this month. However, the maintainer hasn’t worked on Slate in years and there are dozens of pull requests sitting around without merge and comment. There have been attempts to revive it,
but there were still some rough edges and I decided to try something new.
Here I’ll describe how I use Mjolnir and my experience with it so far.
The instructions on Mjolnir’s homepage are pretty good as far as getting Mjolnir installed goes.
You’ll need to get luarocks working and then create an init.lua file, which isn’t very hard.
The basic install you get can’t do much so you’ll have to use some of the many Mjolnir modules.
Before you use a module you have to install it first, to install mjolnir.hotkey you would run
luarocks install mjolnir.hotkey
Mjolnir makes managing windows really easy with great modules to help you with this most of which are built upon the basic
functionality found in mjolnir.application.
That module provides basic access to running applications and their windows, which modules like
mjolnir.bg.grid use to provide things like the ability
to move windows around and resize on a grid. There are even fancier modules like
mjolnir.tiling which automatically organize your windows
like a fancy Linux tiling window manager would do.
Basic Key Bindings
Generally the way you want to start is by binding actions (really just Lua functions) to keys using the mjolnir.hotkey.
Here’s an example from the Mjolnir homepage of binding a key that just nudges a window right:
Since it’s just Lua code you can also just directly pass function names and use variables to refer to common chords:
Using a Grid
Personally I found the easiest way of doing window management was to use the mjolnir.bg.grid module. It provides functions that allow you to shuffle windows around a grid of a configurable number of rows and
columns (3x3 by default). Here’s an example of some basic bindings inspired by this config:
One of my favourite parts of Mjolnir is that you can write your own modules in Lua and Objective C to hook into OSX
functionality that Mjolnir doesn’t support by default. The great thing is other people have already written all sorts
of modules to do things like controlling Spotify
and playing sounds.
Recently I wrote my own module in 4 hours or so that adds the window hints feature that I missed from Slate:
mjolnir.th.hints. Except I think I did it even better than Slate did.
It allows you to quickly switch apps and windows using “hints” that pop up when you hit a key that have a letter on them,
when you press the letter it switches to that app.
All you have to do is bind it to a key:
My personal config is a bit fancier and more specific to me than you might want to start off with, but you might want to get
some ideas from it. You can find the latest version in my dotfiles repo,
but I’ve included my config at the time of writing later on the page because it will probably be simpler than my
config at the time you read this.
It has fancy features like rebinding the keys on keyboard layout change (which doesn’t always work).
Probably the best feature is a crappy implementation of something that mimics Slate’s support for layouts.