Git worktrees
The git mechanism behind an isolated workspace, and what it does and does not separate.
A git worktree is a second checkout of the same repository, on its own branch,
in its own directory, sharing one .git history. Proliferate uses worktrees to
give each workspace somewhere to work that is not your main checkout.
How Proliferate uses worktrees
When you create a workspace with the New worktree target, Proliferate runs the git plumbing for you: it resolves the repository root from the checkout you linked, creates a worktree and a branch for the workspace, and then runs the repo's setup script inside the new directory.
Your primary checkout is never touched. It is the repo root that worktrees are created from, not a target Proliferate writes into, and it is never a candidate for cleanup.
Managed worktrees
"Managed" means the worktree has a durable workspace record behind it, so Proliferate knows which branch it is on, which sessions belong to it, and whether it is safe to remove.
That record is also what makes recovery possible. If the directory disappears — you deleted it, or a disk moved — the workspace itself survives and the checkout can be restored in place, on the same branch, with its sessions and history intact. Uncommitted edits that were lost with the directory are not recoverable; committed state is.
Restore only ever rebuilds committed branch state. Commit or publish work you care about before removing anything.
Use isolated branches on the same machine
A worktree is not a container or a VM. It shares your machine, your disk, your installed toolchains, and your dependency caches, which is exactly why creating one is cheap.
What it isolates is branch and workflow state:
| Isolated | Shared |
|---|---|
| The branch and the working tree | The repository's git history and objects |
| Files on disk for that stream of work | Your toolchains, caches, and global config |
| Setup script and run command execution directory | Your machine's ports, processes, and credentials |
Worktrees are a development boundary, not a security boundary. An agent in a worktree runs as you, with your access.
Proliferate's own files
Each worktree has a .proliferate/ folder for the things a run needs on disk
but nobody wants in a commit — workflow context documents under
.proliferate/context/<run-id>/, and scratch state. The folder is git-excluded,
so it never appears in git status and never lands in a diff.
How pruning works in Proliferate
Worktrees accumulate. Pruning is the cleanup path for old, clean ones.
Before removing a worktree, the runtime checks for reasons not to:
- Uncommitted changes or unresolved git state.
- Live sessions or terminals.
- Queued prompts or running operations.
Anything that trips a check is left alone. Raising the Ideal worktrees target under Settings → Pruning changes the pressure the policy works against; it never makes an unsafe worktree deletable.
Pruning removes the checkout and keeps the workspace's chat history. Purging is the separate, destructive path that deletes the runtime record, sessions, and transcripts as well. Commits, branches, and pull requests survive both. See Lifecycle & storage.