# Run work in parallel with worktrees > How Archon gives each repository run its own git worktree, and how to inspect, provision and clean up worktrees. A run against a repository works in its own git worktree by default: a separate checkout of the same repository on its own branch. Two runs can edit `auth.ts` at the same time without seeing each other's changes, and a run's ordinary edits stay in its worktree instead of your checkout. If you don't like the result, close the pull request. A worktree separates checkouts. It is not an execution or security sandbox: commands a run executes can still affect files outside it. For an isolated execution environment on a folder project, see [Container isolation](/guides/container-isolation/). ## Choose how a run is isolated | Command | Behavior | |---|---| | `archon workflow run "..."` | New worktree on a generated branch | | `archon workflow run --branch fix/login "..."` | Reuses a healthy Archon registration for the branch, otherwise creates or reuses a worktree at the configured target path | | `archon workflow run --no-worktree "..."` | Runs in your current checkout | Use `--branch` with a descriptive name for work that changes code; it makes worktrees and pull requests easy to identify. Use `--no-worktree` only for read-only work. A workflow can pin the choice with `worktree.enabled` in its YAML. Don't start two runs on the same branch at once: one branch maps to one worktree. By default, worktrees live under `~/.archon/workspaces///worktrees/`. Set `worktree.path` in the repository's config for a repo-local location such as `.worktrees`, and add it to `.gitignore`. With `--branch`, Archon first reuses a healthy active task worktree registered in Archon for that project and branch, even at another path. Without that registration, worktree creation can still reuse a usable checkout at the configured target path. If no healthy active task registration was reused and another path holds the branch, creation fails with `branch_checked_out`, naming the holder, whether or not it is registered in Archon. Check whether a live Archon run still needs that checkout before freeing the branch. Once it is safe, preserve its changes, then detach it with `git -C switch --detach` or remove it before retrying. Archon leaves that checkout untouched. [Exact-branch continuation](/reference/cli/#continuing-an-existing-estate), such as `--adopt`, can reuse a Git-registered holder at another path. A workflow can also start a child run with its own worktree by writing `isolation: worktree` on a `workflow:` node; see [Launching a separate governed run](/reference/workflow-language/#launching-a-separate-governed-run-with-workflow). Those branches have generated names such as `archon/task-3f9a1c2b-...-child-0`. A paused or failed child run resumes in its original worktree, so leave child worktrees alone until the whole run has finished. ## Provision new worktrees Prepare dependencies and generated files before agents start, in the repository's `.archon/config.yaml`: ```yaml worktree: copyFiles: ['.env'] postCreate: - bun install --frozen-lockfile postCreateTimeout: 300000 # per command, in milliseconds ``` Commands run in order in the new checkout, after submodules and copied files. A command that exits nonzero, times out or cannot start stops worktree creation, and the error reports the exit code or timeout with the command's output. Both a healthy Archon-registered worktree and a usable existing checkout at the configured target path are reused without running setup again. Setup should provision the checkout, not leave a server running. Copied `.env` files are not loaded automatically. See [Configuration](/reference/configuration/) for every `worktree` option. ## Inspect and clean up ```bash archon isolation list # active worktrees and containers archon isolation cleanup # remove eligible environments older than 7 days archon isolation cleanup 14 # ... older than 14 days archon isolation cleanup --merged # remove environments whose branches merged archon isolation cleanup --merged --include-closed # also those whose PRs closed unmerged archon complete fix/login # remove a branch's worktree and local branch; retain its remote branch ``` Cleanup keeps live runs, resumable failed runs, worktrees with uncommitted changes and commits that exist on no remote. `--merged` and `archon complete` retain remote branches with a warning, including with `--force`, because registration ownership cannot be proved after local cleanup. Enable GitHub's **Automatically delete head branches** setting for merged pull requests, or follow [manual remote branch recovery](/reference/cli/#recovering-remote-branch-cleanup). A run launched without `--branch` removes the worktree it created on its own generated branch when it completes, if the worktree is clean and Archon confirms every commit is on a remote, keeping the local and remote branch. Otherwise the worktree stays, the run's output names the path and what removing it would lose, and its terminal record keeps the reason. A workflow launched from the Web UI gets the same per-run worktree and the same removal. A worktree created for `--branch` stays when the run ends; `--merged` or `archon complete` removes it. A worktree that belongs to a chat conversation, an issue or a pull request rather than to one run also stays; `--merged`, or `archon isolation cleanup` once it is stale, removes it. A workflow with `worktree.enabled: false` creates no worktree. Without a server, schedule merged cleanup with the SDLC pack's `archon-worktree-cleanup` workflow. A failed run keeps its worktree so you can resume it with `archon workflow resume `, or discard it with `archon workflow abandon `, which attempts worktree removal while keeping the branch. Owner warnings retain the checkout for inspection: use `lsof` when output is still held, resolve the warning, then retry abandonment on the cancelled run.