Hammerspoon – Lua-based powerful tool automation of macOS

Since we've hit the front page of HN again, I've just released Hammerspoon 0.9.92, which contains a few fixes and some additions, but mostly refactored a significant amount of internal project structure to allow our build system to be replaced with something that isn't 5 years old and terrible.

As a result, it's possible that something broke which we didn't find in our internal testing. Please file GitHub issues :)

Happy Christmas y'all!

If anyone cares, here's my config: https://github.com/kbd/setup/blob/master/HOME/.hammerspoon/i...

It shows off a tiny bit of what you can do with Hammerspoon:

  - window and app management
    - keyboard shortcuts for common apps (eg. hyper+T for text editor, hyper+B for browser, hyper+S for shell)
    - if you can code a tiny bit of Lua there's no need for apps like Spectacle, Rectangle, Moom, etc. because it's easy to position apps wherever you want. eg. hyper+L arranges my browser+editor+terminal in a standard layout, and I have other shortcuts to set apps to halves or thirds of the screen, or to another monitor.
  - fuzzy-find popups (like Alfred/fzf) are built-in. I use it to choose audio input/output.
  - a replacement for Caffeine (menubar icon to keep computer from going to sleep)

I have my "hyper" key bound to caps lock using Karabiner Elements (but it still works as a normal caps lock if you hold it for half a second). Here's that config: https://github.com/kbd/setup/blob/master/HOME/.config/karabi...

I love Hammerspoon. It's one of the first must-have-for-a-usable-laptop tools I set up when I get a new MacBook.

Here are the top ways I'm using it right now:

1) Hide/show apps similar to how iTerm lets you bind a hotkey to hide/show a terminal. I've got ctrl+space set to Vimcal, alt+space set to midnight.app (a time tracker I'm building), and ctrl+alt+space set to Things.

2) Start/stop playing my work playlist of lofi hiphop. I got tired of the friction around opening Spotify, going into my work playlist, hitting play, waiting several moments for the playlist to load, etc, so I downloaded a bunch of mp3s from YouTube and put them in ~/Music/work/. Now my work music is a single keyboard shortcut (semicolon+m) and a few miliseconds away.

3) Set up screen recording. There are a few things that need to happen before I start a screen recording (opening CamHead.app, setting my screen resolution, and showing the dock at a certain height so I can later crop the video to 16:9) and I have it all bound to a single hotkey (semicolon+r). I've got another hotkey set up to unset it (semicolon+e).

4) You may have noticed I'm using keyboard shortcuts with semicolon as a modifier key. That's done with Hammerspoon too! I've got an extra layer of hotkeys available to me to set up whatever else I can think of in the future. The code I wrote to use semicolon like this sometimes breaks if I try to type too many actual semicolons in a row but I usually rely on JS Beautify to add those for me.

Really nice at first sight.

I'm getting melancholic vibes of AutoHotKey reading the docs, which was arguably my first entry into professional programming. Knowing nothing about coding, I built a service desk automation back then — with (network file-) shared hotkeys and a real GUI, all in one single file... good times.

Anyway, ever since switching to MacOS more than a decade ago, I've always been searching for an AHK analog for those simple keystroke automations, text-based, with just enough of a glue language to hold it all together — Automator never quite cut it for me, after wielding the full power of AHK, it always felt too limited, rigid and clicky-colory.

Even though I don't have immediate use cases for it anymore, it makes me very happy that I know where to go back now!

I've hooked up Hammerspoon to a bunch of APIs for fast lookups: translation, autocorrect, company lookup, etc.

Translate (Requires Google Translate API key) https://github.com/pasiaj/Translate-for-Hammerspoon

Autocorrect: https://github.com/nathancahill/Anycomplete

Hammerspoon is great. I use it to manage windows (eg set vscode and a browser side-by-side when connected to an external display, full screen when not), add a hotkey to translate selected text with Deepl, to mute sound when the machine sleeps, and to launch a terminal with an fzf-based browser history searcher that beats Firefox’s hands down.

