Worktrees

A worktree is a second checkout of a workspace's repository, on its own branch, kept in <repo>/.worktrees/<name>. In the sidebar, a worktree with terminals open shows as a sub-item under its workspace, with a tab bar of its own.

Worktrees let several agents work on the same repository without sharing a checkout: one worktree per feature, one editing agent per worktree.

Create one

beswarm worktree add --name feat-auth --workspace api

This cuts a new branch feat-auth from the workspace's current commit and opens a terminal in it — exactly what the sidebar's "New worktree" does. The name must be a single path component.

Start the feature's agent in the terminal add opened by passing its terminal id to agent start.

One terminal per worktree

A worktree holds one terminal: the one it was opened with. Need more? Split that terminal into panes (f5 / f6).

• agent start without a terminal id is refused with invalid_request while a worktree is selected in the sidebar. Pass the worktree's terminal id instead — beswarm terminal list shows which tab belongs to which worktree.
• terminal add --worktree is refused when the worktree already has a terminal. Use it to reopen a terminal in a worktree that has none.
• In the TUI, New tab is refused under a worktree sub-item.

List them

beswarm worktree list --workspace api
beswarm worktree list                  # every workspace

Lists workspace, name, branch, how many terminals its sub-item has open, and its directory. The main checkout is the workspace itself and isn't listed.

Park one

beswarm worktree close --name feat-auth --workspace api

Closes the worktree's terminals, killing those shells. The worktree stays on disk; reopen it from the sidebar's "Open worktree".

Remove one

beswarm worktree remove --name feat-auth --workspace api

Closes its terminals, runs git worktree remove, then deletes the branch if add made it and it's merged.

• A branch with unmerged commits is kept, and the output says so.
• Git refuses a worktree with uncommitted changes; its terminals are closed either way.
• It asks for confirmation unless --yes is given. Without a TTY, --yes is required.