Workspace Layers & Tab Groups

Two ways to organize related projects in ~/.lattices/workspace.json:

• Layers — switchable contexts that focus and tile windows
• Tab groups — related projects as tabs within a single terminal window

Both features are configured in the same workspace config and work together.

Tab Groups

Tab groups let you bundle related work into one Lattices tab stack. A tab can be a terminal project or a native application window such as Chrome, an editor, Notes, or a design tool. This is useful when several windows belong to one topic and should share one screen position.

Configuration

Add groups to ~/.lattices/workspace.json:

{
  "name": "my-setup",
  "groups": [
    {
      "id": "vox",
      "label": "Vox",
      "tabs": [
        { "path": "/Users/you/dev/vox", "label": "Terminal" },
        { "app": "Google Chrome", "title": "Vox", "url": "https://github.com/example/vox", "label": "Web" },
        { "app": "Visual Studio Code", "title": "vox", "launch": "Visual Studio Code", "label": "Editor" }
      ]
    }
  ]
}

Project tabs get their pane layout from their own .lattices.json. App tabs are matched by app name and optional window-title substring. url or launch tells Lattices how to open a missing app tab.

How it works

• Each project tab keeps its normal <basename>-<hash> tmux session
• Native app tabs are tracked by app and optional title
• When a layer references the group with a tile, all matched windows collapse into that slot as a cross-app tab stack
• The HUD shows a Lattices tab strip for the active layer's first group
• The split button arranges members inside the group's configured tile; press it again to collapse the windows back into their shared slot
• You can still launch projects independently: cd vox-ios && lats start creates its own standalone session as before

Tab group fields

Each tab needs either path or app.

CLI commands

lats groups                 # List all groups with status
lats group <id>             # Launch or attach to a group
lats tab <group> [tab]      # Switch tab by label or index

Examples:

lats group vox           # Launch all Vox terminal and app tabs
lats tab vox Editor      # Open the editor tab
lats tab vox 0           # Switch to first tab (by index)

Menu bar app

Tab groups appear above the project list in the menu bar panel. Each group row shows:

• Status indicator (running/stopped)
• Tab count badge
• Expand/collapse to see individual tabs
• Launch/Attach and Kill buttons
• Per-tab "Go" buttons to switch and focus a specific tab
• A grid/collapse button for changing between stack and overview

The command palette also includes group commands:

Live tab stacks

You do not need to edit workspace.json for an ad-hoc group. Open Hyperspace, select two or more windows, then right-click any selected window and choose Create Tab Group from N Windows. The same action appears when you multi-select windows in the Hyper-3 sidebar and right-click. ⌘T remains the Hyperspace keyboard shortcut. Lattices immediately stacks those existing terminal, browser, editor, or other app windows in the top-left and shows their switcher in the HUD.

Use a tab button to bring that member forward. Use the split button to arrange the members side by side inside the space reserved for the group, then press it again to collapse back to the shared slot. Hyperspace shows active stacks in the Groupings shelf at the bottom-right; Hyper-3 keeps the same groups in its bottom-right Groupings strip. The pin button restores or hides the movable floating tab tools; × on the floating tools hides them without destroying the group. Ungroup is a separate minus action. Live stacks are runtime-only; use the configured groups above when the group should return after Lattices restarts.

The Workspace Assistant understands the same selection. With windows still selected, say “stack these as tabs” or “add these up.” Agents can use the tabStacks.* daemon methods described in the Agent API.

Layers

Layers let you group projects into switchable contexts. Define up to eight layers and switch between them. A switch puts away what the new layer doesn't use, then brings its windows to the front and tiles them. Layers work like virtual desktops, without macOS Spaces: see Putting windows away.

All tmux sessions stay alive across switches. Nothing is detached, killed or closed. Layers only control which windows are showing.

Configuration

Add layers to ~/.lattices/workspace.json:

{
  "name": "my-setup",
  "layers": [
    {
      "id": "web",
      "label": "Web",
      "projects": [
        { "path": "/Users/you/dev/frontend", "tile": "left" },
        { "path": "/Users/you/dev/api", "tile": "right" }
      ]
    },
    {
      "id": "mobile",
      "label": "Mobile",
      "projects": [
        { "path": "/Users/you/dev/ios-app", "tile": "left" },
        { "path": "/Users/you/dev/backend", "tile": "right" }
      ]
    }
  ]
}

