hammerspoon

Configure Hammerspoon automation for macOS window management and app switching.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/indexzero/dotvibes --skill hammerspoon-indexzero
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hammerspoon
Source: https://github.com/indexzero/dotvibes/tree/main/vlurp/whilp/dotfiles/.claude/skills/hammerspoon
Command: npx skills add https://github.com/indexzero/dotvibes --skill hammerspoon-indexzero

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Configure and manage Hammerspoon automation for macOS, including window management, app launching, and window switching.

Core Features & Use Cases

  • Core infrastructure modules (e.g., hyper-key.lua, config-watch.lua, init.lua) for modular automation.
  • Window management: grid-based layouts, dynamic adaptation to screen type, and hotkeys.
  • App launcher and switching: quick-switch and window-switcher integrations.

Quick Start

Review and extend your init.lua to enable new bindings, test reloads with hotkeys, and verify window layouts across different screen types.

Frequently Asked Questions about hammerspoon

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

FAQPage Schema
How do I set up window management with Hammerspoon on macOS?

Window management in Hammerspoon uses grid-based layouts defined in Lua configuration files. Create a grid.lua module to map hotkeys to window positions, then load it in init.lua. Hammerspoon adapts layouts dynamically to screen type—normal, ultrawide, or vertical—so you define positions once and they adjust automatically across displays.

Can I create custom keybindings and a hyper key with Hammerspoon?

Yes. Hammerspoon lets you define hyper and super modifier keys through a hyper-key.lua module, then bind them to actions like app launching or window switching. Use hs.hotkey.bind() to map key combinations to Lua functions, and enable config reloading with hotkeys to test changes instantly.

How do I automate app launching and window switching in Hammerspoon?

Create a unified switcher using Hammerspoon's window-switcher and app-launcher modules with fuzzy matching. Bind a hotkey to trigger the switcher, which filters open apps and windows by keystroke, letting you jump between apps without clicking. Store launcher and switcher logic in separate Lua modules for modularity.

What's the best way to organize a Hammerspoon configuration across multiple files?

Use a modular structure with separate Lua files for distinct tasks: hyper-key.lua for modifier definitions, grid.lua for window layouts, config-watch.lua for auto-reloading, and app-launcher.lua for quick-switch logic. Load all modules from init.lua and enable file watching so changes reload automatically without restarting.

Does Hammerspoon support command-line interaction for automation?

Yes. Hammerspoon includes hs.ipc.cliInstall() which sets up a CLI so you can trigger Hammerspoon functions from the terminal. This lets you integrate Hammerspoon automation into shell scripts and external workflows without manual hotkey presses.

How do I reload Hammerspoon configuration while testing changes?

Use config-watch.lua to monitor your ~/.config/hammerspoon directory for file changes and auto-reload when you save. Alternatively, bind a hotkey to hs.reload() to manually trigger reloads. Both approaches let you test keybindings and window layouts instantly without restarting the application.