Feature proposal: get-tree and append-layout commands (i3 parity)

[glassbe]

Motivation

AeroSpace currently has no way to programmatically inspect or construct the container tree. This makes it very difficult to build tooling that arranges windows into preset layouts.

i3 on Linux solves this elegantly with three primitives:

• i3-msg -t get_tree — returns the full container hierarchy as queryable JSON
• i3-save-tree — dumps the current layout to a file
• i3-msg append_layout <file> — reconstructs the tree from a JSON layout specification

Without these, the only way to programmatically build a layout in AeroSpace is:

1. flatten-workspace-tree (reset to flat list)
2. focus --window-id + move left in a loop (reorder windows)
3. join-with bottom-up (build container hierarchy)
4. layout on each container (set tiles/accordion/orientation)
5. balance-sizes

This is fragile, slow (requires delays between commands), and limited — join-with always creates containers with the opposite orientation and tiles layout, so you must fix layouts after the fact.

Proposal

1. get-tree command

Dump the workspace tree as JSON.

aerospace get-tree [--workspace <name>]

Example output:

{
  "type": "workspace",
  "name": "1",
  "children": [
    {
      "type": "container",
      "layout": "accordion",
      "orientation": "horizontal",
      "children": [
        {
          "type": "window",
          "window-id": 1234,
          "app-bundle-id": "company.thebrowser.Browser",
          "app-name": "Arc"
        },
        {
          "type": "container",
          "layout": "accordion",
          "orientation": "vertical",
          "children": [
            { "type": "window", "window-id": 5678, "app-name": "Code" },
            {
              "type": "container",
              "layout": "tiles",
              "orientation": "horizontal",
              "children": [
                { "type": "window", "window-id": 9012, "app-name": "Ghostty" },
                { "type": "window", "window-id": 9013, "app-name": "Ghostty" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

2. append-layout command (stretch goal)

Construct a tree from a JSON layout specification, matching windows by app bundle ID.

aerospace append-layout <file.json> [--workspace <name>]

This would flatten the workspace, then build the specified tree by creating containers and binding windows to them directly — no need for the fragile join-with dance.

Existing infrastructure

The codebase already has strong foundations for this:

• FrozenTreeNode (Sources/AppBundle/tree/frozen/FrozenTreeNode.swift) — an immutable snapshot of the tree that could serve as the serialization model for get-tree
• LayoutDescription (in MoveCommandTest.swift) — a recursive enum that already serializes the tree structure for test assertions
• TilingContainer() constructor + bind()/unbindFromParent() — all the primitives needed to construct a tree programmatically for append-layout
• Json enum (Sources/AppBundle/model/Json.swift) — custom JSON serialization already used by list-windows --json

Use cases

1. Preset layouts — save and restore window arrangements per workspace
2. Session restore — recreate your layout after a restart
3. Scripting/automation — programmatically query and manipulate the tree
4. Third-party tools — layout managers, status bars, workspace visualizers

I have a working layout manager (AeroLayout) that currently uses the flatten/move/join workaround. These commands would simplify it from ~500 LOC of engine code to a single append-layout call.

Scope

I would be happy to implement this. My suggested phasing:

1. Phase 1: get-tree — add Encodable to FrozenTreeNode, create the command (~200 LOC)
2. Phase 2: append-layout — layout spec parser + tree construction (~300-400 LOC)

Would love to hear if this direction aligns with the project vision before starting on a PR.