Configuration

.lattices.json

Place a .lattices.json file in your project root to define your workspace layout. lattices reads this file when creating a session.

Minimal example

{
  "panes": [
    { "name": "shell" },
    { "name": "server", "cmd": "pnpm dev" }
  ]
}

Full example

{
  "ensure": true,
  "panes": [
    { "name": "shell", "size": 60 },
    { "name": "server", "cmd": "pnpm dev" },
    { "name": "tests",  "cmd": "pnpm test --watch" }
  ]
}

Config fields

ensure and prefill are mutually exclusive. If both are set, ensure takes priority.

• ensure — when you reattach to an existing session, lattices checks each pane. If a pane's process has exited and the shell is idle, lattices automatically re-runs its declared command.
• prefill — same check, but the command is typed into the pane without pressing Enter. You review and hit Enter yourself.

Pane fields

• size only applies to the first pane. It sets the width of the main pane as a percentage. Default is 60.
• cmd can be any shell command. If omitted, the pane opens a shell.
• name is used in the lats app to show a summary of your layout, and as a target for lats restart <name>.

Layouts

lattices picks a layout based on how many panes you define:

2 panes — side by side

┌──────────┬─────────┐
│  shell   │ server  │
│  (60%)   │ (40%)   │
└──────────┴─────────┘

Horizontal split. First pane on the left, second on the right.

3+ panes — main-vertical

┌──────────┬─────────┐
│  shell   │ server  │
│  (60%)   ├─────────┤
│          │ tests   │
└──────────┴─────────┘

First pane takes the left side. Remaining panes stack vertically on the right.

4 panes

┌──────────┬─────────┐
│  shell   │ server  │
│  (60%)   ├─────────┤
│          │ tests   │
│          ├─────────┤
│          │ logs    │
└──────────┴─────────┘

Auto-detection (no config)

If there's no .lattices.json, lattices still works. It will:

1. Create a 2-pane layout (60/40 split)
2. Open a shell in the left pane
3. Auto-detect your dev command from package.json scripts and run it on the right:
   • Looks for: dev, start, serve, watch (in that order)
   • Detects package manager: bun > pnpm > yarn > npm

Creating a config

Run lats init in your project directory to generate a starter .lattices.json based on your project. The generated config includes "ensure": true by default.

CLI commands

Aliases: ls/list, kill/rm, sync/reconcile, restart/respawn, tile/t.

Keyboard remaps

The menu bar app can create a lightweight keyboard layer from ~/.lattices/keyboard-remaps.json. The default config is:

{
  "rules": [
    {
      "enabled": true,
      "from": "caps_lock",
      "id": "caps_lock_hyper_escape",
      "toIfAlone": "escape",
      "toIfHeld": "hyper"
    }
  ]
}

It is enabled by default and can be turned off from Settings -> General -> Keyboard remaps. Hold Caps Lock to send Hyper (Control + Option + Shift + Command), or tap Caps Lock alone to send Escape.

Machine-readable output

--json flag

lats windows --json returns the raw window array. lats map --json returns a versioned, per-display current-Space snapshot with coordinate metadata:

lats windows --json
lats map --json

Both are useful for piping into jq or consuming from scripts.

Daemon responses

All agent API calls return JSON natively. If you need structured data from lattices, the daemon is easier than parsing stdout. See the API reference.

Exit codes

Recovery

sync

lats sync

Reconciles a running session to match the declared config:

1. Counts actual panes vs declared panes
2. Recreates any missing panes
3. Re-applies the layout (main-vertical with correct width)
4. Restores pane labels
5. Re-runs declared commands in any idle panes

Use when a pane was killed and you want to get back to the declared state without killing the whole session.

restart

lats restart [target]

Kills the process in a specific pane and re-runs its declared command. The target can be:

• A pane name (case-insensitive): lats restart server
• A 0-based index: lats restart 1
• Omitted (defaults to pane 0): lats restart

The restart sequence: send Ctrl-C, wait 0.5s, check if the process stopped. If it's still running, escalate to SIGKILL on child processes. Then send the declared command.

Tile positions

The lats tile command moves the frontmost window to a preset screen position. Available positions:

Aliases: left-half/left, right-half/right, top-half/top, bottom-half/bottom, max/maximize.

Tiling respects the menu bar and dock. It uses the visible desktop area, not the full screen.

For arbitrary cells, use compact CxR:c,r with 1-indexed coordinates from the top-left, or canonical grid:CxR:c,r with 0-indexed coordinates. Example: lats tile 4x4:1,2.

When the menu bar app is running, lats tile routes through the daemon's canonical windows.place and reports a verified receipt. Without the daemon it falls back to AppleScript (frontmost app, primary display) and says so.

Moving a specific window

lats tile always targets the frontmost window. To move a specific window — by the CGWindowID shown in lats map or lats windows — use lats window move / lats window place (daemon required):

lats window move 4182 --display 1                  # keep relative size/position
lats window move 4182 --display 1 --placement right
lats window place 4182 top-left                    # slot on its current display
lats window move 4182 --display 0 --dry-run --json       # plan without moving

A malformed wid is an error; these commands never fall back to the frontmost window. Slots are the named positions above plus grid placements; fractional typed placements remain available via lats call windows.place.

Smart app tiling

Use lats tile family when you want lattices to arrange a whole window family instead of just moving the frontmost window.

Examples:

lats tile family
lats tile family right
lats tile family iTerm2
lats tile family "Google Chrome" left

• With no app name, family means the frontmost app. If iTerm is frontmost, lattices grids your visible iTerm windows.
• If you pass a region (left, right, top, bottom, etc.), the smart grid is constrained to that part of the screen.
• lats distribute uses the same smart grid engine, but defaults to all visible windows instead of the current app family.