What is Hammerspoon? #

To answer this question, I’m just going to crib from Hammerspoon’s homepage itself:

This is a tool for powerful automation of OS X. At its core, Hammerspoon is just a bridge between the operating system and a Lua scripting engine. What gives Hammerspoon its power is a set of extensions that expose specific pieces of system functionality, to the user.

You can write Lua code that interacts with OS X APIs for applications, windows, mouse pointers, filesystem objects, audio devices, batteries, screens, low-level keyboard/mouse events, clipboards, location services, wifi, and more.

Hammerspoon gives you a blank Lua environment and a ton of APIs, and lets you combine them however you envision.

Honestly, I haven’t come up with many projects that I haven’t been able to pull off in Hammerspoon. This environment lets you be wildly creative, and combine all the major APIs that macOS provides with the pleasurable scripting of Lua, a language that’s both lightweight and quick to learn.

Once you’ve completed the course, I’ll give you an overview of every API available to you, and then you’ll be free to run wild and be creative with your own scripts.

Up front #

1. This course site has very minimal JavaScript (~100 lines), and I do not run any ad trackers or JavaScript analytics on the site. They weigh down the site, and it’s really not necessary.
2. If you have any feedback, please email me at d@balatero.com.
3. If you’re having fun with the course, tell your friends! Tell Twitter.
4. If you make your own projects, tell me about them! Send me an email. I want to see what you come up with.

Ok, now that that’s out of the way…

Course outline #

This course will start off by teaching you how to set the tool up and writing your first line of config. We’ll also set you up with a super and hyper key for the best key binding experience. From there, we’ll dive into a few essentials you’ll want to have handy to quickly debug and develop your custom scripts. For those of you new to Lua, I have a handy cheatsheet of syntax and concepts you can keep referring to as you get comfortable writing your own code.

Once we get past the intro stuff, we’ll immediately dive into making cool things! This course is split into a bunch of projects, each one exploring a different subset of the vast Hammerspoon API. I’ll be focusing on the really core APIs: things like keyboard input, hotkeys, shelling out to commands. These will be the meat and potatoes of what you do. You can explore the niche Hammerspoon APIs once you’ve completed the projects in this course.

You’ll get your feet wet with some small projects first. These projects will explore basic glue concepts like hotkey binding, shell commands, and a few other basic APIs. You’ll build things like:

• Basic window management hot keys to send any application window to the left, right, top, bottom, or center
• A fast Alfred-style audio device switcher
• An automatic audio output muter on wake from sleep
• A hotkey to silence your embarrassing macOS notifications while screen sharing
• and more!

Once you’ve worked through these small projects, I’ll walk you through some larger ones that are designed to broaden your understanding of the Hammerspoon APIs. You’ll draw custom UI, make rich keyboard entry experiences, manage your application windows like a pro, make custom menu bars, and so much more.

At the very end of the course, I’ll call out any other interesting Hammerspoon APIs. You can blend these with any of the main concepts you’ve learned during the course to make your own creative tools!