Workspace

Worktrees

Worktrees are Swarm’s Git-based isolation layer for concurrent work. When enabled for a workspace, new sessions can run in separate Git worktree directories instead of all agents editing the same checkout.

Isolation

Use worktrees when multiple sessions may edit the same repo.

A normal workspace points every session at the same folder. Automatic worktrees give each new session a branch-specific working directory, reducing collisions between chat sessions, background agents, and parallel work.

Worktrees require a Git workspace. They isolate working directories and branches; they do not replace review, tests, or explicit merge decisions.

Settings

Workspace worktree settings

enabledTurns automatic worktrees on or off for the active workspace or selected Desktop workspace.

use_current_branchWhen true, new worktree branches start from the current branch at launch time.

base_branchOptional fixed branch source when you do not want to branch from the current branch.

branch_nameThe created branch prefix. The default prefix is agent, producing branches like agent/<id>.

session metadataSessions record whether a worktree is enabled plus worktree root, base branch, and branch name when present.

Commands

Terminal worktree commands

/worktrees

Open the worktrees menu for the active workspace. /wt is an alias.

/worktrees status

Show the active workspace’s current worktree settings.

/worktrees on

Enable automatic worktrees and default branch-off behavior to the current branch.

/worktrees off

Disable automatic worktrees for new sessions in the active workspace.

/worktrees branch <name|current>

Choose a fixed base branch, or use current to branch from the current branch.

/worktrees created-branch <prefix>

Set the branch prefix used for created worktree branches.

Branch names

Swarm stores a branch prefix, then adds the session id.

The default branch prefix is agent. If you enter agent/<id>, Swarm normalizes it back to the prefix agent. At runtime, the created worktree branch is formed with the generated id.

Branch source and branch prefix are separate. The source says where the new branch starts; the prefix says what Swarm names the branch it creates for the isolated run.

TUI and Desktop

Both surfaces expose the same worktree model.

Terminal UIUses /worktrees and /wt to open the menu, toggle worktrees, check status, and set branch behavior for the active workspace.

Desktop launcherShows each saved workspace with a worktree toggle so new sessions can inherit that workspace’s isolation setting.

Desktop settingsHas a Worktrees settings page for enabling automatic worktrees, setting branch source, and changing the created branch prefix.

The UI controls differ, but the backend shape is the same: workspace path, enabled flag, branch source, and created branch prefix.

In the terminal and Desktop, if worktrees are on for a workspace, a new session for that workspace may be created in a generated worktree immediately. To keep the next session in the original checkout, turn worktrees off from the original workspace before starting it.

When to use

Turn worktrees on only when isolation is worth the extra review step.

Good fitParallel implementation, experiments that may touch the same files, or several sessions in one repo.

Less usefulRead-only research, single-session work, non-Git folders, tiny fixes, or changes you intentionally want in the current checkout.

Review stepWorktree isolation prevents accidental overlap while editing. You still decide what to merge, commit, or discard.

Swarm workflow

Use worktrees for parallel agent bursts, not every task.

Turn it onOpen one workspace, run /worktrees on in the TUI, or click the wt control in the Desktop workspace sidebar. Once it is on, new sessions for that workspace can start in generated worktrees.

Fan outLaunch parallel agents from that workspace when several pieces can move at once. Each worktree keeps one agent’s edits and branch isolated.

Check laterAfter the agents finish, review their worktrees, test what is ready, then decide what to commit, merge, or discard.

Ask SwarmTry: Check my worktrees for today. Swarm can inspect the configured worktree branch family and flag commits that are not merged, or patch-equivalent, on the current branch.

Use selectivelyThis is a power tool, not the default path. We use it for roughly 20–30% of work: mostly parallel implementation or experiments where collisions are likely.

Ask from the original workspace, not from inside one of the generated Git worktree folders. If you start the review from inside a worktree, Swarm can treat that isolated checkout as the project and miss the parent workspace picture.