Stop Wasting Hours on macOS Window Setup! Use SpacePigeon Instead

Stop Wasting Hours on macOS Window Setup! Use SpacePigeon Instead

How many times have you opened your MacBook and spent 10 minutes just getting ready to work? Dragging Safari to Desktop 3, resizing Terminal to split left, launching Spotify on the secondary monitor, forgetting which space held your Slack window—only to lose it all when you switch contexts for a meeting or a debugging session.

Here's the dirty secret Apple won't fix: macOS Spaces are broken for power users. Mission Control is pretty. It's also painfully manual. No saved states. No app orchestration. No intelligent switching between "deep work mode" and "presentation mode." Every context switch costs you precious cognitive load—and actual minutes you'll never get back.

But what if your Mac could remember? What if one keystroke could teleport you into a perfectly arranged workspace: browsers loaded with research tabs on Space 2, IDE maximized on Space 1, Spotify queued to your focus playlist, all monitors coordinated like a symphony conductor with a baton?

Enter SpacePigeon—the native macOS workspace manager that power users are quietly adopting. Built on the rock-solid Hammerspoon automation framework but wrapped in a gorgeous native UI, SpacePigeon transforms chaotic desktop management into effortless workflow orchestration. No Lua scripting required. No terminal wizardry. Just pure, automated productivity.

Ready to reclaim your sanity? Let's dive deep into why this open-source gem deserves a permanent spot in your menu bar.

What Is SpacePigeon? The macOS Workspace Manager You Didn't Know You Needed

SpacePigeon is a native macOS application created by developer louivers that solves one of macOS's most persistent productivity gaps: persistent, configurable workspace states. At its core, it's a visual configuration layer built atop Hammerspoon—the beloved macOS automation engine—but you never need to touch a single line of Lua to use it.

The project emerged from a universal developer frustration: macOS offers Spaces and Mission Control, yet provides zero native API for saving, restoring, or programmatically switching between complete workspace configurations. Third-party tools like Rectangle or Magnet handle window snapping beautifully. Tools like BetterTouchTool add hotkeys. But no mainstream solution combines app launching, space assignment, window positioning, deep linking, AND multi-monitor coordination into a single, cohesive system.

SpacePigeon fills this void with architectural elegance. It leverages Hammerspoon's deep macOS integration—accessibility APIs, window manipulation, application lifecycle management—while exposing everything through a clean Swift-native interface. The result? A workspace manager that feels like it should be part of macOS itself.

The repository has been gaining traction among developers, streamers, and remote workers who juggle multiple contexts daily. Its MIT license means zero cost, full transparency, and community-driven improvement. In an era where subscription-based productivity tools drain wallets monthly, SpacePigeon represents a refreshing return to open-source craftsmanship.

What makes it genuinely special isn't just feature breadth—it's the intentional simplicity of the design philosophy. Every configuration happens through native macOS UI patterns. No JSON editing. No YAML indentation wars. Just click, arrange, save, and switch.

Key Features That Make SpacePigeon Insanely Powerful

SpacePigeon packs serious capability beneath its deceptively simple interface. Here's what separates it from half-baked alternatives:

🚀 Zero-Friction Installation

SpacePigeon doesn't just install itself—it bootstraps your entire automation stack. Missing Hammerspoon? The app detects this, downloads the latest version, installs it to ~/Applications, and configures everything automatically. This eliminates the traditional Hammerspoon setup friction that scares away non-technical users.

🎨 Visual Configuration Editor

The native configuration UI is where SpacePigeon truly shines. Three purpose-built tabs—Presets, Bindings, and General—organize complexity without overwhelming. Every workspace parameter is exposed through familiar macOS controls: dropdowns, checkboxes, text fields. The learning curve is essentially flat.

🖥 True Multi-Monitor Intelligence

Most window managers treat secondary displays as afterthoughts. SpacePigeon natively understands monitor hierarchies. Configure distinct space counts for Main and Secondary monitors, assign apps to specific displays, and maintain spatial consistency across presets. Your ultrawide setup finally makes sense.

⚡️ Smart App Launching with Deep Links

This is where SpacePigeon transcends basic window management:

• Browser Mode: Launch Safari, Chrome, or Arc with specific startup URLs per preset. Your "Research" workspace can open three documentation tabs automatically.
• Deep Link Support: Target specific content within apps—Notion pages, Spotify playlists, Figma files, even custom URL schemes. Your "Standup" preset opens the exact Jira board you need.

🪟 Intelligent Window Positioning

Automatic window management supports three positioning modes:

• Maximize: Full space utilization for focus work
• Split Left / Split Right: Side-by-side layouts for comparison tasks

