AeroSpace configuration skill

AeroSpace configuration skill

Overview

AeroSpace is an i3-like tiling window manager for macOS. It uses a tree-based tiling paradigm where windows are organized in nested containers with different layouts and orientations.

Configuration location

• Config file: ~/​.config/​aerospace/​aerospace.toml
• Alternative: ~/​.aerospace.toml
• Format: TOML
• Default config: /​Applications/​AeroSpace.app/​Contents/​Resources/​default-config.toml

Current configuration

Workspace organization

Internal monitor (built-in) - workspaces 1-5:

• Windows automatically maximize with fullscreen mode
• No gaps for maximum screen usage
• Perfect for focused single-window work

External monitor - workspaces 6-9:

• Three-column tiling layout
• 8px gaps between windows
• Flexible window arrangement

Workspace assignment

[workspace-to-monitor-force-assignment]
# Internal monitor
1 = 'built-in'
2 = 'built-in'
3 = 'built-in'
4 = 'built-in'
5 = 'built-in'

# External monitor (sequence number 2)
6 = 2
7 = 2
8 = 2
9 = 2

Gap configuration

[gaps]
inner.horizontal = 8
inner.vertical = 8
outer.left = 8
outer.bottom = 8
outer.top = 8
outer.right = 8

Key bindings

Window navigation

• alt-h/​j/​k/​l - Focus left/​down/​up/​right window (vim-style)

Window movement

• alt-shift-h/​j/​k/​l - Move window left/​down/​up/​right

Workspace switching

• alt-1 through alt-9 - Switch to workspace 1-9

Move window to workspace

• alt-shift-1 through alt-9 - Move window to workspace and follow

Monitor management

• alt-, - Focus left monitor
• alt-. - Focus right monitor
• alt-shift-, - Move workspace to left monitor
• alt-shift-. - Move workspace to right monitor

Layout controls

• alt-shift-space - Toggle floating/​tiling
• alt-f - Toggle fullscreen
• alt-shift-v - Create vertical split (for three-column layout)
• alt-shift-o - Toggle horizontal/​vertical orientation

Resize mode

• alt-r - Enter resize mode
  • h - Decrease width
  • j - Increase height
  • k - Decrease height
  • l - Increase width
  • enter or esc - Exit resize mode

Other

• alt-shift-r - Reload config
• alt-shift-q - Close window

Core concepts

Tree-based tiling

Every workspace contains a tree where:

• Containers have a layout and orientation
• Windows are leaf nodes
• Containers can be nested arbitrarily

Layout types

1. h_tiles - Horizontal tiles (side-by-side)
2. v_tiles - Vertical tiles (stacked)
3. h_accordion - Horizontal accordion (overlapping)
4. v_accordion - Vertical accordion (overlapping)

Normalization

Two automatic normalizations keep layouts sensible:

1. Single-child containers are flattened
2. Nested containers must have opposite orientations

Creating three-column layout

1. Open first window (takes full width)
2. Open second window (splits horizontally - two columns)
3. Focus second window and press alt-shift-v to create vertical split
4. Open third window (appears in the vertical split)

Result: [Window 1] [Window 2 over Window 3]

CLI reference

Overview

aerospace [-h|--help] [-v|--version] <subcommand> [<args>...]

Query commands

list-monitors - List monitors

aerospace list-monitors
aerospace list-monitors --focused
aerospace list-monitors --format '%{monitor-id} | %{monitor-name}'
aerospace list-monitors --json
aerospace list-monitors --count

list-workspaces - List workspaces

aerospace list-workspaces --all
aerospace list-workspaces --focused
aerospace list-workspaces --monitor focused
aerospace list-workspaces --monitor all --visible --empty no
aerospace list-workspaces --format '%{workspace}' --json

list-windows - List windows

aerospace list-windows --all
aerospace list-windows --focused
aerospace list-windows --workspace focused
aerospace list-windows --workspace 1
aerospace list-windows --monitor focused
aerospace list-windows --pid <pid>
aerospace list-windows --app-bundle-id <bundle-id>
aerospace list-windows --format '%{window-id} | %{app-name} | %{window-title}'
aerospace list-windows --json

