Who AeroSpace is for#
Linux developer adopting macOS
Developers who use i3, Sway, or another tiling window manager on Linux can configure AeroSpace to match their existing keybindings almost exactly. The tree-based layout, named workspaces, and alt+hjkl navigation are all directly portable from an i3 config to AeroSpace TOML.
Skip if:
The user is new to tiling window managers and prefers a graphical setup.
Multi-monitor developer setup
AeroSpace assigns workspaces to specific monitors independently, so switching workspaces on your code screen does not disturb your browser or terminal on a second display. This matches the i3wm per-monitor workspace model and is the main reason developers with two or three displays prefer it over native macOS Spaces.
Skip if:
The user works from a single laptop screen where native macOS Spaces are sufficient.
Dotfiles and scripted window control
Because AeroSpace exposes a socket protocol and CLI, your window manager becomes scriptable. You can write shell scripts that move windows to specific workspaces, trigger layouts at login via after-startup-command, or integrate with status bars. The TOML config version-controls alongside your shell configs and other dotfiles.
Skip if:
The user wants a point-and-click or drag-to-snap experience with no config file involvement.
The problem it solves#
macOS gives you Mission Control and native Spaces for window management, but both fall short for developers doing focused work. Switching workspaces requires animations you cannot skip, there is no scripting interface for layouts, and keyboard shortcuts for moving windows between monitors are limited to what System Preferences exposes. Anyone who has used i3 or a tiling window manager on Linux runs into this friction constantly on a Mac.
Multi-monitor setups compound the problem. Native Spaces treat connected displays as a coupled system, which means switching workspaces on one monitor affects the other. There is no plain-text config that tracks in version control, no CLI to query or control the window tree from a script, and no way to set up a repeatable layout at login without manual notes.
How it solves it#
Tree-based tiling layout
Windows are arranged in a hierarchical tree of horizontal and vertical splits. You control the tree with keyboard bindings, and AeroSpace normalizes it automatically so nested containers with opposite orientations are flattened, keeping your layout clean without manual cleanup.
Virtual workspace emulation
AeroSpace implements its own workspace layer instead of using native macOS Spaces. Switching is instant with no animations, and each workspace is independent per monitor in a multi-monitor setup. You can name workspaces with letters or numbers and bind each to a keyboard shortcut.
Plain-text TOML configuration
All keyboard bindings, gaps, layout preferences, and startup commands live in a single `~/.aerospace.toml` file. The config is TOML 1.1.0 format, version-tracked alongside your other dotfiles, and hot-reloadable when `auto-reload-config` is enabled.
CLI and shell completion
The `aerospace` binary ships with man pages and completion scripts for bash, fish, and zsh. You can query workspaces, move windows, and trigger layout commands from terminal scripts or other tools via a socket protocol with a defined wire format.
No SIP modification required
AeroSpace uses only macOS public accessibility APIs plus a single private API for window ID lookup. It never requires disabling System Integrity Protection, which keeps your system security posture intact and makes the tool more resilient to macOS updates.
Per-monitor workspace assignment
Workspaces can be assigned to specific monitors by name or index. When you switch workspaces on one monitor, other monitors stay where they are, matching i3wm's per-monitor workspace behavior rather than macOS's coupled Spaces model.
Strengths and trade-offs#
Strengths
- No SIP requirement, public APIs onlyMost tiling window managers for macOS require disabling System Integrity Protection or hooking into private APIs at depth. AeroSpace avoids this: it operates on the macOS public accessibility API and does not touch kernel extensions or code injection. Your system stays unmodified.
- Dotfile-native configurationThe entire configuration lives in a TOML file at `~/.aerospace.toml`. You can commit it to a repo, restore it on a new machine with one `cp`, and diff changes over time. There is no database, no sync service, and no GUI to reverse-engineer when documenting your setup.
- MIT license with no restrictionsAeroSpace is MIT licensed, which means you can use it personally, commercially, or as part of a larger toolchain with no attribution requirements and no restrictions on how you run it. There are no subscription fees, no license server checks, and no expiry.
- Active maintenance and real adoptionThe project has three contributors with write access and ships regular updates (last push October 2026). At 23,531 GitHub stars and 745 forks since its 2023 launch, it has real adoption for a macOS system utility, reflecting sustained developer interest beyond an initial spike.
Trade-offs
- -Public beta with possible breaking changesAeroSpace is not yet at version 1.0. The README explicitly notes that breaking changes to configuration files, CLI, and behavior can happen before 1.0, with semver major bumps when they do. A pending core tree refactor is blocking the 1.0 release, and a known bug where windows randomly jump to the focused workspace is tied to that same refactor.
- -Not notarized by AppleAeroSpace is not submitted to Apple's notarization process. The Homebrew installation script removes the quarantine attribute automatically, but manual installs require an extra step to bypass the 'Apple cannot check this app' warning. This is a friction point for users who follow all macOS security prompts closely.
- -No GUI configuration, keyboard-onlyAeroSpace provides no graphical interface for configuration. The README states a GUI for configuration will never be added. If you prefer drag-to-snap, visual layout presets, or point-and-click window arrangement, AeroSpace is not the right fit.
- -Does not integrate with native macOS SpacesAeroSpace ignores native macOS Spaces entirely and runs a parallel workspace system. Features that depend on Spaces (Mission Control grouping, per-space wallpapers, Exposé grouping) will not work as expected alongside AeroSpace. You use AeroSpace's workspaces or macOS Spaces, not both.
AeroSpace vs alternatives#
AeroSpace vs Moom
Moom is a paid macOS utility that saves, restores, and snaps window layouts through a GUI. Its core workflow is mouse-and-menu: hover a window's green button to see snap zones, or draw custom layout regions in a grid editor. Moom has no CLI, no text config, and no concept of virtual workspaces.
AeroSpace targets a different workflow entirely. Where Moom helps you arrange windows by dragging, AeroSpace arranges them through keyboard bindings alone. AeroSpace has no snap zones, no GUI layout editor, and no preset-saving feature. Its virtual workspace system and tree-based tiling are capabilities Moom does not offer at any price. For someone who wants to snap Finder to the left half of the screen with a mouse gesture, Moom is the faster pick. For someone who wants to press alt+h and have their editor tile left without touching the mouse, AeroSpace is the option built for that workflow.
AeroSpace vs BetterStage
BetterStage is a paid macOS app focused on window grouping and stage management. It extends the macOS Stage Manager concept with keyboard shortcuts for activating groups and switching between staged sets of windows. BetterStage integrates with native macOS features rather than replacing them.
AeroSpace does not integrate with Stage Manager or native macOS Spaces. Its workspace model is self-contained and explicitly ignores the macOS Spaces layer. BetterStage is for users who want an enhanced version of the macOS window experience; AeroSpace is for users who want to leave that experience behind for a keyboard-only tiling model. The two tools serve different user intents and are not interchangeable.
Both Moom and BetterStage are commercial tools with no self-hosting consideration. AeroSpace is MIT licensed and runs entirely on your own machine with no network calls, no account required, and no subscription.
Quick start#
Install AeroSpace via Homebrew for automatic updates and setup on macOS 13 or later.
```bash
brew install --cask nikitabobko/tap/aerospace
```What it's built on#
- Languages
- Swift
FAQ#
Does AeroSpace require disabling System Integrity Protection?
No. AeroSpace uses macOS public accessibility APIs and does not require disabling SIP. This distinguishes it from yabai, which requires SIP modification to enable some of its features. AeroSpace uses one private API for window ID lookup but no kernel extensions or code injection.
Is AeroSpace stable enough for daily use?
The README marks AeroSpace as public beta but states it can be used as a daily driver. The main caveat is that breaking changes to config files and CLI can happen before version 1.0. A known bug can cause windows to randomly jump to the focused workspace; the fix is blocked on a core tree refactor listed in the project roadmap.
How is AeroSpace different from Moom or BetterStage?
Moom and BetterStage are paid tools built around GUI-driven layout saving and drag-to-snap window placement. AeroSpace is keyboard-only, configured through a text file, and designed for developers who want a Linux tiling WM workflow on macOS. There is no GUI in AeroSpace; every action maps to a keyboard binding or CLI command.
Can AeroSpace work alongside native macOS Spaces?
AeroSpace replaces macOS Spaces rather than working alongside them. It runs its own workspace emulation and explicitly ignores the native Spaces layer. Features tied to macOS Spaces, such as Mission Control grouping or per-space wallpapers, will not function as expected when AeroSpace is managing workspaces.
How do I install AeroSpace?
The preferred install is via Homebrew: brew install --cask nikitabobko/tap/aerospace. This provides automatic updates and removes Apple's quarantine flag so the app opens without warnings. A manual install from the GitHub releases page is also available for users who want a pinned version.
Similar open-source tools#
winmux
Project-based window manager for macOS with sidebar and tab groups
rakazo
AI teammates you own: your keys, your model, your machine.
Oxynote
Technical wiki with live metrics, draft reviews, and real-time editing
Deviload
yt-dlp desktop app with media library, player, and editor
Word Smith
Long-form writing studio for Obsidian. No cloud, no account.
Arrmada
Movies, TV, books and requests in one app, arr stack included