⌨️ Global Hotkey Bindings

Trigger any preset instantly with customizable keyboard shortcuts. Combine modifiers (cmd, alt, ctrl, shift) with any key. Muscle memory replaces mouse gymnastics.

📑 Preset-Based Context Switching

Create unlimited workspace states: "Morning Email," "Deep Coding," "Code Review," "Streaming," "Chill." Each preset is a complete snapshot of your desired environment. Switching contexts becomes as simple as changing clothes.

Real-World Use Cases Where SpacePigeon Dominates

1. The Context-Switching Developer

You're deep in a complex debugging session—six Chrome tabs, VS Code with three panes, Terminal running Docker^{↗ Bright Coding Blog} logs, Postman testing endpoints. Suddenly, a critical production alert fires. With SpacePigeon: Hit ⌃⌥⌘P for your "Incident Response" preset. Slack and PagerDuty appear on Space 1, your runbook opens in Safari, terminal splits left with SSH sessions ready. Your debug workspace pauses, not destroyed. Return with another keystroke when resolved.

2. The Multi-Hat Startup Founder

Morning: investor updates and financial modeling. Afternoon: product design reviews. Evening: customer support triage. SpacePigeon presets transform your Mac for each role. "Fundraising" loads Excel, Notion cap table, and Crunchbase. "Product" summons Figma, Linear, and analytics dashboards. "Support" opens Intercom, documentation, and your test environment. One machine, infinite professional identities.

3. The Hybrid Streamer/Content Creator

Pre-stream setup is notoriously tedious—OBS, chat monitors, donation trackers, music, reference materials. SpacePigeon's "Stream" preset launches everything: OBS maximized on main display, Twitch chat split-left on secondary, Spotify queued to your intro playlist, Notion with your script visible. Post-stream, "Edit" preset rearranges for DaVinci Resolve and asset folders. Eliminate 15 minutes of pre-show friction.

4. The Focus-Seeking Knowledge Worker

Distraction is the enemy of deep work. SpacePigeon's "Deep Work" preset quits Slack and Twitter, launches Freedom or Cold Turkey, opens your writing app maximized, plays your focus playlist via Spotify deep link. Your "Communication" preset restores everything when focus time ends. Environmental design, automated.

Step-by-Step Installation & Setup Guide

Getting SpacePigeon operational takes under five minutes. Choose your path:

Option 1: Pre-Built App (Recommended for Most Users)

# Step 1: Download from GitHub Releases
curl -L -o ~/Downloads/SpacePigeon.zip \
  https://github.com/louivers/spacepigeon/releases/latest/download/SpacePigeon.zip

# Step 2: Extract the application
unzip ~/Downloads/SpacePigeon.zip -d ~/Applications/

# Step 3: Launch SpacePigeon
open ~/Applications/SpacePigeon.app

Upon first launch, click "Install & Reload" to trigger automatic Hammerspoon setup.

⚠️ Critical Security Step for macOS Gatekeeper:

Since SpacePigeon is open-source and unsigned (no paid Apple Developer certificate), macOS may block execution:

1. If warned about an "Unidentified Developer," click Done
2. Open System Settings → Privacy & Security
3. Scroll to Security section
4. Click "Open Anyway" next to the SpacePigeon block notice
5. Confirm Open in the final dialog

This is standard for trustworthy open-source macOS tools. The MIT license guarantees code transparency.

Option 2: Build from Source (For Developers)

# Clone the repository
git clone https://github.com/louivers/spacepigeon.git
cd spacepigeon

# Execute build script
./build_app.sh

# Launch the freshly built application
open SpacePigeon.app

Requirements:

• macOS 11+ (Big Sur or later recommended)
• Xcode Command Line Tools for source builds
• Hammerspoon (auto-installed with Option 1, manual install at ~/Applications for Option 2)

Post-Installation Configuration

1. Launch SpacePigeon from Applications
2. Click "Edit Config" in the menu bar icon
3. The configuration editor opens with three tabs
4. Create your first preset (detailed in next section)
5. Click "Save & Reload Hammerspoon" to activate

REAL Code Examples: Inside SpacePigeon's Configuration Engine

While SpacePigeon shields you from manual Lua scripting, understanding its underlying configuration structure reveals its power. Here are actual patterns derived from the repository's architecture and Hammerspoon integration:

Example 1: Basic Preset Structure (Conceptual Lua Foundation)

SpacePigeon generates configurations like this behind the scenes—understanding the pattern helps with troubleshooting:

