Skip to main content
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 loop 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

# 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/loop commands for idempotent “get or create” behavior.

​
Listing Worktrees

# Full table view
clawker worktree list

# Branch names only
clawker worktree ls -q
The table shows:
ColumnDescription
BRANCHBranch name (or “(detached)” for detached HEAD)
PATHFilesystem path to worktree
HEADShort commit hash
MODIFIEDRelative time since last change
STATUSHealth 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

# 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: 
# 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 and loop commands accept a --worktree flag that automatically creates or reuses a worktree: 
# Container commands
clawker run --worktree feature/auth @
clawker container run --worktree feature/cache @
clawker container create --worktree hotfix/login @

# Loop commands
clawker loop iterate --prompt "Build auth system" --worktree feature/auth
clawker loop tasks --file tasks.md --worktree feature/tasks

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

# Auto-generate a branch name (loop only)
clawker loop iterate --prompt "Experiment" --worktree ""
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: 
# 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.
This differs from clawker worktree add, which is a strict creation command — it errors if the worktree already exists. The --worktree flag on container/loop commands is designed for repeated use in workflows where you want “get or create” semantics.

​
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 for the full explanation of path mirroring and session persistence.

​
Loop conflict detection

If a loop is already running in the project root, Clawker detects the conflict and offers to create a worktree automatically:
  • Interactive mode: Prompts with three choices — use a worktree, proceed anyway, or abort
  • Non-interactive mode: Warns and suggests --worktree

​
Example: Parallel Feature Development

# Terminal 1: Feature A on its own branch
clawker loop iterate --prompt "Implement user authentication" \
  --worktree feature/auth

# Terminal 2: Feature B in parallel
clawker loop iterate --prompt "Add API rate limiting" \
  --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: 
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 for the complete explanation of workspace mounting, git integration, and session persistence.