Automate the arrangement of windows into complex, repeatable layouts using aerospace.
This project is a script that drives the excellent aerospace
window-manager CLI.
You describe a layout once (in JSON), then run the script whenever you need that workspace restored.
- Launches apps if they are not already running.
- Moves / focuses windows into the requested workspace.
- Supports nested horizontal & vertical groups for sophisticated tiling.
- Falls back to a configurable "stash" workspace so your primary workspace starts clean.
- One-line listing of all available layouts.
- Optional fractional sizing for windows and groups via a simple
size
field (e.g."size": "2/3"
). - Supports multi-display setups with the
display
field to correctly calculate window sizes, in a per-layout basis.
You can install aerospace-layout-manager
with a single command:
curl -sSL https://raw.githubusercontent.com/CarterMcAlister/aerospace-layout-manager/main/install.sh | bash
This script will automatically detect your operating system and architecture, download the correct release binary, and place it in /usr/local/bin
.
{
"stashWorkspace": "S",
"layouts": {
"work": {
"workspace": "1",
"layout": "v_tiles",
"orientation": "vertical",
"windows": [
{ "bundleId": "com.apple.Safari" },
{
"orientation": "horizontal",
"windows": [
{ "bundleId": "com.jetbrains.WebStorm", "size": "2/3" },
{ "bundleId": "com.apple.Terminal", "size": "1/3" }
]
}
]
}
}
}
Field reference:
- stashWorkspace – workspace whose windows will be used as temporary storage.
- layouts → each key is a layout name you can invoke.
- workspace – target workspace (string or number) for the layout.
- layout – one of Aerospace's layout names (
tiles
,h_tiles
,v_tiles
,floating
, …). - orientation – default orientation for nested groups (
horizontal
orvertical
). - windows – recursive array of:
{ "bundleId": "…", "size": "n/d" }
– an application window, optionally sized as a fraction.{ "orientation": "horizontal" | "vertical", "size": "n/d", "windows": [ … ] }
– a nested group, optionally sized as a fraction.
- size – (optional) fractional width/height (
"numerator/denominator"
). In a horizontal context (orientation: "horizontal"
) the fraction controls width; in a vertical context it controls height. - display – (optional) display name or ID (as shown by
system_profiler SPDisplaysDataType
), or a valid alias (main
,secondary
,external
,internal
).- In multi-display setups, you can specify the target display for a layout in order to correctly calculate window sizes (if specified with
size
). By default, the layout will be applied to the primary display.
- In multi-display setups, you can specify the target display for a layout in order to correctly calculate window sizes (if specified with
Once installed, you can use the aerospace-layout-manager
command.
First, add a layouts file to ~/.config/aerospace/layouts.json
. See the Configuration section for details.
aerospace-layout-manager --listLayouts
# or: aerospace-layout-manager -L
# by long option
aerospace-layout-manager --layout work
# by short option
aerospace-layout-manager -l work
# or simply pass the name as a positional argument
aerospace-layout-manager work
aerospace-layout-manager --configFile ~/my-layouts/presentation.json -l keynote
- Clear – moves every window currently in the target workspace to
stashWorkspace
. - Move – ensures each app is running, then moves its first window into the layout's workspace, depth-first.
- Reposition – flattens the workspace, sets the requested layout type, and joins / splits panes according to the JSON hierarchy.
- Resize - sets the windows to the fractional sizes, if specified
- Focus – switches to the fully-arranged workspace.
The logic lives in index.ts
and is intentionally kept readable if you need to tweak timings or behaviour.