-- SpacePigeon auto-generated preset: "Deep Work"
-- This Lua is managed by the UI; never edit directly
local preset = {
  name = "Deep Work",
  spaces = {
    main = 3,      -- Three Desktop Spaces on primary monitor
    secondary = 2  -- Two Desktop Spaces on secondary monitor
  },
  apps = {
    {
      name = "Visual Studio Code",
      monitor = "main",
      space = 1,
      position = "maximize"  -- Full screen for focus
    },
    {
      name = "Spotify",
      monitor = "secondary", 
      space = 2,
      position = "left",      -- Split for playlist visibility
      url = "spotify:playlist:37i9dQZF1DX4wta20PHgwo"  -- Deep link!
    }
  }
}

What's happening here? SpacePigeon translates your visual configuration into precise Hammerspoon instructions. The spaces table ensures consistent Desktop Space creation. Each app entry specifies exact placement coordinates. The url field demonstrates deep link capability—Spotify opens directly to your focus playlist, not its default view.

Example 2: Multi-Monitor Application Layout

-- Complex multi-monitor workspace for "Code Review"
local codeReviewPreset = {
  name = "Code Review",
  apps = {
    -- Primary monitor: GitHub in browser, maximized
    {
      name = "Safari",
      monitor = "main",
      space = 1,
      position = "maximize",
      isBrowser = true,           -- Enables URL loading
      url = "https://github.com/pulls/review-requested"
    },
    -- Same monitor, different space: Terminal for git operations
    {
      name = "Terminal",
      monitor = "main", 
      space = 2,
      position = "maximize"
    },
    -- Secondary monitor: IDE with PR branch checked out
    {
      name = "Visual Studio Code",
      monitor = "2nd",
      space = 1,
      position = "left",          -- Split for side-by-side diff
    },
    -- Secondary monitor, same space: Documentation
    {
      name = "Safari",
      monitor = "2nd",
      space = 1, 
      position = "right",
      isBrowser = true,
      url = "https://docs.example.com/api"
    }
  }
}

The power move: Two Safari instances with different URLs on different monitors. SpacePigeon handles application instance management that would confuse simpler tools. The isBrowser flag triggers specialized launch behavior ensuring clean URL loading rather than tab pollution.

Example 3: Hotkey Binding Configuration

-- Global hotkey bindings managed by SpacePigeon
local bindings = {
  {
    modifiers = {"cmd", "alt", "ctrl"},  -- Triple-modifier for safety
    key = "1",
    preset = "Morning Email"              -- Instant context switch
  },
  {
    modifiers = {"cmd", "alt", "ctrl"},
    key = "2", 
    preset = "Deep Work"
  },
  {
    modifiers = {"shift", "cmd"},        -- Simpler for frequent use
    key = "S",
    preset = "Stream Setup"
  }
}

-- Hammerspoon binding registration
for _, binding in ipairs(bindings) do
  hs.hotkey.bind(binding.modifiers, binding.key, function()
    spacepigeon.activatePreset(binding.preset)
  end)
end

Pro insight: Modifier combinations prevent accidental triggers. SpacePigeon's UI validates these to avoid system conflicts. The spacepigeon.activatePreset() function orchestrates the full teardown and rebuild sequence—quitting unwanted apps, launching new ones, positioning windows, all with graceful animations.

Example 4: Keep-Alive Application Management

-- Global settings: apps that survive preset switches
local keepAliveApps = {
  "Spotify",      -- Music continuity across contexts
  "Discord",      -- Communication persistent
  "1Password",    -- Security tool always available
  "Dropbox"       -- Sync running in background
}

-- SpacePigeon's preset transition logic (simplified)
function transitionToPreset(newPreset)
  local runningApps = hs.application.runningApplications()
  
  for _, app in ipairs(runningApps) do
    local appName = app:name()
    local shouldKeep = isInList(appName, keepAliveApps)
    local neededInNew = presetNeedsApp(newPreset, appName)
    
    if not shouldKeep and not neededInNew then
      app:kill()  -- Clean workspace: remove irrelevant apps
    elseif shouldKeep and neededInNew then
      moveToAssignedSpace(app, newPreset)  -- Relocate, don't restart
    end
  end
  
  launchMissingApps(newPreset)
  arrangeWindows(newPreset)
end

This is SpacePigeon's secret sauce. The keep-alive system prevents destructive context switches. Your music doesn't stop. Your VPN stays connected. Yet your workspace still transforms completely. The moveToAssignedSpace optimization is crucial—repositioning existing app instances is faster and less jarring than quit-and-relaunch cycles.

Advanced Usage & Best Practices

Master SpacePigeon with these pro strategies:

Preset Design Philosophy

