AeroSpace Window Management

AeroSpace is a tiling window manager for macOS that brings i3/sway-style workspace management to Mac. Unlike traditional window managers, AeroSpace uses persistent workspaces across monitors and keyboard-driven navigation to eliminate the need for mouse-based window juggling.

Core Concepts

Workspaces vs. Monitors

Traditional macOS: Each monitor has its own set of "Spaces" (virtual desktops) that are monitor-specific. Moving between spaces on one monitor doesn't affect the other monitor.

AeroSpace: Workspaces are independent of monitors. You can have workspace 1 on monitor A, then move it to monitor B, and workspace 1 maintains all its window arrangements. This allows for more flexible multi-monitor workflows.

Key difference:

• macOS Spaces: Monitor-locked (Space 1 on Monitor A ≠ Space 1 on Monitor B)
• AeroSpace Workspaces: Monitor-independent (Workspace 1 can move between monitors while keeping its windows)

Important Limitations

❌ AeroSpace does NOT:

• Support predefined layouts per monitor (no "Monitor 1 always has this layout")
• Save/restore layouts automatically on startup
• Allow the same app window to exist in multiple workspaces simultaneously
• Sync layouts between workspaces

✅ AeroSpace DOES:

• Persist workspace window arrangements until you change them
• Allow multiple windows of the same app in different workspaces (Chrome in workspace 1 AND workspace 2)
• Let you manually set up workspaces once and they'll maintain that arrangement

First Window, Second Window, and Window Panes

In AeroSpace terminology:

• Window = Individual application window
• Pane = A tiled position within a workspace (not a window split, but a layout slot)
• Layout = How windows are arranged (tiles, accordion, floating)

Example:

Workspace 1 (tiles layout, horizontal)
┌─────────────┬─────────────┐
│  Terminal   │   Browser   │  ← Two windows in horizontal tiles
│  (Window 1) │  (Window 2) │
└─────────────┴─────────────┘

When you add a third window, AeroSpace automatically adjusts:

┌────────┬────────┬────────┐
│Terminal│Browser │  Code  │
└────────┴────────┴────────┘

Essential Shortcuts

Navigation (⌃⌥ = Ctrl+Option)

Note: These use ⌃⌥ instead of ⌥ alone to avoid conflicts with Zellij terminal multiplexer shortcuts.

Moving Windows (⌃⌥⇧ = Ctrl+Option+Shift)

Workspace Switching

Moving Windows to Workspaces

Layout Controls

Service Mode (⌥⇧+;)

Multi-Monitor Workflows

Creating Similar Layouts Across Monitors

Problem: You want workspace 1 on Monitor A and workspace 2 on Monitor B to have similar window layouts.

Reality check: AeroSpace has no "sync layout" or "apply template" feature. You must manually set up each workspace.

Workflow:

1. Set up workspace 1 (Monitor A):

   bash
   ⌥+1              # Switch to workspace 1
   # Open Terminal (⌘+Space, type "terminal")
   # Open Neovim (in Terminal: nvim)
   ⌃⌥⇧+h/l          # Arrange windows side-by-side
   ⌥+/              # Toggle to horizontal tiles if needed
   

2. Set up workspace 2 (Monitor B):

   bash
   ⌥+2              # Switch to workspace 2
   # Open Browser (⌘+Space, type "chrome")
   # Open Obsidian (⌘+Space, type "obsidian")
   ⌃⌥⇧+h/l          # Arrange identically to workspace 1
   

3. Move workspace 2 to Monitor B:

   bash
   ⌥⇧+Tab           # Move workspace to next monitor (wrap around)
   # May need to press multiple times to reach desired monitor
   

Can you have the SAME app in both workspaces?

No - Same window cannot be in two workspaces.
Yes - Multiple windows of the same app can be in different workspaces.

Example:

bash
# Workspace 1
⌥+1
⌘+Space → "terminal" → Enter    # Terminal window 1
# Inside terminal: nvim project1

# Workspace 2  
⌥+2
⌘+Space → "terminal" → Enter    # Terminal window 2 (NEW window)
# Inside terminal: nvim project2

Now you have Terminal in BOTH workspace 1 and workspace 2, but they're different windows of the same app.

Per-Monitor Workspace Assignment

Goal: Always have workspace 1 on Monitor A, workspace 2 on Monitor B, etc.

Reality: AeroSpace doesn't support automatic monitor-to-workspace binding. Workspaces are monitor-independent by design.

What this means:

