creating-hammerspoon-scripts

Create macOS automation scripts using Hammerspoon's Lua API for window management, hotkeys, and event watchers.

Updated Dec 4, 2025

Search Tags:#lua #macos automation #window management #hammerspoon #init.lua #hotkeys #event watchers

Ready to run

npx skills add https://github.com/dallascrilley/dowser --skill creating-hammerspoon-scripts-dallascrilley

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: creating-hammerspoon-scripts
Source: https://github.com/dallascrilley/dowser/tree/main/skills/creating-hammerspoon-scripts
Command: npx skills add https://github.com/dallascrilley/dowser --skill creating-hammerspoon-scripts-dallascrilley

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve? Writing Hammerspoon configurations from scratch is error-prone: watchers silently stop due to Lua garbage collection, config changes don't apply without reload, and windows end up under the menubar. This Skill provides proven patterns, templates, and troubleshooting guidance that prevent these common pitfalls. ## Core Features & Use Cases - Window Management Patterns: Ready-to-use Lua code for halves, quarters, maximize, center, and multi-monitor movement using hs.window and hs.screen. - Hotkey & Modal Interfaces: Global hotkey bindings, modal app launchers, and window management modes with proper exit handling. - Event Watchers: Correctly-scoped (global variable) patterns for pathwatcher, wifi, application, and USB watchers, plus auto-reload configuration. - Use Case: A user wants a keyboard-driven window tiling setup on macOS. The Skill provides a starter init.lua, window-snapping snippets, and a reload hotkey so the config works immediately and iterates safely. ## Quick Start Ask the assistant to create a Hammerspoon init.lua config with window management hotkeys and an auto-reload watcher.

Frequently Asked Questions about creating-hammerspoon-scripts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I create a Hammerspoon window management script?▼

Use hs.window.focusedWindow() to get the active window, then call win:setFrame() with coordinates derived from screen:frame(). Bind the function to a hotkey with hs.hotkey.bind(), and always check that the focused window is not nil before manipulating it.

How do I set up hotkeys in Hammerspoon?▼

Call hs.hotkey.bind() with a modifier table like {"cmd", "alt"}, a key name, and a callback function. For multi-step workflows, use hs.hotkey.modal.new() to create a modal mode, and always call modal:exit() after each action.

Why does my Hammerspoon watcher stop working after a few minutes?▼

Watchers stored in local variables get garbage collected by Lua once init.lua finishes executing. Store every watcher (pathwatcher, wifi, application, USB) in a global variable by removing the local keyword so it persists for the session.

Why don't my Hammerspoon config changes take effect?▼

Hammerspoon only reads init.lua at launch or on explicit reload via hs.reload(). Add a reload hotkey or set up an hs.pathwatcher on ~/.hammerspoon/ that calls hs.reload() automatically when Lua files change.

Does Hammerspoon work on macOS for multi-monitor window movement?▼

Yes, Hammerspoon supports multi-monitor setups on macOS 11.0+. Use win:screen():next() to get the next display and win:moveToScreen() to move the window, and use screen:frame() rather than fullFrame() to avoid the menubar and dock.