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 reports the slot path. A free slot is not listed there: releasing a checkout unregisters the worktree from the owning clone’s git, which is what leaves the directory, the output base and the server behind for the next branch. 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.