A change’s tasks run in a dedicated git worktree on their own branch — a second checkout of your repository, outside the project directory. Your working tree is never touched until you merge. You stay in one IDE window the whole time.

The first-run question

The first time a change runs a task, SpecBuddy asks:

“add-full-text-listing-search” has not run a step yet. Where should its steps run?

• Continue in current branch — run steps directly in the current working tree. • Create Worktree — isolate steps in a dedicated git worktree on their own branch, with a separate review and merge lifecycle.

This choice is remembered for this spec.

Create Worktree is the recommended answer, and the one this documentation assumes. Choose Continue in current branch for a small change you’ll commit yourself, or in a repository where a second checkout is impractical. The choice is per change; to stop being asked, turn on Always run steps in a dedicated worktree in Settings.

You can also create the worktree ahead of time: right-click the change in the Spec Explorer → Create Worktree.

What a worktree is, here

• Location: outside your project — ~/.specbuddy/<project hash>/worktrees/<change-id>/. It does not show up in your project view, your VCS changes, or your search results.
• Branch: feature/<change-id> by default. The pattern is a setting, Worktree branch name; {specid} is the only placeholder and it is required.
• Lifetime: created on the first task run, kept across sessions and IDE restarts, removed when the change is merged — or when you remove it explicitly.

The Spec Explorer row shows ⎇ feature/add-full-text-listing-search while the worktree exists, and the Cockpit’s header shows the branch and whether the current copy is the main tree or the worktree.

Working in one window

You don’t open the worktree as a project. Instead, SpecBuddy mirrors the change’s session into the window you already have:

• The Cockpit, the banner and the Explorer open the worktree copy of a document when a session is live there. A banner on it reads Worktree Copy, with Open original to jump to your copy of the same file, and Main tree to see the difference if they have diverged.
• The diffs under review are the worktree’s.
• Your own copy of tasks.md is the identity of the change — the Explorer row, the history — but its content while a task runs is the worktree’s. When the two differ (you edited the document in your tree while the agent worked in the worktree), the banner says so and offers Open current version.

If you do want the worktree as a separate window — to run its build, to browse it in the Project view — right-click the change → Open Worktree Window. The main toolbar in such a window shows This window is a SpecBuddy worktree; click it to get back. The toolbar in your main window shows SpecBuddy: N Active Sessions while agents are running.

Commit and merge

When the change is done — usually straight from the completion card of Sync and archive — three actions land the branch:

• Commit — commits everything in the worktree on its branch. Nothing reaches your branch.
• Merge — merges the worktree branch into the branch your project has checked out. The Cockpit’s Merge control also offers Choose branch… with every other local branch as a target.
• Commit & Merge — both, in one go.

All three are agent runs: SpecBuddy hands the agent a precise git instruction, the agent performs it, and the log shows the commands. A merge conflict therefore does not fail silently — the agent reports it in the log and stops for you.

The same actions are in the Cockpit header (a Commit / Merge row under the change name while a worktree exists) and in the Explorer’s context menu.

The sync-and-archive gate

Merging a change whose deltas are not yet synced would land its code before its specs. So Merge on an OpenSpec change checks first, and if the change is not archived in the worktree it asks:

This OpenSpec change has not been synced & archived yet. Merging now lands its worktree before its spec deltas reach the main specs and the change is archived. Sync & Archive the change first? Sync & Archive first · Merge anyway

Sync & Archive first runs that, and its completion card offers the merge again.

After the merge

When every task of the change is merged, SpecBuddy removes the worktree and the Explorer’s ⎇ badge disappears. The branch itself stays in your repository until you delete it.

If you merged outside SpecBuddy — from the git command line, a PR — the worktree stays until you remove it: right-click the change → Remove Worktree. The confirmation states that anything in the worktree never committed or merged is lost; SpecBuddy refuses to remove a worktree with an active session.

Snapshots

Every run is bracketed by two snapshots, and rollback restores the first of them. Snapshots are stash-format commits synthesised from the tree’s state — they are not git stash push, they never touch the index or the working files, and they include untracked files the run created. You’ll see them under git stash list in the worktree; leave them alone, SpecBuddy owns them.

Running in the current branch

If you chose Continue in current branch, tasks run in your working tree, directly. Everything else — snapshots, review, rollback, refine — works the same; you just have no Merge step and no isolation. Commit as you normally would. Keep in mind that the agent’s uncommitted edits and yours now share one tree.