Hammerspoon Space Manager

An opinionated Hammerspoon module for moving the focused window to a numbered macOS Space or an adjacent display.

Space Manager dynamically reads the regular Spaces attached to each display, filters out full-screen Spaces, and assigns global shortcut numbers using this screen order:

1. Primary display
2. Displays to the left of primary
3. Displays to the right of primary
4. Vertically arranged displays

Features

• Move the focused window to regular Spaces 1 through 9.
• Move the focused window to the adjacent display on the left or right.
• Recalculate Space numbering whenever a shortcut is pressed.
• Detect unavailable system hotkeys and report understandable errors.
• Support the changed private Space-movement operation in macOS 26 Tahoe.
• Verify numbered-Space movement before displaying a success alert.

Requirements

• macOS with Hammerspoon installed.
• Accessibility permission for Hammerspoon.
• Displays have separate Spaces enabled in System Settings → Desktop & Dock → Mission Control when using multiple displays.
• Apple Command Line Tools on macOS 26 or newer. The Tahoe helper is compiled locally with xcrun clang when first needed.

The numbered-Space implementation relies on private macOS APIs. Apple may change or remove them in a future macOS release.

Installation

Clone the repository into the Hammerspoon configuration directory:

git clone <repository-url> ~/.hammerspoon/space-manager

Add this loader to ~/.hammerspoon/init.lua:

local moduleDirectory = hs.configdir .. "/space-manager"
local spaceManager = dofile(moduleDirectory .. "/space_manager.lua")

spaceManager.start()

Reload the Hammerspoon configuration from its menu.

Default shortcuts

Shortcut	Action
Control+Option+1 through Control+Option+9	Move the focused window to that numbered regular Space.
Control+Option+,	Move the focused window to the adjacent display on the left.
Control+Option+.	Move the focused window to the adjacent display on the right.

Configuration

Pass overrides to start to change the bindings or helper cache path:

spaceManager.start({
  modifiers = { "ctrl", "option" },
  moveLeftKey = ",",
  moveRightKey = ".",
  maxNumberedSpace = 9,
  alertDuration = 1.5,
  tahoeHelperPath = "/tmp/hammerspoon-space-manager-move",
})

The helper source path is discovered relative to space_manager.lua. It may also be overridden with tahoeHelperSource for a nonstandard installation.

Limitations

• Full-screen and tiled windows are not supported by the movement contract.
• Full-screen Spaces are excluded from shortcut numbering.
• Screen ordering is intentionally opinionated; unusual arrangements may require adapting orderedScreens.
• The macOS 26 helper uses undocumented SkyLight interfaces and is tested against macOS 26.5.2.

See the Space Manager guide for implementation details and the validation checklist.

Security and privacy

Space Manager runs locally and does not make network requests. The Tahoe helper receives only numeric window and Space identifiers. See SECURITY.md for reporting security issues.

Acknowledgements

The macOS 26 symbol lookup and bridged Space operation in native/space_move_helper.m are adapted from yabai. The original MIT copyright and permission notice are retained in that source file.

License

This repository is available under the MIT License. Bundled third-party-derived code retains its original notice.