Git Worktrees

Workbench uses git worktrees to give each workspace its own isolated copy of your repository. This is what makes parallel agents possible without merge conflicts.

What Are Git Worktrees?

A git worktree is a feature of git that lets you check out multiple branches of the same repository simultaneously, each in its own directory. Unlike cloning the repo multiple times, worktrees share the same .git history and objects — they’re lightweight and fast to create.

Adding a Repository

Add an existing repo

Open the Add Repository modal from the Workspaces sidebar, select the Local tab, and browse to (or paste the path of) a repository already on disk. Workbench registers it and creates workspaces from its branches.

Clone a repo

The Add Repository modal also has a Clone tab. Paste a repository URL (HTTPS or SSH) and Workbench clones it into the default repository directory, registers it, and creates the first workspace — all in one step.

Default repository directory

Settings > General > Default repository directory sets the pre-filled path for the Add Repository modal and the clone destination. When this is configured, you can skip browsing for a folder every time you add or clone a repo.

Automatic Management

When you create a workspace in Workbench:

A new branch is created from your repository’s default branch
A worktree is checked out to a directory under your configured worktree base path (default: ~/.workbench/workspaces)
Your setup script runs in the new worktree (if configured)

When you archive a workspace, the worktree and its directory are cleaned up automatically.

Discovering Existing Worktrees

Worktrees created outside Workbench — git worktree add from a terminal, teammate tooling, or other agent runners like Conductor — aren’t tracked as workspaces until you import them. Run discovery to scan the repository for those worktrees:

Workspaces sidebar → right-click a repository row and choose Discover Worktrees….
Repo Settings → the Worktree discovery field has a Discover worktrees button.

Both open the Existing worktrees found dialog, which lists each untracked worktree with its branch name, path, and on-disk size. Name each one, select the ones to import, and confirm — Workbench registers them as workspaces. The per-row trash icon deletes a stray worktree from disk instead. When the scan finds nothing, the dialog tells you so.

Branch Naming

New workspace branches are given a random name initially. After your first prompt, the agent automatically renames the branch to something descriptive based on the work being done.

You can configure branch naming behavior in Settings > Git:

Username prefix: branches are prefixed with your git username (e.g., sean/add-health-check)
Custom prefix: use your own prefix (e.g., feature/, fix/)
No prefix: just the descriptive name

Branch Cleanup

When archiving a workspace, Workbench can optionally delete the local branch. This setting (Settings > Git > Auto-delete branch on archive) only deletes branches that contain only checkpoint commits — if you’ve made manual commits on the branch, it will be preserved.

Bulk Cleanup of Archived Workspaces

Archived workspaces still occupy disk space in the database (chat history, terminal tab state, SCM cache). To purge them in batches:

Project dashboard → the ARCHIVED section header has a Clean up… button. Opens the modal scoped to the current repository.
Settings → Storage → lists every local repository with its archived count and a per-row Clean up… button, plus a top-level Clean up all (N) button next to the section header that runs cleanup across every local repository in a single pass.
Per-repo Settings → the Workspace cleanup field at the bottom of the per-repo settings page opens the same modal.

The cleanup modal lets you:

Filter to workspaces older than 30 / 60 / 90 days, 6 months, or 1 year (measured from creation), or leave it on All to see every archived workspace.
In cleanup-all mode, browse all eligible workspaces grouped by repository header (single-repo mode renders a flat list).
Select rows individually or use Select all to grab every eligible row in one click.
Permanently delete the selected workspaces — their worktrees, branches, chat history, and terminal state. Lifetime metrics survive in the deleted_workspace_summaries table so cost/turn dashboards stay accurate.

While the run is in flight the modal shows live per-row progress: a spinner next to pending rows, a green check as each row completes its full DB + worktree + branch + env cleanup, an X for failures, and a circled dash for rows the user cancelled. A running counter at the top reports X of N deleted, Y failed. The bulk-cleanup-progress Tauri event drives the UI; a unique request id is generated per run so concurrent cleanups (e.g. from two Settings windows) stay isolated.

Cancel stays enabled throughout the run. Clicking it (or closing the modal) flips the button to “Cancelling…” and signals cooperative cancellation: the in-flight row finishes its own DB + worktree teardown, then every remaining row is reported as cancelled. Cancelled rows are untouched in the DB and on disk, so re-running cleanup picks them up cleanly. Cleanup is atomic per row — each row either finishes its full DB + worktree + branch cleanup before its deleted event fires, or stays entirely intact, so a cancellation never leaves orphan worktrees behind a deleted database row.

From the CLI:

# Dry-run: show which IDs would be deleted
workbench workspace purge --repo <repo-id> --older-than-days 90 --dry-run

# Actually delete archived workspaces older than 90 days in this repo
workbench workspace purge --repo <repo-id> --older-than-days 90

# Delete every archived workspace in the repo
workbench workspace purge --repo <repo-id>

The CLI rejects non-Archived IDs at the server, so an Active workspace can never be removed via this path even if its ID accidentally slips into the resolved list.

Worktree Base Directory

By default, worktrees are created under ~/.workbench/workspaces. You can change this in Settings > General > Worktree base directory.

Checkpoints and Forking

Workbench captures conversation checkpoints automatically as the agent works, and lets you fork a workspace from any checkpoint into a new branch — original session preserved. See Checkpoints & Forking for the full workflow.

Divergent Branch Pull

When you click Pull on a trunk repository and both the local branch and the remote have new commits (i.e. the branches have diverged), Workbench opens a resolution modal instead of failing silently.

Available options

Merge (recommended) — creates a merge commit combining both sets of changes. Preserves the full history of both branches. This is the safest option when you are unsure which commits conflict.
Rebase — replays your local commits on top of the incoming remote changes. Produces a cleaner linear history, but rewrites local commit SHAs.
Fast-forward only — refuses to proceed on diverged branches. Use this when you want to confirm that no local commits exist before pulling.
Open terminal — opens an integrated terminal so you can handle the situation manually with any git command.

Conflict resolution

If Merge or Rebase encounters conflicts, Workbench attempts automatic resolution using the workspace’s AI agent. The agent inspects each conflicting file and applies edits to resolve the markers.

If the agent cannot resolve all conflicts, you have three options:

Retry — re-run automatic resolution after you have edited the remaining conflicts by hand.
Open terminal — resolve the remaining conflicts manually in a terminal, then run git merge --continue or git rebase --continue as appropriate.
Abort — cancel the entire pull and return to the pre-pull state (see below).

Recovery across restarts

Pull attempts persist in the database across app restarts. If you close Workbench while a merge or rebase is in progress, clicking Pull again on the same repository resumes the operation where it left off rather than starting over.

Aborting

You can abort at any point during conflict resolution. Workbench runs git merge --abort or git rebase --abort as appropriate and cleans up any temporary worktree state, leaving your repository in a clean state identical to before the Pull was initiated.

Original source: utensils.io/claudette