---
title: Git Worktrees
description: Automatic git worktree management for branch-based parallel development.
---

Claudette 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.

## Automatic Management

When you create a workspace in Claudette:

1. A new **branch** is created from your repository's default branch
2. A **worktree** is checked out to a directory under your configured worktree base path (default: `~/.claudette/workspaces`)
3. 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 Claudette — `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 — Claudette 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](/claudette/features/settings/):

- **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, Claudette 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:

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

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

# Delete every archived workspace in the repo
claudette 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 `~/.claudette/workspaces`. You can change this in `Settings > General > Worktree base directory`.

## Checkpoints and Forking

Claudette 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](/claudette/features/checkpoints-and-forking/) for the full workflow.
