---
title: "Worktrees"
description: "Git worktree integration for multi-branch agent workflows"
icon: "code-branch"
---

Clawker integrates with Git worktrees to let you run multiple agents on separate branches simultaneously without conflicts. Each worktree gets its own working directory, and Clawker tracks them in the project registry.

## Why Worktrees?

Without worktrees, running two agents on the same project means they share the same working directory and branch. Changes from one agent can conflict with the other. Worktrees solve this by giving each agent its own checkout of the repository on a separate branch.

Common patterns:
- Run a feature development agent while a review agent works on a different branch
- Test multiple approaches to the same problem in parallel
- Keep the main branch clean while agents experiment on feature branches

## Creating Worktrees

```bash
# Create a worktree for a new branch (branches from HEAD)
clawker worktree add feature/auth

# Create from a specific base branch
clawker worktree add feature/cache --base main

# Branch names with slashes are supported
clawker worktree add hotfix/login-redirect
```

The worktree directory is created under `~/.local/share/clawker/worktrees/<repoName>-<projectName>-<sha256(uuid)[:12]>/`. If the branch already exists, it's checked out in the new worktree. If it doesn't exist, it's created from the base ref (default: HEAD).

If the worktree already exists in the registry, the command returns an error. Use `clawker worktree list` to check existing worktrees, or use the `--worktree` flag on container commands for idempotent "get or create" behavior.

## Listing Worktrees

```bash
# Full table view
clawker worktree list

# Branch names only
clawker worktree ls -q
```

The table shows:

| Column | Description |
|--------|-------------|
| BRANCH | Branch name (or "(detached)" for detached HEAD) |
| PATH | Filesystem path to worktree |
| HEAD | Short commit hash |
| MODIFIED | Relative time since last change |
| STATUS | Health status |

Status values:
- **healthy** — Directory, `.git` file, git metadata, and branch all exist
- **registry_only** — Directory deleted but registry entry remains (safe to prune)
- **dotgit_missing** — Directory exists but the `.git` file inside is missing or is a directory instead of a file
- **git_metadata_missing** — Directory and `.git` file exist, but git's internal worktree metadata (`.git/worktrees/<slug>/`) is gone
- **broken** — Directory and git metadata exist, but the branch has been deleted

Locked worktrees (via `git worktree lock`) have `IsLocked` set internally and are protected from pruning, but lock status is independent of health — a locked worktree can have any status.

## Removing Worktrees

```bash
# Remove a worktree
clawker worktree remove feature/auth

# Remove multiple worktrees
clawker worktree rm feature/auth feature/cache

# Also delete the branch
clawker worktree remove --delete-branch feature/auth

# Force remove with uncommitted changes
clawker worktree remove --force feature/auth
```

Safety checks prevent accidental data loss:
- Refuses to remove worktrees with uncommitted changes (unless `--force`)
- `--delete-branch` refuses to delete unmerged branches (use `git branch -D` manually)
- `--delete-branch` refuses to delete the currently checked-out branch

## Health Checks

When you list or inspect worktrees, Clawker performs a multi-layer health check on each entry:

1. **Directory existence** — Does the worktree directory still exist on disk?
2. **`.git` file check** — Linked worktrees contain a `.git` *file* (not a directory) that points back to the main repository's `.git/worktrees/<slug>/` metadata. Clawker verifies this file exists and is indeed a file.
3. **Git metadata check** — The main repository's `.git/worktrees/<slug>/` directory must exist. This is where git stores the worktree's HEAD, index, and config.
4. **Branch existence** — The branch associated with the worktree must still exist in the repository.
5. **Lock detection** — Checks for a `locked` file in the worktree's git metadata. Locked worktrees are protected from pruning.

