Master macOS Automation with Hammerspoon

Master macOS Automation with Hammerspoon: Your Gateway to a Smarter Workflow

Hammerspoon is a revolutionary desktop automation tool for macOS that bridges system-level APIs with a flexible Lua scripting engine. This allows you to exert powerful control over your system by writing custom Lua scripts. Whether you're looking to simplify repetitive tasks, manage your windows with precision, or react to system events, Hammerspoon provides the framework to build your ideal workflow.

Getting Started: Your First Steps with Hammerspoon

To begin your journey with Hammerspoon, download the latest release and install it in your Applications folder. Running the application for the first time will prompt you to grant necessary Accessibility access. Once set up, you can access Hammerspoon's configuration by clicking its menu bar icon and selecting 'Open Config'. For comprehensive API documentation, explore the official Hammerspoon API docs to discover the vast array of extensions and functions at your disposal.

The Power of Lua Scripting

Lua is a lightweight, yet powerful programming language perfect for scripting complex automation. If you're new to Lua, a quick tutorial like 'Learn Lua in Y minutes' is a great starting point.

Core Functionality and Practical Examples:

1. Hello World & Notifications: Begin with the basics. Hammerspoon allows you to bind hotkeys to trigger actions. A simple example involves binding a key combination to display a "Hello World!" notification using hs.alert.show() or macOS native notifications via hs.notify.new().

hs.hotkey.bind({"cmd", "alt", "ctrl"}, "W", function()
  hs.alert.show("Hello World!")
end)

2. Spoons: Pre-made Plugins: Enhance Hammerspoon's capabilities with 'Spoons' – pre-made plugins that extend its functionality. For instance, the 'AClock' Spoon can be installed and used to toggle its display with a custom hotkey.

hs.loadSpoon("AClock")
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "C", function()
  spoon.AClock:toggleShow()
end)

3. Window Management: Take control of your windows. Hammerspoon excels at manipulating window frames. Move windows precisely, resize them to fill halves of your screen, or create complex multi-window layouts using hs.layout. You can even bind keys for intuitive window movement inspired by Nethack.

-- Move focused window 10 pixels left
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "H", function()
  local win = hs.window.focusedWindow()
  local f = win:frame()
  f.x = f.x - 10
  win:setFrame(f)
end)

-- Move focused window to left half of 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)

4. Window Filters: Contextualize your automation with hs.window.filter. This module allows you to apply rules based on application, window properties, or even custom predicates, enabling precise control over when your scripts run. A practical use case is cleaning the pasteboard when pasting from Safari into Messages to prevent unwanted link expansion.

5. Configuration Reloading: Streamline your development process by automatically reloading your Hammerspoon configuration. You can bind a hotkey for manual reloads (hs.reload()) or use hs.pathwatcher to monitor your config directory for changes and trigger automatic reloads.

6. Interacting with Application Menus: Automate interactions with application menus. Hammerspoon can find and select menu items, allowing you to control application features, such as cycling through Safari's User Agent strings.

7. Menubar Items & System Events: Create custom menubar items using hs.menubar to display status or trigger actions. You can also react to system events like application activations (hs.application.watcher), Wi-Fi network changes (hs.wifi.watcher), or USB device connections (hs.usb.watcher).

8. Advanced Automation: Hammerspoon's capabilities extend to defeating paste blocking, running AppleScript, controlling media applications like iTunes and Spotify, drawing on the screen for visual feedback, sending iMessages/SMS, and even automating Hammerspoon itself via URLs.

Hammerspoon is a testament to the power of open-source software, offering unparalleled flexibility for Mac users to customize and automate their digital lives. Dive in, experiment with the examples, and discover how Hammerspoon can transform your daily computing experience.