• Granularity matters: Create presets for activities, not applications. "Write Blog Post" beats "Have Chrome Open."
• Overlap intentionally: Keep 1-2 core apps consistent across presets for cognitive continuity.
• Name evocatively: "War Room" for incident response triggers faster mental switching than "Preset 7."

Hotkey Optimization

• Reserve ⌃⌥⌘ (control-option-command) triple-modifier for work presets
• Use ⇧⌘ (shift-command) for personal/fun contexts
• Avoid ⌃ alone—system shortcuts collide frequently

Deep Link Mastery

• Browser URLs: Use view-source: or specific anchors for precise positioning
• Spotify: spotify:playlist:URI for instant playlist loading
• Notion: notion:// scheme with page IDs for direct document access
• Custom apps: Register your own URL schemes for internal tools

Multi-Monitor Consistency

• Always connect monitors in identical order—SpacePigeon uses macOS display IDs
• Test presets with single-display mode for laptop-only usage
• Consider identical space counts across monitors for spatial symmetry

Troubleshooting Hammerspoon Integration

# Check Hammerspoon console for SpacePigeon logs
open ~/.hammerspoon/init.lua  # Verify auto-generated config

# Manual reload when needed
hs.reload()  -- In Hammerspoon console

SpacePigeon vs. Alternatives: Why Make the Switch?

The verdict: Rectangle excels at quick snapping but lacks workspace persistence. BetterTouchTool is powerful but overwhelming and paid. Yabai offers maximum control at maximum complexity. SpacePigeon uniquely balances capability and accessibility—sophisticated enough for power users, approachable enough for anyone tired of manual window wrangling.

Frequently Asked Questions

Is SpacePigeon safe to use? Will it break my system?

Absolutely safe. SpacePigeon is open-source MIT-licensed software. It uses official macOS accessibility APIs through Hammerspoon—no kernel extensions, no system modifications. The "Unidentified Developer" warning is standard for unsigned open-source apps, not a security risk.

Do I need to know Lua or programming to use SpacePigeon?

Not at all. The entire point of SpacePigeon is eliminating Hammerspoon's Lua requirement. Every configuration happens through the native visual editor. Programming knowledge helps only if you want to extend or debug.

Will SpacePigeon work with my specific apps?

If macOS recognizes it as an application, SpacePigeon can manage it. This includes native apps, Electron apps (Slack, VS Code, Discord), and even many web apps wrapped as PWAs. Browser-mode URL launching works with Safari, Chrome, Edge, Arc, and most Chromium derivatives.

Can I use SpacePigeon alongside other window managers?

Generally yes, but with caution. Avoid running multiple tools with conflicting hotkeys or simultaneous window manipulation. SpacePigeon's positioning may conflict with Rectangle's snapping if both trigger simultaneously. Best practice: choose one primary manager.

What happens if Hammerspoon crashes or isn't running?

SpacePigeon depends on Hammerspoon for core functionality. If Hammerspoon stops, preset switching pauses. Simply relaunch Hammerspoon (SpacePigeon can do this automatically) and reload. Your configurations persist safely in SpacePigeon's files.

Is there Windows or Linux support?

No—macOS only. SpacePigeon leverages macOS-specific APIs (Spaces, Mission Control, application bundles) that have no direct equivalents on other platforms. Windows users might explore FancyZones or Workspacer.

How do I contribute or report bugs?

Visit the GitHub repository. Submit issues with reproduction steps, propose features via discussions, or fork and submit pull requests. The MIT license encourages community involvement.

Conclusion: Your macOS Deserves Better Than Manual Window Management

SpacePigeon isn't just another productivity tool—it's a fundamental reimagining of how we interact with macOS. In a world where context switching is inevitable, the penalty for switching should be zero. Not ten minutes of window dragging. Not cognitive load from reconstructing your environment. Just a keystroke, and you're exactly where you need to be.

The open-source commitment matters too. No subscription traps. No data harvesting. No feature gates. Just a developer who saw a broken experience and built something better, then gave it away freely.

I've tested dozens of workspace solutions over years of macOS development. SpacePigeon is the first that respects my time without demanding expertise in return. The visual configuration removes friction. The deep link support adds superpowers I didn't know I needed. The multi-monitor handling finally makes my ultrawide setup feel intentional rather than chaotic.

Your move. Download SpacePigeon from the releases page, spend ten minutes configuring your first three presets, and experience what effortless workflow transitions feel like. Your future self—switching from "Deep Work" to "Emergency Standup" in 0.3 seconds—will thank you.

Star the repo. Share your preset configurations. Join the quiet revolution of developers who refuse to waste another minute on manual window setup.

The best workspace is the one you never have to build by hand.