If any check fails, the worktree's status reflects the first failure found. When a check can't be performed (e.g., the git manager isn't available), Clawker degrades gracefully — it reports what it can and notes the limitation in the inspect error.

## Pruning Stale Entries

If worktree directories are deleted manually or by `git worktree remove` (bypassing Clawker), registry entries become stale. Prune them:

```bash
# Preview what would be pruned
clawker worktree prune --dry-run

# Remove stale entries
clawker worktree prune
```

A worktree is considered prunable when any of: the directory is missing, git metadata is gone, or the branch has been deleted. However, **locked worktrees are never pruned** — even if they appear stale. If a worktree has been locked with `git worktree lock`, it's skipped during pruning and reported separately in the output.

## Automatic Worktree Creation via `--worktree`

Container commands accept a `--worktree` flag that automatically creates or reuses a worktree:

```bash
# Container commands
clawker run --worktree feature/auth @
clawker container run --worktree feature/cache @
clawker container create --worktree hotfix/login @

# Create branch from a specific base
clawker run --worktree hotfix/login:main @
```

The flag syntax is `branch` or `branch:base`. If the branch doesn't exist, it's created from the base ref (default: HEAD). If it already exists, it's checked out in the worktree.

### Idempotent behavior

The `--worktree` flag is **idempotent** -- if the worktree already exists and is healthy, it is reused rather than recreated. This means you can run the same command repeatedly without error:

```bash
# First run: creates the worktree
clawker run --worktree feature/auth @

# Second run: reuses the existing worktree
clawker run --worktree feature/auth @
```

If the worktree exists in the registry but is unhealthy (directory deleted, `.git` file missing, git metadata gone, or branch deleted), the command fails with a message suggesting `clawker worktree prune` to clean up the stale entry first. Only worktrees with a `healthy` status are accepted for reuse.

<Note>
This differs from `clawker worktree add`, which is a strict creation command — it errors if the worktree already exists. The `--worktree` flag on container commands is designed for repeated use in workflows where you want "get or create" semantics.
</Note>

### Path mirroring

When `--worktree` is used, the worktree directory is mounted into the container at its **host absolute path** — not at a generic `/workspace`. This is essential for session persistence: Claude Code discovers sessions by matching the container's current working directory against git worktree paths. If the container used a synthetic path, session resume would fail because the paths wouldn't match.

See [Container Internals](/container-internals) for the full explanation of path mirroring and session persistence.

## Example: Parallel Feature Development

```bash
# Terminal 1: Feature A on its own branch
clawker run --worktree feature/auth @

# Terminal 2: Feature B in parallel
clawker run --worktree feature/rate-limit @

# Terminal 3: Check on both
clawker worktree list

# When done, clean up
clawker worktree remove --delete-branch feature/auth
clawker worktree remove --delete-branch feature/rate-limit
```

## How Worktrees Interact with the Project Registry

Worktrees are tracked in the project registry (`~/.local/share/clawker/registry.yaml`) under each project:

```yaml
projects:
  - name: "my-app"
    root: "/Users/dev/my-app"
    worktrees:
      feature/auth:
        path: "/Users/dev/.local/share/clawker/worktrees/my-app-my-app-a1b2c3d4e5f6"
        branch: "feature/auth"
```

This allows Clawker to manage worktrees across sessions and detect stale entries.

All worktree operations use the project root from the registry record rather than re-resolving from the filesystem. This avoids subtle path mismatches on systems where paths can differ between resolutions (e.g., macOS symlinks like `/var` → `/private/var`). The registry is the single source of truth for project identity.

## How Worktrees Work Inside Containers

When a container is created with `--worktree`, two mounts are set up:

1. **Worktree directory** — The worktree's checkout directory is mounted at its host absolute path (e.g., `~/.local/share/clawker/worktrees/my-app-my-app-abc123def456/`). This becomes the container's working directory.

2. **Main `.git` directory** — The main repository's `.git` directory is mounted at its original host absolute path (e.g., `/Users/dev/my-app/.git`). This is necessary because the worktree's `.git` file contains an absolute path reference back to the main repository's `.git/worktrees/<slug>/` metadata.

By mounting both at their real host paths, git commands inside the container work correctly — the `.git` file's reference resolves, git finds the shared metadata, and operations like `git log`, `git status`, and `git commit` behave normally.

See [Container Internals](/container-internals) for the complete explanation of workspace mounting, git integration, and session persistence.
