{"id":28794211,"url":"https://github.com/cartermcalister/aerospace-layout-manager","last_synced_at":"2026-02-09T04:08:50.744Z","repository":{"id":298201525,"uuid":"997521576","full_name":"CarterMcAlister/aerospace-layout-manager","owner":"CarterMcAlister","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-09T23:16:58.000Z","size":11,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-09T23:32:39.731Z","etag":null,"topics":["aerospace","layout-manager","mac","macos","tiling-window-manager","window-manager"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CarterMcAlister.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-06T17:10:10.000Z","updated_at":"2025-06-09T23:22:08.000Z","dependencies_parsed_at":"2025-06-09T23:32:42.968Z","dependency_job_id":"6b68eeab-ff2c-49f0-8466-c9ce717a4782","html_url":"https://github.com/CarterMcAlister/aerospace-layout-manager","commit_stats":null,"previous_names":["cartermcalister/aerospace-layout-manager"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/CarterMcAlister/aerospace-layout-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterMcAlister%2Faerospace-layout-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterMcAlister%2Faerospace-layout-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterMcAlister%2Faerospace-layout-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterMcAlister%2Faerospace-layout-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CarterMcAlister","download_url":"https://codeload.github.com/CarterMcAlister/aerospace-layout-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterMcAlister%2Faerospace-layout-manager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260471631,"owners_count":23014255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aerospace","layout-manager","mac","macos","tiling-window-manager","window-manager"],"created_at":"2025-06-18T02:05:16.783Z","updated_at":"2026-02-09T04:08:50.738Z","avatar_url":"https://github.com/CarterMcAlister.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aerospace Layout Manager\n\nAutomate the arrangement of windows into complex, repeatable layouts using aerospace.\n\nThis project is a script that drives the excellent [`aerospace`](https://github.com/nikitabobko/AeroSpace) window-manager CLI.  \nYou describe a layout once (in JSON), then run the script whenever you need that workspace restored.\n\n---\n\n## ✨ Features\n\n* Launches apps if they are not already running.\n* Moves / focuses windows into the requested **workspace**.\n* Supports nested horizontal \u0026 vertical groups for sophisticated tiling.\n* Falls back to a configurable \"stash\" workspace so your primary workspace starts clean.\n* One-line listing of all available layouts.\n* Optional **fractional sizing** for windows and groups via a simple `size` field (e.g. `\"size\": \"2/3\"`).\n* Supports **multi-display setups** with the `display` field to correctly calculate window sizes, in a per-layout basis.\n\n---\n\n## 🚀 Installation\n\nYou can install `aerospace-layout-manager` with a single command:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/CarterMcAlister/aerospace-layout-manager/main/install.sh | bash\n```\n\nThis script will automatically detect your operating system and architecture, download the correct release binary, and place it in `/usr/local/bin`.\n\n## 🔧 Configuration (`layouts.json`)\n\n```json\n{\n  \"stashWorkspace\": \"S\",\n  \"layouts\": {\n    \"work\": {\n      \"workspace\": \"1\",\n      \"layout\": \"v_tiles\",\n      \"orientation\": \"vertical\",\n      \"windows\": [\n        { \"bundleId\": \"com.apple.Safari\" },\n        {\n          \"orientation\": \"horizontal\",\n          \"windows\": [\n            { \"bundleId\": \"com.jetbrains.WebStorm\", \"size\": \"2/3\" },\n            { \"bundleId\": \"com.apple.Terminal\", \"size\": \"1/3\" }\n          ]\n        }\n      ]\n    }\n  }\n}\n```\n\nField reference:\n\n* **stashWorkspace** – workspace whose windows will be used as temporary storage.\n* **layouts** → each key is a layout name you can invoke.\n  * **workspace** – target workspace (string or number) for the layout.\n  * **layout** – one of Aerospace's layout names (`tiles`, `h_tiles`, `v_tiles`, `floating`, …).\n  * **orientation** – default orientation for nested groups (`horizontal` or `vertical`).\n  * **windows** – recursive array of:\n    * `{ \"bundleId\": \"…\", \"size\": \"n/d\" }` – an application window, optionally sized as a fraction.\n    * `{ \"orientation\": \"horizontal\" | \"vertical\", \"size\": \"n/d\", \"windows\": [ … ] }` – a nested group, optionally sized as a fraction.\n  * **size** – *(optional)* fractional width/height (`\"numerator/denominator\"`). In a horizontal context (`orientation: \"horizontal\"`) the fraction controls width; in a vertical context it controls height.\n  * **display** – *(optional)* display *name* or *ID* (as shown by `system_profiler SPDisplaysDataType`), or a valid alias (`main`, `secondary`, `external`, `internal`).\n    * 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.\n\n---\n\n## ▶️  Usage\n\nOnce installed, you can use the `aerospace-layout-manager` command.\n\nFirst, add a layouts file to `~/.config/aerospace/layouts.json`. See the [Configuration](#-configuration-layoutsjson) section for details.\n\n### List available layouts\n\n```bash\naerospace-layout-manager --listLayouts\n# or: aerospace-layout-manager -L\n```\n\n### Apply a layout\n\n```bash\n# by long option\naerospace-layout-manager --layout work\n\n# by short option\naerospace-layout-manager -l work\n\n# or simply pass the name as a positional argument\naerospace-layout-manager work\n```\n\n### Use an alternate config file\n\n```bash\naerospace-layout-manager --configFile ~/my-layouts/presentation.json -l keynote\n```\n\n---\n\n## ⚙️  How it works (high level)\n\n1. **Clear** – moves every window currently in the target workspace to `stashWorkspace`.\n2. **Move** – ensures each app is running, then moves its first window into the layout's workspace, depth-first.\n3. **Reposition** – flattens the workspace, sets the requested layout type, and joins / splits panes according to the JSON hierarchy.\n4. **Resize** - sets the windows to the fractional sizes, if specified\n5. **Focus** – switches to the fully-arranged workspace.\n\nThe logic lives in [`index.ts`](./index.ts) and is intentionally kept readable if you need to tweak timings or behaviour.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartermcalister%2Faerospace-layout-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcartermcalister%2Faerospace-layout-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcartermcalister%2Faerospace-layout-manager/lists"}