> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Aspect CLI worktrees

> Reuse git worktrees at stable paths so Bazel keeps its server, analysis cache and external repositories between them, instead of paying a cold build per worktree.

<Warning>
  New and experimental. File bugs and suggestions to [aspect-build/aspect-cli/issues](https://github.com/aspect-build/aspect-cli/issues).
</Warning>

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.

<Card title="Working in parallel with warm worktrees" icon="book-open" href="/docs/cli/guides/worktrees" horizontal>
  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.
</Card>

```shell theme={null}
git fetch origin
aspect worktree add fix/login --create=origin/main   # a new branch, from a fresh main
aspect worktree add teammate/fix                      # or one that exists, here or on a remote
aspect worktree list                                  # what is in use, and how warm
slot=$(aspect worktree path fix/login) && cd "$slot"  # step into it
cd - && aspect worktree release fix/login             # step out, give the slot back, keep its Bazel state
```

* 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

<CardGroup cols={2}>
  <Card title="aspect worktree add" href="/docs/cli/worktrees/add">
    Take a worktree from the pool, in the free slot whose Bazel state best fits the branch.
  </Card>

  <Card title="aspect worktree release" href="/docs/cli/worktrees/release">
    End the lease: the worktree goes, the slot keeps its Bazel state.
  </Card>

  <Card title="aspect worktree list" href="/docs/cli/worktrees/list">
    Every slot, what holds it, and how warm it is.
  </Card>

  <Card title="aspect worktree path" href="/docs/cli/worktrees/path">
    Print a worktree's directory, for `cd`.
  </Card>

  <Card title="aspect worktree prune" href="/docs/cli/worktrees/prune">
    Delete slots that have gone stale, and the disk they hold.
  </Card>

  <Card title="aspect worktree inspect" href="/docs/cli/worktrees/inspect">
    One slot in full — named, or the one you are standing in — and how to get back to whoever holds it.
  </Card>
</CardGroup>

For coding agents, [Agent skill: pooled worktrees](/docs/cli/worktrees/agent-skill) is written to hand straight to an agent, and [agent detection](/docs/cli/worktrees/agents) covers how each harness's sessions are recognised.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.