Sessions & workspaces

BeSwarm organizes your work in four levels:

Level	What it is
Session	A named, persistent set of workspaces and tabs. `default` always exists.
Workspace	One sidebar entry: a name, a directory, and the tabs it owns.
Worktree	A second checkout of a workspace's repository, on its own branch. See Worktrees.
Tab	A terminal. It exists whether or not it hosts an agent.

Tabs outlive the TUI

Each tab is a detached helper process that owns its PTY. When you quit the TUI, the helpers — and the shells and agents inside them — keep running. Running beswarm again reattaches to whatever is still there.

To really stop everything in a session:

beswarm server stop

This kills every tab helper and shell. The saved layout is kept.

Named sessions

beswarm session start --name payments   # start or reattach
beswarm session attach --name payments  # launch or attach
beswarm session list                    # sessions on disk

Most commands act on the default session. Pass --session <name> to target another one — BeSwarm injects no session context into its tabs, so pass it explicitly on every command when you're not in default.

Workspaces

beswarm workspace list
beswarm workspace add --name api --path ~/code/api
beswarm workspace remove --name api --yes

add creates a workspace and its first terminal. --path defaults to the current directory.
remove closes every terminal the workspace owns, and is refused without --yes while it owns any.

Check the state

beswarm status

status shows this client's saved state and the helpers running for the session, with terminal ids.