workspace & worktree

Both command groups talk to the running TUI over the session's control socket, so they need a running session. Address workspaces and worktrees by name, always through --name / --workspace flags. --workspace is required on every worktree subcommand except list.

workspace

beswarm workspace list [--json]
beswarm workspace add --name <name> [--path <dir>]
beswarm workspace remove --name <name> [--yes]

list shows each workspace's name, git branch, terminal count and directory.
add creates a workspace and its first terminal, like the sidebar's "new" button. --path defaults to the current directory. Refused if the name is taken or the directory is missing.
remove closes every terminal the workspace owns; refused without --yes while it owns any. Removing the last workspace leaves a fresh one.

Error codes: workspace_not_found, workspace_name_taken, workspace_has_terminals.

worktree

beswarm worktree list   [--workspace <ws>] [--json]
beswarm worktree add    --name <name> --workspace <ws>
beswarm worktree close  --name <name> --workspace <ws>
beswarm worktree remove --name <name> --workspace <ws> [--yes]

Subcommand	What it does
`list`	Workspace, name, branch, open terminal count and directory of each worktree. Without `--workspace`, lists every workspace's worktrees; a worktree two workspaces share shows once. The main checkout isn't listed.
`add`	Cuts branch `<name>` from the workspace's current commit into `.worktrees/<name>` and opens a terminal in it. The name must be one path component.
`close`	Closes the worktree's terminals. The worktree stays on disk; reopen it from the sidebar's "Open worktree".
`remove`	Closes its terminals, runs `git worktree remove`, and deletes the branch if `add` made it and it's merged.

remove keeps a branch with unmerged commits (JSON branch_kept says why). Git refuses a worktree with uncommitted changes; its terminals are closed anyway. It asks [y/N] unless --yes; with no TTY, --yes is required.

Error codes: workspace_not_found, worktree_not_found, git_failed (git's own message), invalid_request.

See Worktrees for how to use them day to day.