Convert Figma logo to code with AI

Hammerspoon logohammerspoon

Staggeringly powerful macOS desktop automation with Lua

11,867
578
11,867
579

Top Related Projects

23,088

A tiling window manager for macOS based on binary space partitioning

8,144

Hide menu bar icons on macOS

14,622

Automatic tiling window manager for macOS à la xmonad.

25,585

Move and resize windows on macOS with keyboard shortcuts and snap areas

Quick Overview

Hammerspoon is a powerful automation tool for macOS that allows users to create custom shortcuts, automate tasks, and control various aspects of their system using Lua scripting. It provides a bridge between the operating system and a Lua scripting engine, enabling users to interact with system elements like windows, applications, mouse, and keyboard.

Pros

  • Highly customizable and extensible
  • Powerful API for system interaction and automation
  • Active community and extensive documentation
  • Free and open-source

Cons

  • Steep learning curve for users unfamiliar with Lua
  • Limited to macOS platform
  • May require frequent updates to maintain compatibility with macOS changes

Code Examples

  1. Binding a hotkey to move a window to the left half of the screen:
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "Left", function()
  local win = hs.window.focusedWindow()
  local f = win:frame()
  local screen = win:screen()
  local max = screen:frame()

  f.x = max.x
  f.y = max.y
  f.w = max.w / 2
  f.h = max.h
  win:setFrame(f)
end)
  1. Creating a caffeine-like functionality to prevent sleep:
local caffeine = hs.menubar.new()

function setCaffeineDisplay(state)
    if state then
        caffeine:setTitle("AWAKE")
    else
        caffeine:setTitle("SLEEPY")
    end
end

function caffeineClicked()
    setCaffeineDisplay(hs.caffeinate.toggle("displayIdle"))
end

if caffeine then
    caffeine:setClickCallback(caffeineClicked)
    setCaffeineDisplay(hs.caffeinate.get("displayIdle"))
end
  1. Automatically switching audio output based on connected devices:
function audioDeviceChanged()
    local current = hs.audiodevice.current()
    if current.name:match("AirPods") then
        hs.audiodevice.findDeviceByName("AirPods"):setDefaultOutputDevice()
    elseif current.name:match("Built-in") then
        hs.audiodevice.findDeviceByName("Built-in Output"):setDefaultOutputDevice()
    end
end

hs.audiodevice.watcher.setCallback(audioDeviceChanged)
hs.audiodevice.watcher.start()

Getting Started

  1. Install Hammerspoon from https://www.hammerspoon.org/ or via Homebrew:

    brew install --cask hammerspoon
    
  2. Create a configuration file at ~/.hammerspoon/init.lua

  3. Add your Lua scripts to the init.lua file

  4. Reload the Hammerspoon configuration by clicking the menu bar icon and selecting "Reload Config"

  5. Start automating your macOS experience!

Competitor Comparisons

23,088

A tiling window manager for macOS based on binary space partitioning

Pros of yabai

  • Focused specifically on window management and tiling
  • Offers more advanced tiling features and layouts
  • Faster and more lightweight for window operations

Cons of yabai

  • Requires disabling System Integrity Protection (SIP) for full functionality
  • Less versatile than Hammerspoon, primarily focused on window management
  • Steeper learning curve for configuration

Code Comparison

yabai configuration example:

yabai -m config layout bsp
yabai -m config top_padding 10
yabai -m config left_padding 10
yabai -m config right_padding 10
yabai -m config bottom_padding 10

Hammerspoon window management example:

hs.hotkey.bind({"cmd", "alt", "ctrl"}, "Left", function()
  local win = hs.window.focusedWindow()
  local f = win:frame()
  local screen = win:screen()
  local max = screen:frame()
  f.x = max.x
  f.y = max.y
  f.w = max.w / 2
  f.h = max.h
  win:setFrame(f)
end)

Hammerspoon offers a more general-purpose scripting environment for macOS automation, while yabai specializes in advanced window management and tiling. Yabai provides more powerful tiling features but requires more setup and potential security trade-offs. Hammerspoon is more versatile and easier to get started with but may be less efficient for complex window layouts.

8,144

Hide menu bar icons on macOS

Pros of Dozer

  • Focused, single-purpose tool for hiding menu bar icons
  • Lightweight and easy to use with a simple interface
  • Free and open-source

Cons of Dozer

  • Limited functionality compared to Hammerspoon's extensive capabilities
  • Less customizable and extensible
  • Smaller community and fewer updates