list-apps - List running applications

aerospace list-apps

list-modes - List binding modes

aerospace list-modes

list-exec-env-vars - List environment variables for exec commands

aerospace list-exec-env-vars

config - Query config options

aerospace config <key>

Window management

focus - Focus window

aerospace focus left|down|up|right
aerospace focus dfs-next|dfs-prev
aerospace focus --window-id <id>
aerospace focus --dfs-index <index>
aerospace focus left --ignore-floating
aerospace focus right --boundaries workspace --boundaries-action wrap-around-the-workspace

move - Move window

aerospace move left|down|up|right
aerospace move --window-id <id> left
aerospace move right --boundaries workspace --boundaries-action stop

swap - Swap windows

aerospace swap left|down|up|right

resize - Resize window

aerospace resize smart +50           # Smart resize (larger)
aerospace resize smart -50           # Smart resize (smaller)
aerospace resize width +100          # Increase width by 100px
aerospace resize height -50          # Decrease height by 50px
aerospace resize --window-id <id> smart +50

close - Close window

aerospace close
aerospace close --window-id <id>

close-all-windows-but-current - Close all windows except current

aerospace close-all-windows-but-current

Layout commands

layout - Change layout

# Specific layouts
aerospace layout h_tiles             # Horizontal tiles
aerospace layout v_tiles             # Vertical tiles
aerospace layout h_accordion         # Horizontal accordion
aerospace layout v_accordion         # Vertical accordion

# Orientations
aerospace layout horizontal          # Change to horizontal
aerospace layout vertical            # Change to vertical

# Toggle commands (cycles through options)
aerospace layout tiles accordion              # Toggle tile vs accordion
aerospace layout horizontal vertical          # Toggle orientation
aerospace layout floating tiling              # Toggle float vs tiling

# Window-specific
aerospace layout --window-id <id> floating

join-with - Join windows under common parent

aerospace join-with left|down|up|right
aerospace join-with right            # Create nested vertical split
aerospace join-with down             # Create nested horizontal split
aerospace join-with --window-id <id> right

split - Split focused window

aerospace split horizontal|vertical

flatten-workspace-tree - Flatten workspace tree

aerospace flatten-workspace-tree

balance-sizes - Balance window sizes

aerospace balance-sizes

Fullscreen commands

fullscreen - Toggle AeroSpace fullscreen

aerospace fullscreen
aerospace fullscreen on
aerospace fullscreen off
aerospace fullscreen on --no-outer-gaps
aerospace fullscreen --window-id <id>

macos-native-fullscreen - Toggle macOS fullscreen

aerospace macos-native-fullscreen

macos-native-minimize - Minimize window

aerospace macos-native-minimize

Workspace commands

workspace - Focus workspace

aerospace workspace 1                # Switch to workspace 1
aerospace workspace next             # Next workspace
aerospace workspace prev             # Previous workspace
aerospace workspace next --wrap-around
aerospace workspace 5 --auto-back-and-forth
aerospace workspace 3 --fail-if-noop

workspace-back-and-forth - Toggle between workspaces

aerospace workspace-back-and-forth

move-node-to-workspace - Move window to workspace

aerospace move-node-to-workspace 1
aerospace move-node-to-workspace next
aerospace move-node-to-workspace prev --wrap-around
aerospace move-node-to-workspace 5 --focus-follows-window
aerospace move-node-to-workspace --window-id <id> 3

move-workspace-to-monitor - Move workspace to monitor

aerospace move-workspace-to-monitor left|down|up|right
aerospace move-workspace-to-monitor next|prev
aerospace move-workspace-to-monitor <monitor-pattern>

summon-workspace - Move workspace to focused monitor

aerospace summon-workspace 1

Monitor commands

focus-monitor - Focus monitor

aerospace focus-monitor left|down|up|right
aerospace focus-monitor next|prev
aerospace focus-monitor <monitor-pattern>
aerospace focus-monitor next --wrap-around

move-node-to-monitor - Move window to monitor

