SpacePigeon is a native macOS app (powered by Hammerspoon) that lets you define workspaces — which apps open, which desktop spaces they go to, and how windows are arranged.

Effortlessly transition between workflows. SpacePigeon instantly orchestrates your applications, windows, and displays into the perfect environment for any task with a single click or hotkey.

• 🚀 One-Click Setup: Installs everything automatically. If you don't have Hammerspoon, SpacePigeon will download and install it for you.
• 🎨 Visual Configuration: A full native UI to manage your workspaces. No need to touch Lua code manually.
• 🖥 Multi-Monitor Support: Configure spaces and app layouts for both your Main and Secondary monitors.
• ⚡️ Smart App Launching:
  • Browser Mode: Launch browsers with specific startup URLs.
  • Deep Links: Open apps to specific content (e.g., Notion pages, Spotify playlists, or custom URL schemes).
• 🪟 Window Management: Automatically position windows:
  • Maximize
  • Split Left / Split Right
• ⌨️ Hotkeys: Bind global hotkeys to trigger specific presets instantly.
• 📑 Presets: Create multiple workspace states (e.g., "Work", "Chill", "Stream") and switch between them.

1. Go to the Releases page.
2. Download SpacePigeon.zip.
3. Unzip the file.
4. Run SpacePigeon.app.
5. Click "Install & Reload".

If macOS prevents the app from opening because it "cannot be verified":

1. Click Done (or Cancel) on the warning dialog.
2. Open System Settings.
3. Go to Privacy & Security.
4. Scroll down to the Security section.
5. Click the Open Anyway button next to "SpacePigeon.app was blocked...".
6. Click Open in the final confirmation.

(This is required because the app is open-source and not signed with a paid Apple Developer certificate).

If you prefer to build it yourself:

1. Clone the repository:

   git clone https://github.com/yourusername/spacepigeon.git
   cd spacepigeon

2. Run the build script:

   ./build_app.sh

3. Open the generated app:

   open SpacePigeon.app

Launch SpacePigeon and click "Edit Config" to open the configuration editor.

Manage your workspace layouts here.

• Spaces: Define how many Desktop Spaces you want on your Main and Secondary monitors.
• Applications Layout: Add apps to the list.
  • Name: The application name (e.g., "Safari", "Terminal").
  • Monitor: Choose "Main" or "2nd".
  • Space: The space number (1-based index) on that monitor.
  • Position: Maximize, Left, or Right.
  • Gear Icon ⚙️: Access advanced settings:
    • Is this a Browser?: Check this to enable startup URL support.
    • URL: Enter a web URL (for browsers) or a deep link (for other apps) to open on launch.

Set up global hotkeys to trigger your presets.

• Modifiers: cmd, alt, ctrl, shift (comma separated).
• Key: The key to press (e.g., S, 1, F).
• Preset: Select which preset this hotkey should activate.

Global settings that apply to all presets.

• Keep Alive Apps: A list of applications that should not be quit when switching presets.
  • By default, SpacePigeon quits apps not defined in the current preset to keep your workspace clean.
  • Add apps here (e.g., "Spotify", "Discord") to keep them running in the background.
  • If a kept-alive app is also part of the new preset's layout, it will be moved to its assigned space/position.

After making changes, click "Save & Reload Hammerspoon" to apply them immediately.

• Hammerspoon (The app will automatically download and install this to ~/Applications if it is not found).

MIT