Spacepal docs

Install Spacepal, grant two permissions, and press ⌥Tab to see every Space. This page covers setup, shortcuts, automation and fixes for common problems.

Setup

Move Spacepal to your Applications folder and open it. Its icon and the name of the current Space appear in the menu bar.
Grant Accessibility in System Settings, Privacy & Security. Spacepal needs it to switch Spaces and move windows.
Grant Screen Recording in the same place. Spacepal needs it for the Space previews. Previews never leave your Mac (see Privacy).
In System Settings, Desktop & Dock, turn off Automatically rearrange Spaces based on most recent use. Otherwise macOS reorders your Spaces and the numbers stop matching.

Settings, Setup shows each of these with a green check once it is done.

Keyboard shortcuts

Shortcut	Action
`⌥Tab`	Open the overview (changeable in Settings)
`⌃⌥1` … `⌃⌥0`	Go to Space 1 to 10. Press again to go back to where you were.
`⌃⌥⇧1` … `⌃⌥⇧0`	Move the front window to Space 1 to 10
`⌃⌥←` `⌃⌥→`	Previous or next Space (add `⇧` to take the window along)
`⌃⌥↑` `⌃⌥↓`	Up or down a row, when a grid column count is set in Settings
⌃⌥`	Last Space you were on
`⌃⌥F`	Search windows on all Spaces. Return goes to the window, ⌘Return brings it here.
`⌃⌥W`	Windows on this Space
`⌃⌥L`	Open an app on this Space
`⌃⌥/`	Show or hide the scratchpad app
`⌃⌥M`, then a letter	Mark the front window
`⌃⌥'`, then a letter	Jump to a marked window

URL scheme

Every action has a spacepal:// link, so you can trigger it from Shortcuts, Raycast, Alfred, BetterTouchTool, a Stream Deck or a terminal (open "spacepal://next").

Link	Does
`spacepal://switch/3`, `spacepal://switch/Mail`	Go to a Space by number or name
`spacepal://next`, `previous`, `back`, `up`, `down`	Step between Spaces
`spacepal://overview`	Open the overview
`spacepal://move-window/4`, `move-window/next`	Move the front window
`spacepal://rename/current?name=Design`	Rename a Space
`spacepal://note/2?text=Invoice%20due`	Set a Space's note
`spacepal://profile/Work`, `template/Developer`	Apply a profile or template
`spacepal://save-layout`, `restore-layout`, `eject`	Window layouts, and getting ready to unplug displays
`spacepal://windows`, `windows/all`, `launcher`, `scratchpad`	Open the panels
`spacepal://minimize-all`, `undo-minimize`, `save-space`	Clear a Space, or save and close it
`spacepal://add-desktop`, `remove-desktop/current`	Add or remove a desktop (direct version only)
`spacepal://settings`, `diagnostics`	Open Settings, or copy a diagnostics report

AppleScript

tell application "Spacepal"
    get current space name
    switch to space "Mail"
    rename space 3 to "Design"
end tell

Also available: current space number, space names, next space, previous space, last space, show overview and move window to space. Open Spacepal in Script Editor's library for the full dictionary.

Raycast and other tools

Spacepal writes the current Spaces, their names and their apps to state.json in its Application Support folder whenever something changes. The Raycast extension reads it, and so can SketchyBar, Hammerspoon or your own scripts. An optional local HTTP API (Settings, General) listens on 127.0.0.1:57301 with a token; it is off by default.

Troubleshooting

Switching plays the slide animation, or does nothing

Check that Accessibility is granted, then open Settings, Setup. If it still fails, turn on "Switch to Desktop 1-4" in System Settings, Keyboard, Keyboard Shortcuts, Mission Control; Spacepal falls back to those.

Space numbers or names are on the wrong desktops

Turn off Automatically rearrange Spaces based on most recent use in Desktop & Dock. Names are tied to each Space, not to its position, so they come back once the order is stable.

Previews are blank or old

Grant Screen Recording, then quit and reopen Spacepal. A preview is refreshed each time you visit that Space.

The menu bar item is missing

On MacBooks with a notch, a full menu bar hides items under the notch. Spacepal moves itself to the left of other items on first launch. If it is still hidden, choose the dots or icon-only style in Settings, Appearance, or remove a few other menu bar items.

Report a problem

Open spacepal://diagnostics, which copies a report to the clipboard, and paste it into an email to support@getspacepal.com.

Written by Dan Bayer, developer of Spacepal. Last updated 2026-10-27.