It’s easy to use and has great docs. Lua is fun to write. HS is a really nice project.

I’ve especially enjoyed using Hammerspoon in combination with the prebaked config “Spacehammer” (https://github.com/agzam/spacehammer), which takes a lot of inspiration from Spacemacs (and, of course, enables a systemwide “edit this text field with emacs” workflow).

I fell briefly in love with Hammerspoon, but stopped using it.

My MacOS automation is now my QMK keyboard calling Alfred workflows; I use Yabai for window management.

I admire Lua, but ran into some sharp edges learning to program in it. Still, one can get up to speed quickly if one knows other scripting languages.

Hammerspoon window management was deathly slow. Yabai is close to instantaneous.

Another happy Hammerspoon user reporting.

I feel Hammerspoon's Lua is to macOS what elisp is to Emacs. You can use it to glue all sorts of wonderful things.

I wrote a bit about it here: https://xenodium.com/emacs-utilities-for-your-os (building my own Alfred/Quicksilver-like experience) and https://xenodium.com/cycling-window-layouts-via-hammerspoon (cycle through my preferred window layouts).

edit: typos

Love Hammerspoon, I have a small snippet to store bookmarks. I copy the url, open the shortcut, add tags and it is saved to sql lite file.

  local function insertDB(db, linkval, value)
    local url = tostring(linkVal)
    local categ = tostring(value)
  db:exec[=[
           INSERT INTO bookmarks VALUES (NULL,`url`,`categ`) 
    ]=]
   end


  hs.hotkey.bind({"alt", "ctrl"}, "S", function()
    db = hs.sqlite3.open('/dropbox/user/bookmarks.db')
    local insert_stmt = assert( db:prepare("INSERT INTO 
  bookmarks VALUES (NULL, ?, ?)") )

  local url = hs.pasteboard.getContents()

  local tag, value = hs.dialog.textPrompt(url, "Please enter 
  category:");

  if tag == 'OK' then
  insert_stmt:bind_values(url, value)
  insert_stmt:step()
  insert_stmt:reset()
  -- insertDB(db, linkVal, value) 
 end

end)

I'm a big fan of hammerspoon, but not so much Lua. I also use emacs with Doom, where a lot of bindings are behind a 'leader key'. I found an awesome framework called 'spacehammer'[1] that fits very well into the way I like to work. It similarly hides binding behind a leader, and it's written in Fennel, a lisp that compiles to Lua. I feel like I get to expand the customizability of Emacs out to my whole system and I love it. Hammerspoon is pretty bare on its own so I suggest you check out spacehammer even if it's just a show case of the potential of hammerspoon.

[1] https://github.com/agzam/spacehammer

I like Hammerspoon, but it's a bit of a pain to write the scripts with Lua - I don't use the language often and it usually takes a while to figure out syntax and necessary stdlib/Hammerspoon functions. Does someone have a hint on how to set up e.g. VSCode or IJ with Lua support and completion for Hammerspoon functions?

The only shortcoming I run into frequently with Hammerspoon is the fact that it is not low-level enough in the keyboard listening stack. I use Karabiner-Elements which solves most of the things I need such as literally remapping the “fn” key because there’s no way for Hammerspoon to know if the “fn” key is pressed, only the more standard modifier keys. It also gets very tricky because I replace Caps Lock with “fn” and combine it with other modifier keys. It also can’t distinguish between “Left shift” and “Right shift” keys for example.

Overall though I’m extremely grateful for Hammerspoon and if it ever stops working I might consider moving to Linux as my personal machine. I am able to chain key presses infinitely and categorize the different functions.

For example, I press “Caps Lock” + “Left shift” + “a” to open a global key chording menu, press “w” for my “window management” category which opens another key chord menu, then press “w” again to maximize my current window. I replace the final “w” with “m” to minimize, “p” to open the most recently used window in a stack of windows in an application. Not only that, these keys are case sensitive so that effectively doubles my space of usable infinite key chords.

Hammerspoon is so amazing for developer workflows after you put the time in.

My pretty extensive (but poorly organized) config:

https://github.com/nonissue/hammerspoon

Features include: - TOTP menubar app (that automatically types the code when clicked) - A menubar app for quickly changing screen resolution - A menubar sleep timer - Window management with convenient hot keys and undo functionality - Capslock rebinding to ESC when pressed alone, CTRL when pressed with other keys - A utility to allow you to both save a screenshot to disk AND have it copied to clipboard (AFAIK you can't do this natively in macOS).

There's other a bunch of other stuff, but those are the highlights. If you have any questions about it, please let me know! (email: andy@nonissue.org or open an issue on github).

I use this!

- Mute my computer when I put it to sleep or when I change wifi networks

- Hyper key

- Mail.app menubar indicator

- Spotify menubar current song

- Shortcut to move mouse cursor to another monitor

- Window switcher that only lists apps in the current workspace

I've been using Phoenix (https://github.com/kasper/phoenix), which is hackable in JavaScript (here's my config: https://gist.github.com/rcarmo/5132874cdaf2755e42907508802e8...) and has a smaller scope (only window management), but haven't found it compelling enough to keep hacking at my config, so I'm back to Moom (https://manytricks.com/moom/), which would be perfect if it supported chaining sequences of sizing instructions (i.e., tile a window twice to the left to turn it from 1/2 to 1/3 width).

One of my more useful things, cmd+shift+m and cmd+shift+u to minimize all windows and un-minimize all windows of the active application. The un-minimize gets used more often (e.g. I may have a few Chrome windows minimized during my workday that I want to un-minimize en masse after work is done).

    local cmdShift = {'cmd', 'shift'}

    hs.hotkey.bind(cmdShift, 'm', function()
      local app = hs.application.frontmostApplication()

      for _, window in pairs(app:allWindows()) do
        window:minimize()
      end
    end)

    hs.hotkey.bind(cmdShift, 'u', function()
      local app = hs.application.frontmostApplication()

      for _, window in pairs(app:allWindows()) do
        window:unminimize()
      end
    end)

In case people are looking for more of these for Mac or Windows, well... I've been making a list, and checking it twice:

- https://taoofmac.com/space/apps/window_managers

I'm a big fan of Hammerspoon.

At least a few years ago, OS X's window management when plugging/unplugging external monitors was pretty bad.

Thanks to Hammerspoon, I don't have to think about it at all - I plug in monitors when I want to and all my windows resize and move themselves based on rules I defined.

It means stepping away from my desk or coming back to it is a no-brainer.

Maybe it's not needed these days, but it sure was a lifesaver back when I first adopted it.

My config, if people are interested:

https://github.com/NateEag/dotfiles/blob/master/src/.hammers...

I like hammerspoon. I’ve been using it for years and never got beyond setting up window resizing with the visual grid - which I think is like one of the very first steps in the tutorial - but I’d recommend it just for that.

I really like HS especially filling the macOS missing features place like for windows management + either opening/focusing specific applications with shortcuts.

Does anyone knows a cross platform tools that can map keyboard keys to mouse button? Preferably in a layer?

Does anyone have a wrapper for this and suckless it's dmenu?

I'd love to have one config that delivers the same workflow for my macos and my Debian system.

Maybe it's a nobrainer with a simple shell script, I haven't looked into it yet myself.

I don’t use Mac but it seems that this is the app that keeps popping up whenever I find out that some kind of desktop/window manager automation is easier on Mac than on Linux. Nice.

Love Hammerspoon! I wish there was an easier way to find great scripts, though. They seem to be all over the internet in random places.

Just curious do people use these types of automations to help with coding/software engineering? If so, in what way?

Is there something like this for python?

hmmm I could use this to spoof "productivity" monitoring software. I was planning on build my own app to do this but this looks like a nice alternative.

Thanks!

Fyi applescript offers a JS engine