WindowRanger

Who It's For

WindowRanger is for macOS users who think in terms of workspaces rather than individual window positions — someone who wants a dedicated "coding" or "writing" workspace that remembers which windows belong to it, even across a reboot. It suits people who prefer one focused workflow (workspace switching and window arrangement) over a general-purpose scripting language for controlling their desktop, and who want that workflow reachable entirely from the keyboard or the menu bar.

How It Works

WindowRanger organizes open windows into virtual workspaces, tracking window membership and the active workspace persistently so the layout survives an app restart. Each workspace can use one of three layout modes: Freeform for manual positioning, Tiled for a binary split tree, or Accordion for an overlapping stack — and this choice, along with window placement, is migration-safe and persists between sessions. Two configurable global shortcut families drive interaction: Navigate, for finding workspaces and windows, and Arrange, for moving windows between them. The menu bar can present workspaces in Compact, Medium (chips), or Full (display-grouped) modes, and multi-monitor setups can run in either Independent or Unified display modes. Named, reusable profiles support local manual or automatic selection, a Game Mode, and portable JSON export/import. The app requires Accessibility permissions on first launch, and settings are stored locally in ~/Library/Caches/dev.appranger.WindowRanger/workspace-state.json, with iCloud sync available for profiles, shortcuts, and menu-bar preferences.

Configuration

WindowRanger ships a separately signed windowranger command-line helper for status, workspace management, layout control, actions, and configuration, installed at ~/.local/bin/windowranger:

# Install via Homebrew
brew install --cask appranger/tap/windowranger

# Generate the Xcode project during development
xcodegen generate

Compared to Alternatives

Compared to Putback, which focuses on restoring window positions when displays reconnect and layering named Scenes on top, WindowRanger centers on persistent virtual workspaces with three distinct layout modes (Freeform, Tiled, Accordion) rather than display-reconnect-triggered restoration. Compared to general scripting frameworks, WindowRanger is deliberately narrower — it is built around one workspace-and-arrangement workflow rather than a general-purpose command language, trading flexibility for a smaller, more learnable shortcut surface.

Requirements

• Accessibility permissions required on first launch
• No SIP disabling required
• Free and open source (MIT license)
• Actively maintained — frequent releases through beta and 1.0.x

Getting Started

Install via Homebrew with brew install --cask appranger/tap/windowranger, or download the signed release directly from GitHub. Launch WindowRanger and grant Accessibility permission when prompted. Arrange windows into workspaces, choose a layout mode per workspace, and use the Navigate and Arrange shortcut families to move between them from the keyboard. Full source and documentation are on GitHub.