• You CANNOT say "Workspace 1 always lives on Monitor A"
• Workspaces can move between monitors freely (⌥⇧+Tab)
• You CANNOT define a layout template that applies to a specific monitor

Workaround - Manual positioning on startup:

After booting your Mac and opening apps:

bash
⌥+1              # Go to workspace 1
⌥⇧+Tab           # Move workspace 1 to Monitor A (press multiple times if needed)

⌥+2              # Go to workspace 2  
⌥⇧+Tab           # Move workspace 2 to Monitor B

Better approach - Use semantic workspace names:

• Workspace C = "Code" (⌥+c)
• Workspace D = "Docs" (⌥+d)
• Workspace M = "Music" (⌥+m)

This way you remember workspaces by purpose, not monitor position.

Example: Two-Monitor Coding Setup

Monitor A (left, 1920x1080): Workspace C (Code)

┌─────────────┬─────────────┐
│  Terminal   │   Neovim    │
│  (Zellij)   │  (LazyVim)  │
└─────────────┴─────────────┘

Monitor B (right, 1920x1080): Workspace D (Docs)

┌─────────────┬─────────────┐
│  Browser    │  Obsidian   │
│  (Docs)     │  (Notes)    │
└─────────────┴─────────────┘

Setup commands:

bash
# On Monitor A
⌥+c              # Switch to workspace C
# Open Terminal + Neovim, arrange with ⌃⌥⇧+h/l

# Move to Monitor B
⌥+d              # Switch to workspace D
# Open Browser + Obsidian, arrange with ⌃⌥⇧+h/l
⌥⇧+Tab           # Move workspace D to Monitor B

Switching:

• ⌥+c = Jump to code workspace (Monitor A)
• ⌥+d = Jump to docs workspace (Monitor B)
• ⌥+Tab = Toggle between last two workspaces

Configuration File Location

~/.config/aerospace/aerospace.toml

Key settings:

• persistent-workspaces - Keeps workspaces alive even when empty
• default-root-container-layout - Default layout for new workspaces (tiles/accordion)
• on-focused-monitor-changed - Mouse follows focus to new monitor

Reload config: ⌥⇧+; then Esc

Troubleshooting

Workspace 10 Appears on Second Monitor

Problem: You press ⌥+1 to go to workspace 1 on first monitor, but your second monitor shows "workspace 10" instead of a named workspace.

Cause: AeroSpace auto-generates workspace numbers when apps open on monitors without an active workspace. Since your config only defines ⌥+1 through ⌥+9 (not ⌥+0), workspace 10 has no keyboard shortcut.

Solution 1: Move windows to a defined workspace

bash
# Focus the second monitor (click or move mouse there)
⌥+2              # Switch to workspace 2 (this moves to second monitor)
# All windows on "workspace 10" will merge into workspace 2

Solution 2: Add ⌥+0 binding for workspace 10

Add to ~/.config/aerospace/aerospace.toml in [mode.main.binding] section:

toml
# Add after the alt-9 line
alt-0 = 'workspace 10'
alt-shift-0 = 'move-node-to-workspace 10'

Then reload config (⌥⇧+; then Esc).

Solution 3: Prevent auto-workspace creation

Use letter workspaces instead of numbers for multi-monitor setups:

• Monitor 1: Workspace 1 (⌥+1)
• Monitor 2: Workspace A (⌥+a)
• Monitor 3: Workspace B (⌥+b)

This way, you avoid the 10/20/30 numbering collision.

Best practice: Explicitly create workspaces before opening apps:

bash
⌥+1              # Go to workspace 1 (monitor 1)
# Open apps here

⌥+2              # Go to workspace 2 (monitor 2)  
# Open apps here

This prevents AeroSpace from auto-creating numbered workspaces.

Comparison to Other Tools

When to use AeroSpace:

• You want i3/sway-style tiling on macOS
• You switch between many apps and windows frequently
• You prefer keyboard navigation over mouse
• You need workspace persistence across monitors

When to use Moom:

• You want quick window snapping (quarters, halves)
• You prefer mouse-driven workflows
• You don't need persistent workspaces

Links

Official Documentation

• URL: https://nikitabobko.github.io/AeroSpace/guide↗
• Summary: Complete guide to AeroSpace configuration, commands, and concepts

GitHub Repository

• URL: https://github.com/nikitabobko/AeroSpace↗
• Summary: Source code, issue tracker, and community discussions

Related Articles

• Moom - Alternative window manager with mouse-driven interface
• Zellij - Terminal multiplexer that pairs well with AeroSpace