App windows in layers

Layers aren't limited to terminal sessions. You can include any application window by using the app, title, url, and launch fields instead of path:

{
  "name": "hudson",
  "layers": [
    {
      "id": "main",
      "label": "Main",
      "projects": [
        { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
        { "app": "Vox", "tile": "top-right", "launch": "open -a Vox" },
        { "path": "/Users/you/dev/frontend", "tile": "bottom-right" }
      ]
    },
    {
      "id": "docs",
      "label": "Docs",
      "projects": [
        { "app": "Google Chrome", "url": "https://docs.example.com", "tile": "left" },
        { "app": "Notes", "title": "Sprint Notes", "tile": "right" }
      ]
    }
  ]
}

When switching to a layer, lattices matches windows by app name and optionally filters by title substring or url prefix. If launch is provided and no matching window is found, the command is executed to open the app.

Using groups in layers

Layer projects can reference a tab group instead of a single path. This lets you tile a whole group into a screen position:

{
  "name": "my-setup",
  "groups": [
    {
      "id": "vox",
      "label": "Vox",
      "tabs": [
        { "path": "/Users/you/dev/vox-ios", "label": "iOS" },
        { "path": "/Users/you/dev/vox-web", "label": "Website" }
      ]
    }
  ],
  "layers": [
    {
      "id": "main",
      "label": "Main",
      "projects": [
        { "group": "vox", "tile": "top-left" },
        { "path": "/Users/you/dev/design-system", "tile": "right" }
      ]
    }
  ]
}

When this layer is launched, Lattices starts or focuses the "vox" group and stacks all of its terminal and app windows in the top-left quarter, alongside the design-system project on the right. Use the HUD tab strip to change the visible member, or its grid button to fan out the whole topic.

Layer fields

Each project entry must have either path, group, or app — pick one.

Tile values

Any tile position from the config reference works: left, right, top, bottom, top-left, top-right, bottom-left, bottom-right, left-third, center-third, right-third, maximize, center.

Layouts

Instead of a tile per entry, a layer can lay its windows out itself:

{
  "id": "web",
  "label": "Web",
  "layout": "auto",
  "projects": [
    { "app": "Ghostty", "title": "mini: web" },
    { "app": "Cursor", "title": "web" },
    { "app": "Google Chrome", "title": "localhost" }
  ]
}

A lone window sits centred at half width on an ultrawide and fills a standard display. More than three windows in a lane or column form a grid two wide.

The layout applies on the main display, to the layer's windows on the desktop it's showing, whenever you switch to the layer or choose it again. Every window an entry matches takes part, frontmost first, and the layer's first window ends up in front. Entries with their own tile or display keep their place.

Switching layers

Four ways to switch:

Every one of them switches the same way:

1. Everything the layer doesn't use is put away (see below)
2. The layer's windows are raised, matched by app / title / url
3. A layer with a layout lays out its windows

Choosing the layer you're on again gathers its windows back up.

Two extras go further, and are always asked for by name:

• Tile also moves windows with a tile value to that position: lats layer <name> --tile, or mode: "tile" in the API.
• Launch first starts the projects that aren't running, then tiles: lats layer <name> --launch, Launch Layer in the command bar, l in command mode, or mode: "launch".

The app remembers which layer was last active across restarts.

Putting windows away

A switch clears the main display before it raises the new layer:

• Hidden apps. An app with nothing in the new layer is hidden, as if you pressed ⌘H.
• Parked windows. The other windows of an app the layer does use (a second Ghostty or Chrome window, say) are parked: moved into the display's bottom-right corner, where macOS leaves a sliver showing. An app that also has windows on another display or desktop is parked rather than hidden, so those windows stay where they are. Some apps (TextEdit and other standard Cocoa windows) won't let a window go off-screen; theirs stay where they are and keep showing.
• Scenes. Each layer remembers what else it had showing, beyond its own entries, and brings it back when you return. A window you open while a layer is up comes back with that layer.

Only the main display and the desktop it's showing take part. Other displays are left alone, and a switch never reaches onto another desktop or takes you there: a layer window on another desktop stays put. Re-tiling the active layer leaves the rest of the screen alone. Everything happens at the switch; nothing runs in the background.

Exiting layers

Choose Exit Layers to return to ordinary desktop use. Lattices clears the active layer, restores windows it parked, and unhides apps it hid. Your saved layers and window assignments remain available.

lats layer exit            # Exit layers
lats layer off             # Same action

Windows stay on their existing macOS desktops. If a parked window belongs to a desktop that is not showing, Lattices keeps its saved position and retries restoration when you visit that desktop. Exiting layers does not move all windows onto the current desktop.

Choose a layer to enter layers again. Show All Windows, lats layer reveal, and lats layer show-all use the same exit action.

Named layer switching

You can switch layers by name from the CLI:

lats layer hudson           # Switch to the layer named "hudson"
lats layer 1                # Switch to the layer on ⌘⌥1
lats layer hudson --launch  # Start what isn't running, then tile

A number is a pad slot, as ⌘⌥ takes it: 1–4 and 6–9. A name is the layer's id or label, so scripts don't depend on the order.

Adding and removing windows

Any window can join a layer without editing workspace.json by hand. It's saved there as an entry of its app and its title, so it comes back after a restart; while it lives, it stays in the layer when its title changes.

lats layer add wid:1234 --to web       # default: the active layer
lats layer remove wid:1234 --from web

⌘⌥T adds the front window to the layer you're on. In the ⌘⌥Space preview, a digit sends the picked window to the layer in that slot and Delete takes it out. Hyperspace's layer piles and ⌘L write the same layers. A window held by an entry that matches other windows too (a bare app, a project) can't be taken out on its own; edit that entry instead.

Layer bezel

When you switch layers, a 3×3 grid flashes in the upper middle of the screen, numbered like Cmd+Option+1–9. Layers fill the eight slots round the middle in order: 1, 2, 3, 4, then 6, 7, 8, 9, so a ninth layer has no slot. The new layer's slot is lit, its name sits underneath, and slots without a layer stay dim. The middle slot holds the Lattices pointer, which turns to aim at the new layer's slot.

Under the name, the layer's apps are listed, one row each, then the apps of windows it had showing when you last left it. A switch only brings windows on the desktop the main display is showing, so an app whose windows are elsewhere says where, dimmed: Parked, Hidden, Put away, Desktop 2, Left display, Full screen. A running app without the layer's window says No window, and an entry with nothing running says Not open. Last, dimmed, come other layers' windows whose app kept them on screen when the switch tried to park them: Stayed.

Control+Option+Shift+arrows move to the nearest layer that way on the pad, hopping the middle: from 4, right goes to 6. At the pad's edge the grid shows the layer you're on for a moment, its lit slot bumping the way you pushed. Cmd+Option+5, or a slot without a layer, shows the layer you're on too.

Programmatic switching

Agents and scripts can switch layers via the agent API:

import { daemonCall } from '@lattices/lattices'

// List available layers
const { layers, active } = await daemonCall('layers.list')
console.log(active === null ? 'Layers off' : `Active: ${layers[active].label}`)

// Switch to a layer by index
await daemonCall('layers.switch', { index: 0 })

// Switch to a layer by name
await daemonCall('layers.switch', { name: 'hudson' })

// Exit layers while keeping saved definitions and desktop assignments
await daemonCall('layers.exit')

The layers.switch call switches as ⌘⌥ does: it puts away what the target layer doesn't use, brings its windows forward, and applies the layer's layout. Entry tile placements need mode: "tile", and mode: "launch" also opens what isn't running. Its index counts layers in list order from 0, not pad slots. A layer.switched event is broadcast to all connected clients. layers.list also reports what switches have put away, under stage, and layers.reveal brings it all back.

More methods in the Agent API reference.

Rule-backed layers

All layer definitions, including rules created in Studio, live in ~/.lattices/workspace.json. If that file is absent, Lattices imports the old ~/.lattices/layers.json once and leaves the old file unchanged. Subsequent edits belong in workspace.json. Exiting layers preserves these definitions.

Give a project entry a match clause to find windows by rule. A layer matches a window through any of its entries. Inside one clause, every present positive field must match, and every clause in not must fail.

{
  "id": "review",
  "label": "Review",
  "projects": [
    {
      "match": {
        "appEquals": "Google Chrome",
        "titleRegex": "(GitHub|Pull Request)",
        "not": [{ "titleContains": "Actions" }]
      }
    },
    { "match": { "sessionContains": "lattices" } }
  ]
}

app and titleContains match substrings. Use appEquals to match an exact app name.

One layer per window

A window belongs to one layer at most. When entries in different layers match it, the strongest claim holds it: a pin, then a match clause, a tab group, a project, and last app and title, where a longer title beats a shorter one and a bare app comes last. Ties go to the earlier layer, then the earlier entry. An entry with only launch or url finds no windows.

A window added to a layer by hand (⌘⌥T, the layer bezel, layers.assign) is saved as its app and title, with a pin:

{ "app": "Safari", "title": "Docs", "saved": true, "pins": [{ "wid": 41027, "pid": 812, "app": "Safari", "title": "Docs" }] }

An entry saved this way ("saved": true) holds windows by its pins alone: a second window with the same title stays with the layer whose rule reads it. Its app and title find a pin's window again and launch one. An entry you write has no saved and holds what its app and title match, pins or not, so adding a window to it keeps it matching the rest, and it stays when that window's pin goes. Editing a saved entry's rule in Hyperspace makes it a written one.

The pin holds the window while it lives, whatever its title turns to. A pin whose window closes while its app runs on is dropped, and a saved entry it leaves with no pins goes with it. Once the app quits, a pin whose window is gone takes the window with exactly its app and title, unless another layer's rule holds that window; a pin without a pid, saved before pins kept one, takes only a window no other layer reads. Adding a window to a layer takes the pins other layers had on it.

Layer bar

When a workspace config is loaded, a layer bar appears between the header and search field in the menu bar panel:

 lattices  2 sessions              [↔] [⟳]
┌────────────────────────────────────────┐
│  ● Web          ○ Mobile               │
│  ⌥1             ⌥2                     │
└────────────────────────────────────────┘
 Search projects...

• Active layer: filled green dot
• Inactive layers: dim outline dot
• Hotkey hints shown below each label

Layout examples

Single project

{
  "projects": [
    { "path": "/Users/you/dev/vox" }
  ]
}

No tile — just focuses the window wherever it is.

Two-project split

{
  "projects": [
    { "path": "/Users/you/dev/app", "tile": "left" },
    { "path": "/Users/you/dev/api", "tile": "right" }
  ]
}

Mixed: apps + terminals

{
  "projects": [
    { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
    { "path": "/Users/you/dev/api", "tile": "right" }
  ]
}

Group + project

{
  "projects": [
    { "group": "vox", "tile": "left" },
    { "path": "/Users/you/dev/api", "tile": "right" }
  ]
}

Four quadrants

{
  "projects": [
    { "path": "/Users/you/dev/frontend", "tile": "top-left" },
    { "path": "/Users/you/dev/backend", "tile": "top-right" },
    { "path": "/Users/you/dev/mobile", "tile": "bottom-left" },
    { "path": "/Users/you/dev/infra", "tile": "bottom-right" }
  ]
}

Tips

• Projects don't need a .lattices.json config to be in a layer — any directory path works. If the project has a config, lattices uses it; if not, it opens a plain terminal in that directory.
• App windows don't need any config at all — just specify app and optionally title or url to match the right window.
• You can have up to 9 layers (Cmd+Option+1 through Cmd+Option+9).
• Edit workspace.json by hand — the app re-reads it on launch. Use Refresh Projects in the command bar, or restart the app, to pick up changes.
• The tile field is optional. Omit it if you just want the window focused without repositioning.
• Tab groups and standalone projects can coexist in the same workspace. Use groups for related project families, standalone paths for individual projects.