aerospace move-node-to-monitor left|down|up|right
aerospace move-node-to-monitor next|prev
aerospace move-node-to-monitor <monitor-pattern>

move-mouse - Move mouse cursor

aerospace move-mouse monitor-lazy-center
aerospace move-mouse monitor-force-center
aerospace move-mouse window-lazy-center
aerospace move-mouse window-force-center

Mode commands

mode - Activate binding mode

aerospace mode service
aerospace mode resize
aerospace mode main

trigger-binding - Trigger binding manually

aerospace trigger-binding --mode main --key alt-1

System commands

reload-config - Reload configuration

aerospace reload-config

enable - Enable/​disable window management

aerospace enable on|off|toggle

volume - Manipulate volume

aerospace volume <args>

debug-windows - Debug Accessibility API

aerospace debug-windows

Focus back-and-forth

focus-back-and-forth - Toggle focus

aerospace focus-back-and-forth

Common operations

Quick status checks

# Current workspace
aerospace list-workspaces --focused

# All windows on current workspace
aerospace list-windows --workspace focused

# All monitors
aerospace list-monitors

# Current window tree
aerospace list-windows --workspace focused --format '%{window-id} | %{app-name}'

Reload config

aerospace reload-config
# or use keybinding: alt-shift-r

Monitor patterns

Workspace assignment supports:

• main - Primary monitor
• secondary - Non-main monitor (2-monitor setups only)
• <number> - Monitor sequence (1-based, left to right)
• <regex> - Case-insensitive substring match
• '^pattern$' - Full regex match

Example:

[workspace-to-monitor-force-assignment]
1 = 'main'
2 = 'secondary'
3 = 1                    # First monitor (leftmost)
4 = 2                    # Second monitor
5 = 'built-in'           # Substring match
6 = '^dell.*'            # Regex match
7 = ['secondary', 'dell'] # Multiple patterns (fallback)

Configuration examples

Per-monitor gaps

[gaps]
# Different gaps per monitor
inner.horizontal = [{ monitor.main = 0 }, { monitor.secondary = 8 }, 5]
outer.left = [{ monitor.'built-in' = 0 }, 10]

Window callbacks

# Auto-tile all new windows
[[on-window-detected]]
if.during-aerospace-startup = false
run = 'layout tiling'

# Specific workspace behavior
[[on-window-detected]]
if.workspace = [1, 2, 3]
run = 'fullscreen on --no-outer-gaps'

# App-specific layout
[[on-window-detected]]
if.app-name-regex-substring = 'Terminal'
run = 'move-node-to-workspace 1'

Custom modes

[mode.service.binding]
esc = 'mode main'
r = ['flatten-workspace-tree', 'mode main']
f = ['layout floating tiling', 'mode main']
h = ['layout horizontal vertical', 'mode main']

[mode.main.binding]
alt-shift-semicolon = 'mode service'

Troubleshooting

Check if AeroSpace is running

ps aux | rg -i aerospace

View current workspace

aerospace list-workspaces --monitor focused --empty no

View window tree

aerospace list-windows --workspace focused --format '%{window-id} | %{app-name} | %{window-title}'

Config not loading

• Check config file location: ~/​.config/​aerospace/​aerospace.toml
• Validate TOML syntax
• Reload config: aerospace reload-config or alt-shift-r
• Check AeroSpace logs in Console.app

Keybindings not working

• Check for conflicts with other apps (Hammerspoon, Karabiner, etc.)
• Verify modifier keys are correct
• Test with: aerospace list-workspaces --monitor focused

Windows not tiling

• Check if window is floating: aerospace list-windows --workspace focused
• Toggle tiling: alt-shift-space
• Some apps force floating mode

Resources

• Repository: https://github.com/nikitabobko/AeroSpace
• Documentation: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.adoc
• Default config: https://github.com/nikitabobko/AeroSpace/blob/main/docs/config-examples/default-config.toml
• i3-like config example: https://github.com/nikitabobko/AeroSpace/blob/main/docs/config-examples/i3-like-config-example.toml