Skip to main content
New and experimental. File bugs and suggestions to aspect-build/aspect-cli/issues.
Working on two branches at once in a Bazel repo costs a cold build for the second, because Bazel keys its server and output base on the workspace path, and every new worktree is a path it has never seen. Delete the worktree and its output base stays on disk. aspect worktree hands out worktrees from a pool of reused paths instead, so the second branch — and the twentieth agent task — starts with the Bazel state the first one left.

Working in parallel with warm worktrees

New here? The guide walks through it end to end: what the pool saves, a day of work across several branches, handing slots to coding agents, and keeping the disk in check.
  • A slot is a directory at a fixed path that holds one git worktree at a time. The path never changes, so Bazel’s output base, and its server while it runs, carry over to whatever worktree comes next.
  • A pool is one repository’s slots, keyed on its origin remote, under ~/.aspect/worktrees/.
  • A slot’s warmth is what it has kept: hot with a live Bazel server, warm with only its output base, cold with neither.
Nothing is symlinked and no Bazel flag is injected, so bazel, an IDE or a script in the slot reaches the same state, and git worktree list shows every slot. add and release follow git worktree add and git worktree remove; each page compares the two flag by flag.

​
Commands

aspect worktree add

Take a worktree from the pool, in the free slot whose Bazel state best fits the branch.

aspect worktree release

End the lease: the worktree goes, the slot keeps its Bazel state.

aspect worktree list

Every slot, what holds it, and how warm it is.

aspect worktree path

Print a worktree’s directory, for cd.

aspect worktree prune

Delete slots that have gone stale, and the disk they hold.

aspect worktree inspect

One slot in full — named, or the one you are standing in — and how to get back to whoever holds it.
For coding agents, Agent skill: pooled worktrees is written to hand straight to an agent, and agent detection covers how each harness’s sessions are recognised.