Git Worktrees

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:

• 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:

# 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 for the full workflow.