Release / 7 Jul 2026 / with v0.21.0-Beta, v0.21.1-Beta

AeroSpace v0.21.2-Beta

Combine window commands with conditions and pipes in keyboard bindings.

Before you upgrade to v0.21.2-Beta

7 to fix

For an unconditional `on-window-detected` rule that stops processing, add `if = 'true'`; omitting `if` is accepted only with `check-further-callbacks = true`.

Action requiredRun rules when windows appear and commands when focus changes.Affects: Window-detected rules with no condition and no check-further-callbacks setting.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/Sources/AppBundle/config/parseOnWindowDetected.sw…

Legacy `on-window-detected` conditions such as `if.app-id` are soft-deprecated but still supported; command predicates such as `if = 'test ...'` are documented replacements.

Behavior changedRun rules when windows appear and commands when focus changes.

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/docs/guide.adoc

Quote literal reserved characters in binding and callback command arguments, separate quoted words with spaces, and escape command-line continuations with a backslash.

Action requiredConfigure keyboard shortcuts and binding modes in a text file.Affects: Bindings and callbacks whose arguments relied on the old command parser.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/Sources/AppBundle/shell/shellLexer.swift

Add `--fail-if-noop` when scripts need `layout` to return a failure for an unchanged layout; by default an unchanged layout now succeeds.

Action requiredArrange and resize windows in nested tiles or accordion layouts.Affects: Scripts branching on layout's previous no-op failure status.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/docs/aerospace-layout.adoc

Configuration reloads can apply valid settings despite minor errors; warnings go to stderr, while `--warnings-as-errors` reports them as errors.

Behavior changedConfigure keyboard shortcuts and binding modes in a text file.Inferred

Read the evidence

Update custom socket clients to exchange a four-byte protocol version of 1 before sending length-prefixed JSON requests.

Action requiredQuery windows, workspaces, monitors and applications from scripts.Affects: Custom clients using AeroSpace's Unix socket directly.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/docs/guide.adoc

Update scripts that require an exact generic-error exit code: generic errors now use 2; test conditions distinguish false from errors.

Action requiredQuery windows, workspaces, monitors and applications from scripts.Affects: Scripts interpreting specific numeric exit codes.Inferred

Read the evidence

nikitabobko/AeroSpace/compare/v0.20.3-Beta...v0.21.0-Beta

Install Bash 5 and use the repository's Swift 6.3.2 toolchain when building this release from source.

Action requiredAffects: Users building AeroSpace from source.Inferred

Read the evidence

Replace unframed JSON reads and writes with a four-byte little-endian payload length followed by UTF-8 JSON, in both directions, after the version handshake.

Action requiredQuery windows, workspaces, monitors and applications from scripts.Affects: Custom clients using the pre-0.21 unframed JSON socket protocol.Inferred

Read the evidence

What changed in v0.21.2-Beta

The built-in shell supports sequences, conditions and pipes, with `eval` for CLI use; `subscribe`, `run-callback`, automatic config reload and mouse-driven focus are also available.

v0.21.2-Beta; Beta for macOS 13+, available as a GitHub release archive; Accessibility permission required.

New things you can do

Combine window-management commands with conditions, sequences and pipes.

Added

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/docs/guide.adoc

Focus windows by moving the pointer over them.

AddedInferred

Read the evidence

Fixed and improved

Set `auto-reload-config = true` and reload once manually to reload configuration on file saves.

ImprovedConfigure keyboard shortcuts and binding modes in a text file.

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.0-Beta/docs/config-examples/default-config.toml

Use command predicates in `on-window-detected`; `run-callback on-window-detected --for-every-window` reapplies rules to existing windows and exposes callback output.

ImprovedRun rules when windows appear and commands when focus changes.

Read the evidence

Set layouts on empty workspaces or use `layout --workspace NAME --root`; directional `focus` and `move` can refuse to leave fullscreen windows.

ImprovedArrange and resize windows in nested tiles or accordion layouts.

Read the evidence

`--no-stdin` no longer reads input; `workspace next/prev --stdin` can choose the first listed workspace when the current workspace is absent from the list.

Now worksSwitch between virtual workspaces without animations.Inferred

Read the evidence

nikitabobko/AeroSpace/compare/v0.20.3-Beta...v0.21.0-Beta

Mouse-driven focus respects fullscreen windows and ignores pointer positions that do not identify a normal window.

Now worksFocus windows by moving the pointer over them.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.1-Beta/Sources/AppBundle/mouse/focusFollowsMouse.swift

Menu-bar clicks no longer steal focus when Displays have separate Spaces is off; keyboard focus no longer interleaves floating windows between every accordion window.

Now worksArrange and resize windows in nested tiles or accordion layouts.Inferred

Read the evidence

nikitabobko/AeroSpace/compare/v0.21.0-Beta...v0.21.1-Beta

Restoring a floating window preserves its latest size so it is not nudged away from the right or bottom screen edge.

Now worksKeep selected windows floating above the tiled layout.Inferred

Read the evidence

nikitabobko/AeroSpace/blob/v0.21.2-Beta/Sources/AppBundle/tree/MacWindow.swift

Seeded by @iluxav with Codex, from the release's public sources. Each change links to its evidence.

Before you upgrade to v0.21.2-Beta

For an unconditional `on-window-detected` rule that stops processing, add `if = 'true'`; omitting `if` is accepted only with `check-further-callbacks = true`.

Legacy `on-window-detected` conditions such as `if.app-id` are soft-deprecated but still supported; command predicates such as `if = 'test ...'` are documented replacements.

Quote literal reserved characters in binding and callback command arguments, separate quoted words with spaces, and escape command-line continuations with a backslash.

Add `--fail-if-noop` when scripts need `layout` to return a failure for an unchanged layout; by default an unchanged layout now succeeds.

Configuration reloads can apply valid settings despite minor errors; warnings go to stderr, while `--warnings-as-errors` reports them as errors.

Update custom socket clients to exchange a four-byte protocol version of 1 before sending length-prefixed JSON requests.

Update scripts that require an exact generic-error exit code: generic errors now use 2; test conditions distinguish false from errors.

Install Bash 5 and use the repository's Swift 6.3.2 toolchain when building this release from source.

Replace unframed JSON reads and writes with a four-byte little-endian payload length followed by UTF-8 JSON, in both directions, after the version handshake.

What changed in v0.21.2-Beta

New things you can do

Combine window-management commands with conditions, sequences and pipes.

Receive window, focus, workspace, mode and binding events as JSON lines.

Focus windows by moving the pointer over them.

Fixed and improved

Set `auto-reload-config = true` and reload once manually to reload configuration on file saves.

Use command predicates in `on-window-detected`; `run-callback on-window-detected --for-every-window` reapplies rules to existing windows and exposes callback output.

Set layouts on empty workspaces or use `layout --workspace NAME --root`; directional `focus` and `move` can refuse to leave fullscreen windows.

`--no-stdin` no longer reads input; `workspace next/prev --stdin` can choose the first listed workspace when the current workspace is absent from the list.

Mouse-driven focus respects fullscreen windows and ignores pointer positions that do not identify a normal window.

Menu-bar clicks no longer steal focus when Displays have separate Spaces is off; keyboard focus no longer interleaves floating windows between every accordion window.

Restoring a floating window preserves its latest size so it is not nudged away from the right or bottom screen edge.