Code Comparison

Dozer (Objective-C):

- (void)toggleHidden {
    [self setHidden:![self isHidden]];
    [self updateStatusItem];
}

Hammerspoon (Lua):

function toggleHidden()
    local isHidden = hs.menubar.isHidden()
    hs.menubar.setHidden(not isHidden)
    updateStatusItem()
end

While both projects deal with menu bar management, their scopes and implementations differ significantly. Dozer is a specialized tool for hiding menu bar icons, written in Objective-C. Hammerspoon, on the other hand, is a powerful automation tool for macOS, using Lua for scripting and offering a wide range of functionalities beyond menu bar management.

Dozer provides a straightforward solution for users who only need to manage menu bar clutter, while Hammerspoon offers a more comprehensive set of tools for power users looking to automate various aspects of their macOS experience.

14,622

Automatic tiling window manager for macOS à la xmonad.

Pros of Amethyst

  • Focused specifically on window management, making it simpler to use for this purpose
  • Provides a more streamlined, out-of-the-box experience for tiling windows
  • Lighter weight and less resource-intensive than Hammerspoon

Cons of Amethyst

  • Less flexible and customizable compared to Hammerspoon's extensive scripting capabilities
  • Limited to window management tasks, while Hammerspoon offers a broader range of system automation features
  • Smaller community and fewer extensions/plugins available

Code Comparison

Amethyst configuration (in JSON):

{
  "layouts": ["tall", "wide", "fullscreen", "column"],
  "mod1": ["option", "shift"],
  "mod2": ["option", "shift", "control"]
}

Hammerspoon configuration (in Lua):

hs.hotkey.bind({"cmd", "alt", "ctrl"}, "Left", function()
  local win = hs.window.focusedWindow()
  local f = win:frame()
  local screen = win:screen()
  local max = screen:frame()
  f.x = max.x
  f.y = max.y
  f.w = max.w / 2
  f.h = max.h
  win:setFrame(f)
end)

This comparison highlights Amethyst's simplicity for window management tasks, while showcasing Hammerspoon's flexibility for more complex automation through its Lua scripting capabilities.

25,585

Move and resize windows on macOS with keyboard shortcuts and snap areas

Pros of Rectangle

  • Simpler and more focused on window management
  • Easier to set up and use for beginners
  • Lightweight with minimal system resource usage

Cons of Rectangle

  • Less customizable and extensible
  • Limited to window management functionality
  • Fewer advanced features for power users

Code Comparison

Rectangle (Swift):

func moveWindowToCenter() {
    if let screen = NSScreen.main {
        let visibleFrame = screen.visibleFrame
        let newFrame = NSRect(x: visibleFrame.midX - frame.width / 2,
                              y: visibleFrame.midY - frame.height / 2,
                              width: frame.width,
                              height: frame.height)
        setFrame(newFrame, display: true)
    }
}

Hammerspoon (Lua):

function centerWindow()
    local win = hs.window.focusedWindow()
    local f = win:frame()
    local screen = win:screen()
    local max = screen:frame()

    f.x = max.x + (max.w / 2) - (f.w / 2)
    f.y = max.y + (max.h / 2) - (f.h / 2)
    win:setFrame(f)
end

Summary

Rectangle is a more straightforward window management tool, ideal for users seeking a simple solution. Hammerspoon offers greater flexibility and customization but requires more setup and learning. The code comparison shows Rectangle using Swift for macOS-specific functionality, while Hammerspoon employs Lua for a more versatile scripting approach.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Hammerspoon

CI codecov.io Downloads current release Downloads all releases Latest tag Latest release

Discord: Click to join

What is Hammerspoon?

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. With these, you can write Lua scripts to control many aspects of your OS X environment.

How do I install it?

Manually

  • Download the latest release
  • Drag Hammerspoon.app from your Downloads folder to Applications

Homebrew

  • brew install hammerspoon --cask

What next?

Out of the box, Hammerspoon does nothing - you will need to create ~/.hammerspoon/init.lua and fill it with useful code. There are several resources which can help you:

What is the history of the project?

Hammerspoon is a fork of Mjolnir by Steven Degutis. Mjolnir aims to be a very minimal application, with its extensions hosted externally and managed using a Lua package manager. We wanted to provide a more integrated experience.

What is the future of the project?

Our intentions for Hammerspoon broadly fall into these categories:

  • Ever wider coverage of system APIs in Extensions
  • Tighter integration between extensions
  • Smoother user experience