Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


What even is this?

The simplest answer is that Hammerspoon is a Lua-based automation framework for your macOS-based computer. It has a robust and well-documented Lua layer on top of the macOS core libraries and APIs.

So, what does my config do?

  • Push-to-Talk (PTT): includes a handy menubar icon for current "talk" status. Bound to holding alt+cmd to talk.

  • Spotify Controls: simple keybindings to handle Play/Pause, Next, Previous. Bound to ctrl+shift+[, ctrl+shift+], ctrl+shift+\.

  • Computer Locking: locks your computer with a set of key commands. Bound to cmd+ctrl+shift+l.

  • Accidental app quitting protection: prevents accidental app quitting, makes you hit cmd+q twice.

  • Application Toggling:

    • Finder: ctrl+backtick
    • Chrome: cmd+backtick
    • Kitty: ctrl+space
    • Slack: cmd+ctrl+shift+s
    • Spark: cmd+ctrl+shift+m
    • Zoom: cmd+ctrl+shift+z
    • Messages: cmd+shift+m
    • YakYak: ctrl+shift+m
    • Spotify: cmd+shift+8
  • App-specific customization:

    • apps can define their own custom fn to be executed when they are active, for example, custom keybinding (see Slack in config.lua)
  • Window Management:

    • Automatic window placement, as presently configured in config.lua.
    • Manual window placement and sizing (with chaining to different sections of the screen as you repeat the keypresses).
      • Bound to cmd+ctrl+j/k/l/h.
  • Laptop "Docking/Undocking" Events:

    • When docking my laptop (plugging in the single TB3 cable, aka using the laptop in desktop mode), it automatically switches:
      • switches Karabiner-Elements profile to pok3r (for my Vortex pok3r mechanical keyboard)
      • switches audio output to AudioEngine D1
      • switches audio input to Logitech Webcam C930e
      • switches off WiFi
    • It will reverse all of the above to the internal/built-in devices of my MacBook Pro when unplugging the single TB3 cable
  • Home Assistant Integration:

    • When logging into the computer, and I'm at home, it will fire off certain shell scripts to my Home Assistant server to handle device control in my office (lights, etc). Home Assistant does this based on other factors, like the weather, time of day, etc. This is very much a WIP.
  • Other Things:

    • I'm sure I missed some of the other things I've added or modified. The above documents the most notable and most used Hammerspoon automations.
    • Be sure to check out the main config to see what all is setup right now.


You can’t perform that action at this time.