Skip to content

README.md

Latest commit

 

History

History
95 lines (65 loc) · 3.02 KB

README.md

File metadata and controls

95 lines (65 loc) · 3.02 KB
Raw

Hammerspoon — Swap Displays

A small Hammerspoon script for macOS that swaps all windows between two displays with a single hotkey, preserving their relative positions and sizes.

What it's for

You work with two displays and want to flip what's shown on each — for example moving your IDE from the left screen to the right one, and your browser the other way — without dragging every window by hand.

With this script: Cmd + Alt + S → all windows swap displays instantly.

Requirements

  • macOS (tested on Apple Silicon, should work on Intel)
  • Hammerspoon installed 
    brew install --cask hammerspoon
    Or direct download: https://github.com/Hammerspoon/hammerspoon/releases
  • Accessibility: on first launch, macOS will ask you to allow Hammerspoon in System Settings → Privacy & Security → Accessibility.

Installation

Option 1 — Single script (simplest)

  1. Copy the contents of swap-displays.lua into your ~/.hammerspoon/init.lua:

    mkdir -p ~/.hammerspoon
cp swap-displays.lua ~/.hammerspoon/init.lua

  2. Reload the Hammerspoon config: click the Hammerspoon icon in the menu bar → Reload Config.

  3. You should see the Hammerspoon loaded alert.

Option 2 — Add to an existing init.lua

If you already have a Hammerspoon config, simply append the contents of swap-displays.lua to your existing ~/.hammerspoon/init.lua (removing the hs.alert.show("Hammerspoon loaded") line if you already have one).

Usage

Press Cmd + Alt + S (⌘ + ⌥ + S).

  • All windows from display A move to display B
  • All windows from display B move to display A
  • Their relative position and size are preserved (a window taking up the right half of its display will take up the right half of the new one)
  • An alert confirms how many windows were moved

Customization

Change the hotkey

At the end of the script, edit this line:

hs.hotkey.bind({"cmd", "alt"}, "S", swapDisplays)

Examples:

  • Cmd + Shift + W → hs.hotkey.bind({"cmd", "shift"}, "W", swapDisplays)
  • Ctrl + Option + Space → hs.hotkey.bind({"ctrl", "alt"}, "space", swapDisplays)

Available modifiers: cmd, alt (option), ctrl, shift.

Support more than 2 displays

This script handles 2 displays. For 3+ displays the logic would need to be adapted (circular rotation, target display selection, etc.) — PRs welcome.

Troubleshooting

The hotkey does nothing

  • Check that Hammerspoon is running (icon in the menu bar)
  • Check that Accessibility is enabled for Hammerspoon
  • Open the Hammerspoon console (icon → Console) to see errors

"Two displays are required to swap"

  • Only one display is connected. Plug in a second display and try again.

Some windows don't move

  • The script ignores non-standard windows (fullscreen Finder, dedicated Spaces, etc.) and minimized windows. This is intentional.

License

MIT — do whatever you want with it.