Hammerspoon: History

hammerspoon logo

I use Hammerspoon to enhance my OSX with custom UI and automations, while also creating "monotasking" deep work environments to keep me focused.

In 2012, I read the Modern Space Cadet article by Steve Losh. This was hugely impactful and I've pretty much tried everything on it (the shift-key training wheels were frustrating but helped my typing!) and I started playing around with all those tricks, especially the Hyper key.

Initially, the Hyper key is a "magic" hack for keyboard shortcut lovers where it assigns a single keypress to the unreachable modifier chord of ⌘⌥⇧⌃. No OS X app uses that crazy chord, but most will let you use it as modifiers for a keyboard shortcut. This enables the user to set a custom keyboard shortcut that will not override a standard keyboard shortcut… effectively a layer of shortcuts that's all your own.

I used Mr. Losh's exact setup for quite a long time: Use KeyRemap4Macbook1 to map a key to the "hyper", and use Keyboard Maestro to listen for that chord and fire off automations, primarily switching between applications.

It's hard to overstate the impact of this hack on my computing style. I haven't used the ⌘+TAB app switcher regularly for nearly eight years now… my fingers just open the browser with HYPER+k, and that is How Computers Should WorkTM. At the time, I was a software developer working mostly on the front-end, so the ability to instantly switch from my editor to the browser shortened my OODA loop and allowed me to iterate very quickly. If you bounce back and forth between two or three programs on a regular basis, I highly recommend investing in something like this.

This has gone through several iterations through the years. I moved from Keyboard Maestro to Alfred for this, using their visual workflow builder to define simple app switching rules. Eventually, there was some kind of breaking change that drove me to Hammerspoon2 sometime in 2018. I'm not entirely sure where I found it, I know it was while searching for a solution to my Hyper-key problems.

I found Hammerspoon's Lua-powered little engine to be powerful and much faster than anything I had used. I was hooked.

While Keyboard Maestro is very powerful, and people have been writing applescripts for Automator forever, Hammerspoon snuggled into a sweet spot in my toolchain. I am a programmer, so anything that I can read and maintain in git is a major bonus. Hammerspoon has enough hooks and API libraries to make writing it fairly easy3. I frequently find myself encoding a process or a UI layout into my Hammerspoon repo for repeatability and consistency.

As my job changed, my uses for Hammerspoon have changed. In some ways, the ability to instantly summon any application is now a bit of a curse to my precious focus rather than a boon to efficiency. I have started restructuring a bit in order to change with me, and it'll probably look totally different in two more years.

At the moment, I use Hammerspoon to:

  • Focus apps with a hotkey.
  • Manage a globally accessible hotkey modal.
  • Connect and disconnect my AirPods.
  • Automatically close distractions in tabs and in apps.
  • Move my windows around.
  • Automatically create layouts for common tasks.
  • Track time to toggl based on activity.
  • Create projects in Things 3.

And more to come... 😈

I'm going to take a few posts and document some of the modules and methodologies to my OS X desktop automation powered by Hammerspoon. While my configuration is a moving target this feels like a good point to do this, it's stable, I'm using it every day, and there are a few things that I've written that I haven't seen done before, and that I've been planning on writing for years.

If you just love automation, and you do not consider yourselves a programmer, you may be able to just clone and tweak my system or another user's. You may also want to take the ideas in this series and implement them in Shortcuts on iOS or Keyboard Maestro. The techniques work regardless of implementation.

  1. Replaced by Karabiner.app, now replaced by Karabiner-elements.app. ¯(°_o)/¯ 

  2. The original commit. I wish I could remember exactly what led me here… it's very likely it was Brett Terpstra's post or my friend Seth

  3. There's a healthy standard lib, but I can't believe I went so long without noticing hs.inspect

  • 2024-02-20 09:38:14 -0600
    Convert to permalinks

  • 2022-06-08 11:31:29 -0500
    Rename articles

  • 2020-09-28 09:20:43 -0500
    Change repo name

    I decided to change the name of my hammerspoon configuration repo to
    `hammerspoon-config` to avoid confusion... it's not the actual
    hammerspoon executable, it's a configuration for that executable.

  • 2020-06-14 15:51:50 -0500
    Update articles with series and series partials

    After the refactor, needed to move the series metadata to the actual

  • 2020-06-08 14:32:30 -0500
    Post: Hammerspoon History