Lifecycle & storage

A workspace is really two things layered together, and it helps to keep them separate:

• The workspace record: your chat history, sessions, repo and branch identity, and review state. This is durable and lives in Proliferate.
• The checkout: the actual files on disk (or in your cloud sandbox) that the agent reads, edits, and runs commands in.

Cleaning up storage removes the checkout. It should never remove your chat history. Proliferate keeps these two lifecycles distinct on purpose, so freeing up disk space is never the same operation as losing your work.

Creating a workspace

What "create" means depends on the target you picked:

• Local checkout: the agent works directly in a folder you've already cloned. Nothing new is materialized.
• New worktree: Proliferate creates a git worktree on your machine for a fresh branch, then runs the repo's local setup script.
• Cloud workspace: Proliferate clones the repo (or reuses an existing clone) inside your cloud sandbox, checks out the branch, and runs the repo's cloud setup script.

From there, all three behave the same way: chat, terminals, file browsing, and git review all work identically regardless of where the checkout lives.

Active and archived

A workspace stays active until you explicitly archive it. Active workspaces show up in the normal sidebar list, whether or not their checkout still exists on disk.

Archiving a workspace:

1. Moves it out of the main sidebar immediately.
2. Keeps it available under Settings → Archived chats, with its full chat history intact.
3. Tries to safely remove its checkout in the background.

If the checkout is clean, Proliferate deletes it right away. If it isn't safe to remove, for example there are uncommitted changes, a merge conflict, a live session, or work still running, the workspace stays archived but shows a cleanup-attention state explaining why. Nothing is force-deleted out from under you.

Unarchiving brings a workspace straight back to active, with the same id and history. If its checkout was cleaned up while archived, Proliferate recreates it automatically the next time you open a file, start a terminal, or send a prompt. You don't need to notice or wait for this beyond that first action feeling a little slower.

Safe cleanup

Proliferate never prunes a checkout that's unsafe to remove. Before deleting anything, it checks for:

• Uncommitted changes.
• Merge conflicts or other unresolved git state.
• A live session or an active terminal.
• A queued prompt or a pending interaction.
• Any operation currently running.

If any of those apply, cleanup is skipped and the workspace is left alone until you resolve the blocker or clean it up yourself.

Automatic pruning keeps your history

You don't have to manage storage by hand. Set an ideal worktree count per repo in Settings → Pruning, and Proliferate keeps usage near that target in the background, unmounting the checkout for old, clean, unused worktrees once you're over the limit. This only removes files on disk: the workspace record and its full chat history stay exactly as they were, and the checkout is recreated automatically the next time you need it. See Per-user sizing for how that target is chosen and how the pressure indicator in the composer reflects it.

Deleting manually

Open Settings → Pruning to see every runtime Proliferate knows about (your local machine and your cloud sandbox) with its current worktree count or resource pressure. Click Details on any runtime to open its full worktree inventory: every checkout, its git status, its chat count, and how much disk space its files and session history are using.

Unlike automatic pruning, the Delete button in this table is destructive to history, not just to files. What it removes depends on the row:

• An orphaned checkout (a worktree with no workspace attached to it anymore) just removes the folder. Nothing else is affected.
• A workspace's row permanently deletes the runtime workspace record, its chats, raw and normalized events, the checkout, and any local agent artifacts. Git commits, branches, pull requests, and your Cloud workspace record are preserved. Proliferate asks you to confirm before running this, since there's no undo.

Cloud specifics

Cloud workspaces follow the same active, archived, and cleanup model, with one addition: your cloud sandbox itself can pause when idle and wake back up on demand, independent of any single workspace's lifecycle. See Local & cloud for how that works.