Worktree mode

By default Build Station serializes tasks per project — at most one Claude session at a time in a project's working directory. That's the safe default; it prevents two agents from stepping on each other's git operations or partial edits.

Worktree mode is the opt-out. When enabled, each task spawn gets its own isolated git worktree as the working directory. Multiple agents can then run in parallel on the same project without colliding.

What's a git worktree?

A worktree is git's mechanism for checking out multiple branches of a repo at once, each in its own directory. Same repo, same .git database, but separate working files. Build Station creates a fresh worktree for each task and deletes it after.

If you've never used git worktree, the short version: it's like cloning the repo but cheaper and tied to the original — branches and commits flow between them naturally.

When to use it

• Multiple agents one project: Developer + infra + reviewer all running simultaneously on the same project. Worktree mode lets them work in parallel.

• Long-running tasks: When one task takes 20+ minutes, queuing the next behind it stalls throughput. Parallel worktrees fix that.

When NOT to use it

• Small projects with infrequent tasks. The serialize-by-default approach is simpler and one agent at a time is fine.
• Projects with heavy submodules or LFS content. Each new worktree pulls fresh checked-out files — disk space adds up, and submodule init runs again.
• Projects with hooks or generated files outside .git. If your project has node_modules, target/, build artifacts, or env files that aren't tracked by git, they won't be in the worktree. Each spawn would start with an empty install. Usually you want to keep serialized mode here.

Turning it on

1. Open the project's detail panel

Main window → click the project.

2. Toggle Worktree mode on

Find the Worktree mode toggle in the project's per-agent settings. Each agent has its own toggle — you can mix (developer in worktree mode, infra serialized, etc.).

3. No restart needed

The next task spawn for that agent will use a worktree automatically.

How it works behind the scenes

For each task spawn with worktree mode on:

1. Build Station creates a fresh worktree at a temp path, branched from the project's current HEAD.
2. The Claude session opens that path as its working directory.
3. The agent does its work — edits, commits, runs commands — entirely inside that worktree.
4. When the task completes (or fails), Build Station cleans up the worktree.

The agent's commits land on a unique per-task branch. You can fetch and merge those branches at your leisure from your main checkout.

Warning: Worktrees bypass the project lock

Tasks running in worktrees are NOT serialized — multiple worktree-mode tasks can run simultaneously on the same project. That's the whole point, but it does mean you lose the safety net. Make sure your agents and prompts handle the parallel case (e.g., they don't all try to bump the same version number).

Cleanup

Since 1.4.0 cleanup is mostly automatic:

• A worktree is given back when its session ends. Before 1.4.0 every worktree session leaked its directory and its branch, and the only thing that ever reclaimed them was the same task id coming round again — self-healing by accident rather than by design.
• Leftovers from a previous run are swept at startup, so a Station that was killed mid-task tidies up when it comes back rather than accumulating directories.
• A record is kept until its worktree is claimed, so a reclaim in progress is not mistaken for a leak.

You should rarely need to intervene. If you do — a crash at exactly the wrong moment, or a worktree a process outside Build Station is holding open — the manual routes still work:

• Open the project's detail panel and click Clean stale worktrees, OR
• Run git worktree prune manually in the project's main checkout.

Either is fine — Build Station's "clean stale worktrees" just does the same prune for you.