Hammerspoon Window Management Guide: macOS Layouts and Snapping with Lua

Hammerspoon Lua guide for macOS window management. Build layouts, window snapping, and app-specific rules 闁?replace 5 tools with one keyboard-driven script.

This guide walks you through everything you need to get productive with Hammerspoon as part of the System track on Toolsmith. Whether you are a first-time user or looking to tighten an existing setup, you will find concrete steps and field-tested tips below.

What you will learn

• How to install and configure Hammerspoon from a clean state.
• The core concepts and mental model behind Hammerspoon.
• Practical workflows you can apply the same day.
• Advanced tweaks and pro tips used by power users.

Why Hammerspoon

Hammerspoon earns its place in a power-user toolkit because it removes friction from work you already do every day. Instead of fighting your tooling, you spend that energy on the actual task. The setup below keeps things minimal and reproducible so you can rebuild it on any machine in minutes.

Prerequisites

Make sure you have a terminal you are comfortable in and a package manager available. On macOS we use Homebrew; on Linux use your distro package manager; on Windows use Winget or scoop. Then install the tool:

# Install Hammerspoon
brew install --cask hammerspoon

Step-by-step setup

1. Install. Run the command above and confirm it works with the tool's version flag.
2. Configure. Create a small config file with sane defaults, then layer in the options that matter to your workflow.
3. Integrate. Wire Hammerspoon into your shell, editor, or launcher so it is one keystroke away.
4. Verify. Run through a real task end-to-end to confirm the setup behaves as expected.

Pro tips

• Start with a tiny config and grow it 闁?a 20-line setup beats a 200-line one you never touch.
• Keep your configuration in version control so any machine can be restored instantly.
• Learn the three commands you use daily before exploring the long tail of features.

Common pitfalls

Most issues come from mismatched versions or a config path that is not where the tool expects it. When something misbehaves, check the version, the config location, and any error output before changing settings blindly.

Final thoughts

Hammerspoon is the kind of tool that feels optional until you rely on it 闁?then it becomes essential. Spend an hour setting it up well and it will pay you back for years. Explore the related tutorials below to go deeper.