Sessions, windows and panes

The tmux model the apps show, how every screen gets its own view of one session, and what survives a dropped connection or a dead tmux.

What the apps and the browser list is tmux's own structure. st does not add a layer of its own on top.

• A session is a set of windows with a name. A machine can have several.
• A window is one screen of a session: a tab in the desktop app and the web terminal, a row in the phone apps' window list.
• A pane is a part of a window, split side by side or one above the other. An agent runs in a pane, and its id (%3) is how st and the orchestration commands name it.

The shared session

st shares one session by name: default, or the one you give with st --session <name>. When it has to make it and someone is at the terminal, it asks for a name first, with the default one keystroke away. Names are letters, digits, - and _.

The apps list every tmux session on the machine, not only that one, and st watches the agents in all of them. st attach puts the terminal you are sitting at into the shared session.

Many screens, one session

The desktop app, two phones and a browser can all be on one session at once. None of them attaches to it directly: each gets its own view inside the same tmux session group. So each has its own current window:

• On different windows, each screen gets its own size. A phone looking at one window does not shrink the desktop's.
• On the same window, there is one size for everybody: tmux gives a window one size. The last one to act sets it, and a page narrower than the window shrinks its type until the lines fit.

What you type goes into the same shells, so everyone sees it at once. zellij has no session groups: there, a second screen shares the first one's size. Multiplexers has the details.

Sessions outlive connections

A session belongs to tmux. Closing the tab, locking the phone, losing the network, quitting the desktop app, even st exit: the session and every program in it keep running, and the next connection finds them as they were. st ls lists the sessions and who is on each right now.

The exception is --mux none, which has no multiplexer to keep the shell: a dropped connection ends it.

Restoring after a tmux crash

A tmux server that dies takes its programs with it. st keeps a snapshot of the server every 10 seconds (the last five are kept) and, when it finds a different server from the one it last saw, sets the sessions up again: names, windows, layouts, folders. Claude Code and Codex panes continue their conversation: st types the resume line and presses Enter when the conversation is saved on the machine. Nothing else is run again, and the window is marked restored in the apps. After a restart of the computer, st asks first instead of restoring by itself.

st restore --pending     # waiting after a restart
st restore --list        # the snapshots kept
st restore --dry-run     # what a restore would do
st restore --from <id>   # restore one by hand

This is tmux only; zellij keeps its own sessions. The details, and how to turn it off, are in Multiplexers.

New sessions and windows

• Desktop app: + New session in the sidebar, + beside the window tabs, ⌘N for a session.
• Phone apps: New session on the Sessions tab, New window in a session's window sheet. New window also offers the coding agents on the machine: pick one, add a first prompt if you like, and st opens the window, starts the agent and types the prompt (st 0.3.58 or later).
• Web terminal: + New session in the sidebar.
• A terminal on the machine: plain tmux works, and so does st --session <name>.

A new window or split made from the apps or the web terminal opens in the folder of the pane you are looking at (tmux, st 0.3.101 or later). If that folder has gone, it opens where it always did, the session's start folder (usually the home directory), so it always opens. zellij is unchanged.

Closing a window or a session from any of them asks first, and names the programs and agents still running in it.

Naming

A window's name is tmux's, so renaming it anywhere renames it everywhere: double-click its tab or its sidebar row in the desktop app or the web terminal, or long-press it in the phone apps. A worker's window is named by the coordinator that started it.

A machine's name is separate: it is what the account calls the machine (Accounts and links).