AeroSpork Guide

AeroSpork needs macOS 13 or later, on Apple silicon or Intel.

The cask installs the app, links the bundled CLI onto your PATH, and installs the man pages and the bash, fish and zsh completions. Your shell may need configuring to pick up Homebrew’s completions: https://docs.brew.sh/Shell-Completion

Releases are signed with a Developer ID, notarized by Apple and stapled, so Gatekeeper accepts them on first launch and you should not see a warning.

If you do see

then the copy you have is not one of those — a build from source, or a download that was altered in transit. Prefer replacing it with a release from the releases page over dismissing the warning: right click the app in Finder and choose Open to run it anyway, which is a decision to trust that particular copy.

AeroSpork looks for a custom config in two locations:

If a config is found in more than one location, the ambiguity is reported.

Debug builds read ~/.aerospork-debug.toml / ${XDG_CONFIG_HOME}/aerospork/aerospork-debug.toml instead, so a debug build never touches the config your installed copy runs. Starting the app with --config-path <file> overrides both locations and skips the ambiguity check entirely.

The config format is TOML, which supports comments. See the TOML spec.

The default config is part of this documentation. It carries the everyday configuration keys, annotated with comments. The options it does not cover are described further down this guide. If no custom config is found, AeroSpork loads the default config.

(monitors and on-window are empty in both — the default config shows examples of each, but commented out.)

The remaining built-in defaults are accordion-padding = 30, default-root-container-layout = 'tiles', default-root-container-orientation = 'auto' and start-at-login = false (all four shown, commented out, in default-config.toml), plus six the default config does not mention at all: enable-normalization-flatten-containers = true, enable-normalization-opposite-orientation-for-nested-containers = true, auto-move-workspaces-on-monitor-connect = true, automatically-unhide-macos-hidden-apps = false, show-menu-bar-icon = true and show-dock-icon = false. after-startup-command, on-focus-changed, on-focused-workspace-changed, on-focused-monitor-changed, on-window-detected, persistent-workspaces and workspace-to-monitor-force-assignment default to empty; the exec table defaults as described under exec-* environment variables.

The safe way to start is therefore to copy the default config and edit it, rather than to write a short file and assume the rest is inherited:

Download default-config.toml

The default config above is written in the current (v2) schema: mod and workspaces generate the i3-style bindings, [keys] holds only what you add or override, and the assignment and rule sections are spelled [monitors] and [on-window]. A v1 config (everything spelled out under [mode.main.binding], workspace-to-monitor-force-assignment, ) still loads — and the first time it does, AeroSpork rewrites it to v2 in place, keeping your original next to it as <name>.pre-v2. The migration only happens when the converted file provably parses to the same configuration, and it is skipped forever once a .pre-v2 file exists — so going back to v1 sticks. One consequence to know in advance: the rewrite regenerates the file, so comments and formatting from the original survive only in the .pre-v2 copy.

How the v2 pieces layer:

