Sessions

A session is a tmux session that Lattices creates for one project directory. The project declares its panes in a .lattices.json file. lats start builds the panes, runs their commands and attaches your terminal. The session keeps running after you detach or close the terminal.

Sessions need tmux (brew install tmux). Window tiling, search, layers and the agent API work without tmux.

The examples use an invented project, tideline, at ~/dev/tideline.

How a session is named

Lattices derives the session name from the directory:

<directory basename>-<first 6 hex characters of sha256(absolute path)>

~/dev/tideline becomes something like tideline-3f9a1c. The hash makes two checkouts with the same basename distinct. Lattices tags the terminal window's title with [lattices:tideline-3f9a1c], which is how the app and lats search find the window later.

Declare the panes

Create a starter config:

cd ~/dev/tideline
lats init

lats init writes .lattices.json with "ensure": true and either two panes or one. It writes two panes when package.json has a dev, start, serve or watch script, checked in that order, and it picks the package manager by lockfile: bun, then pnpm, then yarn, then npm. Without such a script it writes a single shell pane.

A config for tideline with a shell, a dev server and a test watcher:

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

ensure and prefill are exclusive. When both are set, ensure wins.

The pane count picks the layout:

A directory with no .lattices.json still starts. Lattices uses the same two-pane or one-pane default that lats init would write, without saving it.

Start, detach, reattach

cd ~/dev/tideline
lats start

Expected: tmux opens with the declared panes and each cmd running. If the session already exists, lats start reattaches instead of rebuilding it.

Detach with Ctrl+B then D. The panes and their processes keep running.

Run lats start again from the same directory to reattach. With ensure set, a pane whose command has exited restarts on reattach. With prefill set, the command is typed into the pane for you to review and run.

lats on its own prints the directory's session name, config and app status. It does not attach.

lats tmux is an alias for lats start.

See what is running

lats ls          # tmux sessions, with their tab group when they have one
lats status      # managed and unmanaged sessions
lats sessions    # sessions as the daemon sees them; --json for scripts

lats ls prints No active sessions. when tmux has none.

Repair a session

Restart one pane's command:

lats restart server   # by name, case-insensitive
lats restart 1        # by 0-based index
lats restart          # pane 0

lats restart sends Ctrl-C, waits half a second, escalates to SIGKILL on the pane's child processes if needed, then sends the declared command.

Rebuild missing panes without killing the session:

lats sync

lats sync counts the panes, recreates missing ones, reapplies the layout, restores the labels and re-runs declared commands in idle panes. Use it after you closed a pane by hand.

Kill a session:

lats kill            # the current directory's session
lats kill tideline-3f9a1c

Find the session's window

lats focus tideline-3f9a1c

lats focus raises the terminal window that carries the session tag and switches to its Space when needed. Use lats search tideline --deep when you do not know the session name; see Finding windows.

The command bar (Control+Option+Space) lists every project that has a .lattices.json. The app scans ~/dev, ~/Developer, ~/projects and ~/src three levels deep for those files.

Exit codes

Related

• Configuration: the full .lattices.json and CLI reference.
• Layers: group a session's terminal with its editor and browser.
• Concepts: how naming and window discovery work underneath.