SpacePigeon

Product Introduction

1. SpacePigeon is a macOS workspace automation tool that enables users to define and restore complete desktop environments with predefined applications, window layouts, browser URLs, and multi-monitor configurations. It operates as a lightweight open-source application built on Hammerspoon, combining scripting flexibility with native macOS integration. The tool allows users to save workspace states as presets and switch between them instantly via hotkeys or a graphical interface. Its architecture leverages macOS system APIs through Hammerspoon to manipulate spaces, window positions, and application states programmatically.

2. The core value lies in eliminating repetitive manual workspace configuration while maintaining system performance efficiency. SpacePigeon reduces context-switching overhead by enabling instantaneous transitions between distinct workflow environments like development setups, presentation modes, or leisure configurations. It solves the problem of fragmented workspace management through atomic restoration of application states across multiple desktop spaces and monitors, including browser session initialization with specific URLs.

Main Features

1. SpacePigeon provides atomic workspace restoration through Hammerspoon-driven automation that coordinates application launches, window positioning, and browser URL loading simultaneously. Users can define exact desktop space assignments per monitor (primary and secondary), specify window dimensions using split-screen presets (maximize/left/right), and configure application-specific startup parameters. The system tracks workspace states through Lua configuration files that serialize display layouts, application bundles, and browser session data.

2. A native configuration UI enables visual workspace management without requiring manual Lua scripting, featuring drag-and-drop space allocation and preset organization. The interface exposes advanced parameters like browser mode toggles for URL injection, deep link support for apps using custom URI schemes, and monitor-specific space numbering. Configuration changes are validated against Hammerspoon's API constraints before deployment, preventing runtime errors during workspace restoration.

3. Multi-monitor orchestration handles complex display configurations through separate space indexing per screen, with independent application assignments for primary and secondary displays. The system accounts for variable display arrangements by using macOS's native space identifiers rather than fixed positional assumptions. Browser session management supports Chrome-based and Safari browsers through JavaScript automation, enabling precise tab restoration with URL patterns and domain matching.

Problems Solved

1. SpacePigeon addresses the productivity loss from manually repositioning applications across multiple desktop spaces and monitors during workflow transitions. Traditional methods require users to remember application placements and manually recreate complex window arrangements, which becomes error-prone and time-consuming with frequent context switching. The tool automates this process through pixel-perfect window positioning and application state serialization.

2. The primary target users are technical professionals requiring distinct workspace configurations for different tasks, such as software developers needing separate coding/debugging/documentation environments. Secondary beneficiaries include creative workers managing design/video editing suites and power users operating in multi-monitor workstation setups. The solution particularly benefits remote workers frequently switching between collaboration tools and focused work environments.

3. Typical use cases include restoring a development environment with IDE, terminal, and documentation browser tabs across three desktop spaces; creating presentation modes that hide personal apps and position meeting tools; maintaining separate leisure/work profiles with different app sets and browser sessions. Multi-monitor scenarios enable configurations where primary display hosts communication tools while secondary display maintains reference materials or monitoring dashboards.

Unique Advantages

1. Unlike competing workspace managers, SpacePigeon integrates directly with Hammerspoon's low-level macOS API access while abstracting its complexity through a native UI. This combination provides deeper system integration than Electron-based alternatives while maintaining usability for non-technical users. The open-source foundation allows inspection and modification of the underlying Lua automation scripts, unlike closed-source commercial competitors.

2. The browser automation system implements URL pattern matching and session restoration that surpasses basic bookmark opening, capable of executing JavaScript injections and handling authenticated sessions. Deep link support extends beyond standard apps to custom URI schemes, enabling direct navigation to specific content within applications like Obsidian vaults or Notion pages. Space allocation algorithms account for macOS's dynamic space management, preventing conflicts when spaces are added or removed between sessions.

3. Competitive advantages include zero runtime dependencies beyond Hammerspoon (automatically installed), native M-series chip optimization through SwiftUI components, and preset portability across machines through shareable configuration files. The hotkey system bypasses typical macOS shortcut limitations by using Hammerspoon's eventtap API, enabling reliable global shortcuts even when other apps have conflicting bindings. Automatic configuration validation ensures workspace definitions remain functional across macOS updates.

Frequently Asked Questions (FAQ)

1. How do I resolve "unidentified developer" warnings when launching SpacePigeon? The app requires manual approval in System Settings > Privacy & Security due to being unsigned with an Apple Developer certificate. Users must click "Open Anyway" after initial launch failure, then confirm through a secondary dialog. This security workflow is mandated by macOS for all non-App Store distributed applications without paid developer signatures.

2. Can I build SpacePigeon from source instead of using precompiled releases? Yes, the repository includes build scripts (build_app.sh) that compile SwiftUI components and package the Hammerspoon dependencies. Building requires Xcode 14+ and Homebrew for dependency management. The process generates a self-contained .app bundle with embedded Lua configurations and native binaries.

3. How does SpacePigeon handle multi-monitor configurations with varying display setups? The system uses macOS's display UUIDs rather than positional assumptions, maintaining consistent space assignments even when monitor connections change. Workspace presets store display identifiers, automatically adapting to current hardware configurations. If a secondary monitor is disconnected, associated apps relocate to primary display spaces according to fallback rules defined in workspace templates.