`aerospork config’s manual documents the same schema from the command’s point of view.

A workspace the config declares always exists, even while it is empty and on no monitor:

A reserved name that no command could switch to, such as next, is an error.

So aerospork list-workspaces --all, the menu bar and workspace next/prev list all of them from the moment AeroSpork starts. Any other workspace, such as one you reach only through a binding of your own like alt-0 = 'workspace 10', is created when you switch to it and released once it is empty and not visible.

A declared workspace that has never been shown belongs to the main monitor, so with several monitors workspace next/prev cycle it there until you first switch to it somewhere else. After that it keeps the monitor it was last on. Across a restart, an empty one comes back on the main monitor.

AeroSpork reads ~/.aerospork.toml or ~/.config/aerospork/aerospork.toml, never AeroSpace’s ~/.aerospace.toml or ~/.config/aerospace/aerospace.toml. With only an AeroSpace file present, AeroSpork runs its default config and says so on stderr and in the config log. Copy the file across, then:

A binding key is modifiers joined to one key with -: alt-shift-h. The four modifiers are shift, ctrl, alt and cmd. Keys are named:

[gaps] puts space between windows (inner) and between windows and the screen edge (outer):

Any of the six per-direction values can also differ per monitor. The value becomes an array: one or more { monitor.<pattern> = <gap> } rules tried in order, and the array’s last element is the plain number used when nothing matches — it is required:

<pattern> accepts the same monitor descriptions as workspace assignments. The settings GUI edits flat numbers only; it warns before an edit would replace per-monitor rules, which stay a Raw TOML affair.

A binding mode is a named set of bindings. Switching to a mode deactivates every binding of the current mode and activates only the bindings of the new one. AeroSpork starts in the mode named "main".

The feature is identical to the one in i3.

A mode takes two parts: a binding that switches to it, and the declaration of the mode itself.

Commands manipulate AeroSpork and query its state.

You can use them in two ways:

For the list of available commands see: commands

By default, key bindings in the config are interpreted as the qwerty layout.

If you use a different layout or alphabet, or want an alias for an existing key, use key-mapping.key-notation-to-key-code.

The exec section configures the environment of exec-* commands and callbacks (such as exec-and-forget, 'exec-on-workspace-change' callback)

aerospork open-settings (or the menu-bar icon, or opening AeroSpork again while it runs) opens a native settings window with seven panes: General, Gaps, Keys, Monitors, Events, Window Rules and Raw TOML. The window comes to the front, and AeroSpork never tiles it or moves it to a workspace. Structured controls apply live, a moment after you stop changing them. There is no Save button, and a change still pending when you close the window is saved. A save rewrites only the sections you actually edited, so your comments and formatting survive, and a saved change takes effect on screen immediately. Raw TOML is the exception: it applies only when you click Apply, since half-typed TOML is invalid most of the time, and it is the guarantee that no config key is out of the GUI’s reach.

Every GUI save first drops a timestamped backup next to your config (<config>.toml.<yyyyMMdd-HHmmss>.backup; the five most recent are kept), and the Raw TOML pane’s Restore menu lists them. A few config shapes the structured panes cannot rewrite safely — Windows line endings, dotted or inline spellings of a managed section, multi-line arrays — are refused with a pointer to Raw TOML rather than degraded, and values richer than a pane’s controls (a hardware fingerprint, a monitor fallback list) are marked complex and preserved untouched by every save.

One related consequence worth knowing: show-menu-bar-icon = false together with show-dock-icon = false does not hide both. With no menu-bar icon the Dock icon is forced back on, so something visible always leads back into Settings. Opening AeroSpork again, or aerospork open-settings, opens Settings too.

AeroSpork has four layouts:

The tiles layout is the one shown in the previous section.

Accordion is a layout where windows are placed on top of each other.

As in a tiles layout, you navigate an accordion with the focus command: focus (left|right) in an h_accordion, focus (up|down) in a v_accordion.

Accordion padding is configurable via the accordion-padding option.

By default, AeroSpork does two types of tree normalizations:

According to the first normalization, such layout isn’t possible:

it will be immediately transformed into

According to the second normalization, such layout isn’t possible:

it will be immediately transformed into

Normalizations keep the tree structure readable from how windows are placed on screen. You can disable them:

Keep the normalizations enabled unless you have a specific reason not to.

Floating windows are not part of the tiling tree, with one exception: the focus command treats them as if they were. A floating window’s parent container is the smallest tiling container whose area contains the center of the floating window.

That removes the need for a separate binding to focus floating windows.

AeroSpork remembers which workspace each window was on and puts it back when it restarts, along with the monitor that workspace was on.

The memory is keyed on the window id issued by the macOS window server, so it holds for exactly as long as that server does. Restarting AeroSpork — an update, a crash, killall, or Quit from the menu bar — keeps it. Logging out, restarting the Mac, or quitting and relaunching an application does not: those windows are new as far as the system is concerned, and there is no way to recognise them. AeroSpork does not guess. It falls back to placing a window by where it physically sits, which is what it did before.

For windows that must land somewhere specific after their app restarts, say so explicitly with on-window-detected and if.during-aerospork-startup.

The state lives in ~/Library/Caches/com.wbs.aerospork/workspace-memory.json and is readable only by you. It is disposable: deleting it costs one restart’s worth of placement and nothing else.

The name of the active workspace is shown in the menu bar icon.

The intended workflow is to keep a single macOS Space (or one per monitor, if Displays have separate Spaces is enabled) and not to interact with macOS Spaces at all.

macOS has its own hiding, separate from workspaces: kbd:[cmd+h] hides an app, kbd:[cmd+opt+h] hides every other app. A hidden app’s windows cannot be laid out, so AeroSpork has to decide what a tiling window manager should do about them.

AeroSpork needs free space to hide windows in, so arrange your monitors such that every monitor has free space in its bottom right or left corner (System Settings → Displays → Arrange…​).

Otherwise you will see parts of hidden windows on the other monitors.

With many windows parked in the bottom corner of the screen, Mission Control draws windows smaller than the available space allows.

Enabling Group windows by application works around it:

(or in System Settings: System Settings → Desktop & Dock → Group windows by application).

macOS behaves better with Displays have separate Spaces disabled. It is enabled by default. Reported focus and performance issues with it enabled:

When Displays have separate Spaces is enabled, moving a window between monitors also moves it between Spaces, which the public APIs AeroSpork uses do not handle correctly: those APIs are not aware that Spaces exist. The fewer Spaces there are, the fewer of these problems occur.

Unless you need macOS native fullscreen in a multi-monitor setup, disable Displays have separate Spaces. Native fullscreen creates a Space of its own, which brings back the problems above.

To disable the setting:

(or in System Settings: System Settings → Desktop & Dock → Displays have separate Spaces). Logout is required for the setting to take effect.

Use the on-window-detected callback to run commands every time a new window is detected.

An example using every available option:

run commands are run only if the detected window matches all the specified conditions. If no conditions are specified then run is run every time a new window is detected.

Several callbacks can be declared in the config. The callbacks are processed in the order they are declared. By default, the first callback that matches the criteria is run, and further callbacks are not considered. (The behavior can be overridden with check-further-callbacks option)

run supports exactly three commands so far: layout floating, layout tiling and move-node-to-workspace — other layout arguments are rejected here. move-node-to-workspace may appear at most once, and only as the last command in the list. If you need another command, open an issue describing your use case.

A rule’s run list always runs to the end. The app does not have to send an event for its new window to be seen: an app that is still starting when AeroSpork first asks about it is asked again after 1, 2, 4, 8 and 16 seconds, and a window that first looks like a popup is checked again after 1 and 3 seconds, so a rule applies without clicking the window.

Available window conditions:

Ways to find an app-id:

Examples of automations:

Three callbacks track focus changes:

Combining one of them with move-mouse gives "mouse follows focus":

Don’t rely on the order the callbacks are called in. It is an implementation detail and can change between versions.

The callbacks are "recursion resistant": a focus change made inside a callback does not retrigger the callback. Changing focus from inside these callbacks is not a supported pattern, and the handling may change in future versions.

exec-on-workspace-change runs a process when the focused workspace changes. It is used for integrating with status bars.

The same hook, written with the callback that replaces it:

Besides the exec.env-vars, the process has access to the following environment variables:

For a more elaborate example on how to integrate with Sketchybar see ./goodies

Use [monitors] (spelled workspace-to-monitor-force-assignment in v1 configs — both are accepted) to pin workspaces to particular monitors.

The left hand side of the assignment is the workspace name, the right hand side is the monitor pattern.

Supported monitor patterns:

Multiple patterns can be given as an array. The first matching pattern is used.

The move-workspace-to-monitor command fails for a workspace that has a monitor assignment.

--config-path is the one to check first. If it prints a path inside the app bundle (…/AeroSpork.app/Contents/Resources/default-config.toml) then your config failed to load and AeroSpork fell back to the built-in defaults. reload-config --dry-run will then tell you why.

A hung or very busy app that stops answering Accessibility requests keeps its windows where they are: AeroSpork does not treat them as closed, and does not move focus away from them. Until the app recovers, each layout pass can wait up to a second for it, so workspace switches may feel slower.

Only one copy of AeroSpork runs at a time. Starting another, for example the binary from a terminal while the login item is running, prints AeroSpork is already running (pid N), so this copy is exiting and exits. Quit the running copy first to restart it. A debug build and a release build are separate apps and can still run side by side.

AeroSpork logs to the macOS unified log. Nothing is written to a file, and nothing needs to be turned on. The events worth diagnosing after the fact are always recorded: which version started, which config file loaded, why one didn’t, config warnings, focus AeroSpork moved on its own, the CLI socket coming up, a second copy exiting because one is already running, and any CLI command that exited non-zero.

To collect them for a bug report:

Use com.wbs.aerospork.debug for a debug build. The .debug there names the build, not the log level: a release build always logs under com.wbs.aerospork, whatever level it writes at. Records are tagged with a category, so you can narrow them down:

Redirect to a file to attach it: log show … > aerospork.log.

The always-on records above are deliberately sparse. For a per-refresh, per-command trace, set AEROSPORK_DEBUG_LOG and restart the app:

For a debug build every name changes, including the one open needs. open -a AeroSpork would launch the release app next to it:

To confirm the variable actually reached the app, look for the startup record. It is written at notice level, so it survives. It was added in 1.2.0; earlier versions do not write it, so on those the only check is whether the stream shows anything.

If it says off, the variable did not reach the app and the trace will be empty no matter what you stream.

Three things to know about it:

Turn it back off with launchctl unsetenv AEROSPORK_DEBUG_LOG and restart, or the trace keeps running for as long as the app does.