WindowRanger 1.0.0

WindowRanger 1.0.0

WindowRanger 1.0 is the first Stable release of the native macOS virtual-workspace manager. It
combines fast keyboard-driven workspace control with visual configuration, display-aware profiles,
reliable restoration, and an optional command-line interface for automation and agents.

Highlights

• Create named virtual workspaces on one or more displays, switch or move windows with global
  shortcuts, and choose Freeform, Tiled, or Accordion layouts with visual orientation, gap, and
  padding controls.
• Configure reusable profiles with automatic docked, undocked, full-screen Game Mode, and exact
  display-setup selection. Profile content can sync through iCloud while each Mac keeps ownership
  of its local active profile, monitor bindings, and automatic assignments.
• Use the menu bar, searchable Command Palette, Shortcut Guide, Focus Border, and Quick App Shelf
  as complementary ways to navigate and arrange windows. Optional captured workspace previews show
  the current wallpaper and clickable window thumbnails when Screen Recording access is enabled.
• Install the bundled windowranger command from General Settings without administrator access.
  It exposes every stable first-party action and the complete versioned configuration surface, with
  revision checks and explicit replacement confirmation for safe automation. It can also generate
  a ready-to-use agent skill.
• Move between Macs and display arrangements without sacrificing recovery safety: WindowRanger
  preserves workspace membership and frames, handles quit/wake/restart reconciliation, and keeps
  inactive workspaces off-screen without replacing native macOS Spaces.

Requirements

• macOS 14 or later.
• Accessibility permission for window discovery and management.
• Screen Recording permission only when optional captured workspace previews are enabled. macOS's
  permission wording also mentions audio; WindowRanger does not capture audio or the pointer.

Installation

1. Download WindowRanger-1.0.0.dmg from this release's Assets section.
2. Optionally verify it against WindowRanger-1.0.0.dmg.sha256.
3. Use Quit WindowRanger in an existing copy, then open the DMG.
4. Drag WindowRanger.app onto the Applications shortcut and replace the existing copy if Finder
   asks.
5. Launch WindowRanger from /Applications and grant Accessibility access when macOS asks.

The notarized ZIP and its checksum are included as a fallback for environments that cannot mount a
DMG. GitHub's automatically generated source archives do not contain the installable application.

After installation, General Settings can add the bundled command to ~/.local/bin. Open a new
terminal after changing PATH.

Updates and Homebrew

Stable is the default in-app update channel. Beta remains an explicit opt-in and never causes a
Stable-only client to install a prerelease. The Homebrew Cask follows the same signed, notarized,
immutable Stable DMG and will be announced separately after its install, upgrade, uninstall, and
permission behavior has been verified through the selected tap.

Known limitations

• WindowRanger provides virtual workspaces inside the current macOS desktop; it does not create,
  remove, or replace native macOS Spaces.
• Captured workspace previews are off by default and use a bounded, one-shot, in-memory thumbnail
  cache. Without Screen Recording permission, previews fall back to app icons and window metadata.
• Some apps expose unusual or read-only Accessibility windows. WindowRanger conservatively ignores
  ambiguous panels and windows that cannot be moved safely.
• If another window manager uses the same global shortcuts, change one application's shortcuts or
  quit the other manager before using WindowRanger.

Feedback and security

Use the repository issue forms for privacy-safe bugs, feature requests, and questions. Do not post
suspected vulnerabilities, private diagnostics, window titles, document names, URLs, or user file
paths in a public issue; follow SECURITY.md instead.