Automate Your Mac with Hammerspoon — No Coding Needed

// Before you start

What you need

A Mac running macOS 10.15 or later
Admin access to install apps
Homebrew installed (brew.sh) — or willingness to download manually
Comfort opening a text editor like TextEdit or VS Code

Step 1 of 5

Install Hammerspoon

2 min

This installs the Hammerspoon app on your Mac. It sits quietly in your menu bar and does nothing until you give it a script. We use Homebrew here because it is one command. If you do not have Homebrew, go to hammerspoon.org, download the latest release zip, unzip it, and drag Hammerspoon.app to your Applications folder instead.

Terminal · mac

$ brew install hammerspoon --cask

What you should see

==> Installing Cask hammerspoon ==> Moving App 'Hammerspoon.app' to '/Applications/Hammerspoon.app'

This might happen

Homebrew says 'command not found'

Install Homebrew first by running: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" — or just download Hammerspoon manually from hammerspoon.org/releases

Step 2 of 5

Launch Hammerspoon and grant permissions

2 min

Open Hammerspoon from your Applications folder. macOS will ask you to grant Accessibility permissions — this is how Hammerspoon can move windows and detect hotkeys. Without this, almost nothing works. Go to System Settings → Privacy & Security → Accessibility, find Hammerspoon, and toggle it on. You may need to click the lock icon and enter your password first.

Terminal · mac

$ open /Applications/Hammerspoon.app

What you should see

A small hammer icon appears in your Mac menu bar at the top right of the screen.

This might happen

Hammerspoon shows a warning that Accessibility is not enabled

Click 'Enable Accessibility' in the Hammerspoon alert, which takes you directly to System Settings. Toggle Hammerspoon on. If the toggle is greyed out, click the padlock icon at the bottom of the window first.

Step 3 of 5

Create your config file

1 min

Hammerspoon reads all its instructions from a single file called init.lua stored in a hidden folder in your home directory. This command creates that folder and an empty file. You only need to do this once.

Terminal · mac

$ mkdir -p ~/.hammerspoon && touch ~/.hammerspoon/init.lua

What you should see

No output means success. The file now exists.

Step 4 of 5

Add a working automation — a window snap hotkey

3 min

This command writes a real, useful script into your config file. It sets up two hotkeys: pressing Ctrl+Alt+Left snaps the front window to the left half of your screen, and Ctrl+Alt+Right snaps it to the right half. This is the most common Hammerspoon starter use-case. The command below overwrites the empty file you just created — safe to run.

Terminal · mac

$ cat > ~/.hammerspoon/init.lua << 'EOF'

$ -- Snap focused window to left half

$ hs.hotkey.bind({"ctrl", "alt"}, "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)

$ -- Snap focused window to right half

$ hs.hotkey.bind({"ctrl", "alt"}, "Right", function()

$ local win = hs.window.focusedWindow()

$ local f = win:frame()

$ local screen = win:screen()

$ local max = screen:frame()

$ f.x = max.x + (max.w / 2)

$ f.y = max.y

$ f.w = max.w / 2

$ f.h = max.h

$ win:setFrame(f)

$ end)

$ hs.alert.show("Hammerspoon loaded!")

$ EOF

What you should see

No terminal output. The file ~/.hammerspoon/init.lua now contains the script.

This might happen

The hotkeys Ctrl+Alt+Left or Right conflict with another app or macOS shortcut

Open ~/.hammerspoon/init.lua in any text editor and change "ctrl", "alt" to another combination like "cmd", "alt". Save the file, then reload (see next step).

Step 5 of 5

Reload Hammerspoon to activate your script

1 min

Hammerspoon does not pick up changes to init.lua automatically. You need to tell it to reload. Click the hammer icon in your menu bar and choose 'Reload Config'. A grey banner saying 'Hammerspoon loaded!' will flash on your screen — that confirms the script is active. Now click any open window and press Ctrl+Alt+Left or Right to snap it.

Terminal · mac

$ open hammerspoon://reload

What you should see

A grey 'Hammerspoon loaded!' alert flashes briefly in the centre of your screen.

This might happen

No alert appears and the hotkeys do nothing

Click the hammer menu bar icon → 'Open Console'. Any errors in your script appear here in red. The most common cause is a typo introduced when editing the file. Compare your file carefully against the script in step 4.

// Status

cooked. baked. worked.

Hammerspoon is installed and running. Pressing Ctrl+Alt+Left snaps your front window to the left half of the screen; Ctrl+Alt+Right snaps it to the right. You have a working config file you can expand with more automations from the Hammerspoon sample library.

// the honest bit

The honest part

Hammerspoon is genuinely powerful but everything beyond this starter example requires writing or copy-pasting Lua code. The official Getting Started guide (hammerspoon.org/go/start) and the Sample Configurations page have hundreds of ready-made snippets you can paste directly into init.lua — you do not need to write them from scratch. However, customising them to your exact needs will eventually require reading and editing code. This tool rewards curiosity but has a real learning curve past the basics.