Hammerspoon Window Management Guide: macOS Layouts and Snapping with Lua

Why Hammerspoon for Windows?

Hammerspoon is a macOS automation tool that uses Lua scripts to control windows, apps, and system events. For window management, it's more powerful than any dedicated app because you write exactly the rules you need.

This guide builds a complete window management system: edge snapping, grid layouts, multi-monitor support, and custom shortcuts — all in pure Lua.

• Snap windows to screen edges like Windows 7 Snap
• Move windows between monitors with keyboard shortcuts
• Save and restore window layouts per app per display
• Build custom grids for non-standard layouts

Installation & init.lua

Install Hammerspoon from hammerspoon.org or via Homebrew:

brew install --cask hammerspoon

• macOS 12 or later
• Accessibility permissions (Hammerspoon will prompt on first launch)
• Basic Lua knowledge helpful but not required
• Multiple monitors optional but recommended for full benefit

Launch Hammerspoon, grant accessibility permissions in System Settings → Privacy & Security, then open the config file:

~/.hammerspoon/init.lua

Window Layouts with hs.window

The hs.window module is your primary tool. Start with edge snapping — the most useful window management feature.

local wf = hs.window.filter
local half = hs.layout.left50
-- Snap to left half
hs.hotkey.bind({"cmd","alt"}, "left", function()
local win = hs.window.focusedWindow()
local f = win:frame()
local screen = win:screen():frame()
f.x = screen.x
f.y = screen.y
f.w = screen.w / 2
f.h = screen.h
win:setFrame(f)
end)
-- Snap to right half
hs.hotkey.bind({"cmd","alt"}, "right", function()
local win = hs.window.focusedWindow()
local f = win:frame()
local screen = win:screen():frame()
f.x = screen.x + screen.w / 2
f.y = screen.y
f.w = screen.w / 2
f.h = screen.h
win:setFrame(f)
end)

Automated Snapping & Grids

For multi-monitor setups, moving windows between displays is essential. Add full-screen toggle and monitor switching:

• Cmd+Alt+Left/Right — snap to screen halves
• Cmd+Alt+Up — maximize window
• Cmd+Alt+Down — minimize/restore
• Ctrl+Alt+Left/Right — move window to previous/next monitor

Save and restore layouts with hs.layout:

local layout = {
{"Safari", nil, display1, hs.layout.left50, nil, nil},
{"Terminal", nil, display1, hs.layout.right50, nil, nil},
{"Slack", nil, display2, hs.layout.maximized, nil, nil},
}
hs.hotkey.bind({"cmd","alt"}, "0", function()
hs.layout.apply(layout)
end)

Multi-Monitor Layout Logic

Go beyond basic snapping with these advanced techniques:

• Use hs.grid for a visual grid overlay — press a hotkey, see a grid, type two characters to place the window
• Build app-specific layouts: different window positions for code editors vs browsers
• Watch for display changes with hs.screen.watcher and auto-rearrange
• Create a hyper key with Karabiner + Hammerspoon for global shortcuts (see [[Karabiner-Elements Tutorial]])

Layout Bugs & Edge Cases

Window management issues and solutions:

• Windows not moving? Check accessibility permissions — System Settings → Privacy → Accessibility → Hammerspoon
• Wrong screen coordinates? Use hs.screen.allScreens() to debug layout
• Animation too slow? Set hs.window.animationDuration = 0
• App not found by name? Use hs.application.runningApplications() to find exact bundle IDs

Your Window Workflow

Your window management system is ready. Next steps:

• Build an app switcher and menu bar widgets (see [[Hammerspoon App Switcher and Menu Bar]])
• Add clipboard management (see [[Hammerspoon Clipboard Manager]])
• Create automation triggers like WiFi-based actions (see [[Hammerspoon Automation Cookbook]])
• Customize the menu bar (see [[Hammerspoon Menu Bar Customization]])