FAQ

Do you collect information about crashes?

By default, yes. This can be disabled in the Hammerspoon preferences. For more information, see our Privacy Policy

Accessibility issues

Hammerspoon depends on access to the macOS accessibility stack to interact with the desktop, and due to the security requirements in macOS, the user is required to manually allow Hammerspoon access to the accessibility features. macOS manages the list of applications with access to accessibility features in System Preferences. Click on the `Security & Privacy` icon, then the `Privacy` tab and then `Accessibility` from the list. You should ensure that Hammerspoon is present in this list and is ticked.

I can't add Hammerspoon to the list, or enable it

It is unlikely, but possible, that the database controlling access to accessibility features, has become de-syncronised from reality. There is a guide to how to recover from this situation, at http://mizage.clarify-it.com/d/6ervmn (replace 'divvy' in the SQL query, with 'hammerspoon') It's also possible that your Launch Services database has become confused/corrupt. You can force it to rebuild with the command:

sudo /System/Library/Frameworks/CoreServices.framework/Versions/Current/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user

Hammerspoon is not sending keystokes to other applications after upgrading to Catalina

Try resetting all of Hammerspoon's permissions by executing this in Terminal:

tccutil reset All org.hammerspoon.Hammerspoon

hs.application issues

Application names aren't what I expect

If you are trying to find Microsoft Office applications (e.g. using hs.appfinder.appFromName("Word")), they present a different application name to the OS than they display in the system menu bar. Use "Microsoft Word", "Microsoft Excel", etc. instead.

You can get a list of the real names of all running applications in the Hammerspoon Console with the following snippet:

hs.fnutils.each(hs.application.runningApplications(), function(app) print(app:title()) end)

I can't make :findMenuItem() or :selectMenuItem() work in the Hammerspoon Console

Many macOS applications (e.g. Emacs, IBM Notes, Adium) mark their menus as disabled when their windows lose focus, so you may find that you can't play with them from the Hammerspoon Console. Your only option here is to encode the actions in your init.lua or bind them to events (such as hotkeys) from the console, then transfer focus back to the application window.

Issues with full-screen applications

No graphical/UI elements appear when an application is in full-screen mode

This is known to happen when running Hammerspoon with the Dock icon enabled. Try unchecking the "Show dock icon" option in the Hammerspoon Preferences, or add the following code to your init.lua file:

hs.dockIcon(false)

Can I donate money to Hammerspoon's developers?

That is a tremendously generous thought, which we appreciate very much. However, we've taken the view that we would rather keep working on Hammerspoon for fun and not feel obligated to work on it because of money.

Instead, we would ask that you decide how much Hammerspoon is worth to you, and donate that amount of money to a charity of your choosing.