Git Worktrees, Now That Your Coding Agent Uses Them: How They Work and What Breaks

Claude Code runs parallel sessions and subagents in git worktrees: separate checkouts on separate branches, sharing one repository. What a worktree shares and doesn't, the one-branch rule, where Claude Code puts them and when it cleans them up, and the things that still collide: dependencies, ports, local databases and .env files.

A git worktree is a second working directory for the same repository: its own files, its own branch, its own staging area, the same history. Coding agents use them so two sessions, or a session and its subagents, can edit at the same time without overwriting each other. If you run Claude Code with --worktree, or ask it to use worktrees for its agents, this is what is happening underneath.

What is shared and what isn't

Two consequences follow. A commit made in one worktree is visible from all of them at once, with no push or fetch. And git refuses to check out a branch that another worktree already has checked out, so each worktree works on its own branch, and merging is how their work comes together.

How Claude Code uses them

• `claude --worktree feature-auth` (or `-w`) creates `.claude/worktrees/feature-auth/` on a new branch, `worktree-feature-auth`, and starts the session there. Run it again with another name in another terminal for a second, isolated session.

• New worktrees branch from the repository's default branch on the remote. Set `worktree.baseRef` to `"head"` to branch from your current local work instead, which is what subagents working on an in-progress change usually need.

• Subagents get their own worktrees when you ask for it, or always, with `isolation: worktree` in a custom agent's frontmatter.

• On exit, a clean worktree from an unnamed session is removed with its branch; one with changes, untracked files or new commits prompts you to keep or remove it. Subagent worktrees with work in them stay until a periodic sweep can remove them without losing anything.

• While a session is isolated, Claude Code refuses edits and git commands aimed at the main checkout.

What still collides

Housekeeping commands

• `git worktree list` shows every worktree and its branch.

• `git worktree remove <path>` deletes one cleanly (it must be clean, or use --force). Deleting the directory by hand leaves metadata behind; `git worktree prune` clears it.

• `git worktree lock` protects one from pruning; Claude Code locks the worktrees of running agents, so unlock before removing one by hand.

• `git worktree repair` reconnects worktrees after you move the repository.