Sessions, server & update

session

beswarm session start --name <name>       # start or reattach a named session
beswarm session attach --name <name>      # launch or attach to it
beswarm session list                      # sessions on disk
beswarm session close --name <name>       # kill one session's shells; layout kept
beswarm session clear [--yes] [--force]   # delete every session except 'default'
beswarm session reset [--yes] [--force]   # remove all workspaces and tabs from 'default'; settings kept

session close is server stop for one named session: it kills that session's helpers and shells, and the saved layout stays on disk, so starting the session again restores its tabs. A name with no session on disk is an error.

session clear is destructive and can't be undone. It confirms unless --yes, and skips sessions someone is attached to unless --force.

session reset empties the default session: it kills its helpers and drops every workspace and tab from the saved layout, keeping its settings. It can't be undone either. It confirms unless --yes, and refuses while a TUI is attached to default unless --force — an attached TUI would write its workspaces straight back on its next save.

--session

--session <name> selects the session a command acts on (default: $BESWARM_SESSION when set — as it is for every plugin run — else default). It's valid on agent, server, workspace, worktree, status, skill, prompt, sound, terminal, and plugin run, view and history.

It's not for launching — use session start --name or session attach --name for that.

status

beswarm status [server|client]

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

server

beswarm server stop           # kill every tab helper and shell; saved layout kept
beswarm server reload-config  # always fails by design

Settings live in workspaces.json, so reload-config intentionally refuses.

terminal

beswarm terminal list [--json]
beswarm terminal add   --name <name> --workspace <ws>
beswarm terminal add   --name <name> --worktree <wt> [--workspace <ws>]
beswarm terminal close --name <terminal> --workspace <ws>
beswarm terminal close --name <terminal> --worktree <wt> [--workspace <ws>]

Subcommand	What it does
`list`	Every tab: terminal id, title, and the workspace and worktree it belongs to (`-` for none).
`add`	Opens a tab titled `<name>` and focuses it — in the workspace's own tab bar at its directory, or in an existing worktree's sub-item at its checkout. A worktree takes only its first terminal: `--worktree` is refused while it already has one.
`close`	Closes a tab and kills its shell. `--name` is a terminal id or tab title — never an agent name. `--workspace` alone matches the workspace's own tabs, `--worktree` the worktree's. A title shared by several tabs in scope is refused; pass the id. Closing the last tab opens a fresh one.

--workspace with --worktree picks between workspaces that each have a worktree by that name.

beswarm terminal add --name logs --workspace api
beswarm terminal add --name tests --worktree fix-login
beswarm terminal close --name 18d47dc212160d20-1 --workspace api
beswarm terminal close --name tests --worktree fix-login

To stop an agent but keep its tab, use agent stop; follow with terminal close when the tab should go too.

Error codes: workspace_not_found, worktree_not_found, agent_not_found (close, no such terminal), invalid_request (a title matching several tabs, or a worktree that already has a terminal).

update

beswarm update [--handoff]

Downloads and installs the latest version. --handoff restarts into the new binary.

Help

beswarm --help            # every command, and sessions in full
beswarm <command>         # the manual for agent, terminal, workspace, worktree, skill, prompt, tool, artifact, plugin, sound or server
beswarm <command> --help  # same manual
beswarm skill system      # the built-in skill for agents driving beswarm
beswarm --version

Don't run bare beswarm to explore — it launches or attaches the TUI.