Parallel Git Worktrees for AI-Assisted Development

A git worktree is a separate working directory with its own files and branch that shares the same repository history and remote as the main checkout. Claude Code’s documentation describes running each coding session in its own worktree so that edits in one session never touch files in another. That makes it possible to have the assistant building a feature in one terminal while fixing a bug in a second.

Starting an Isolated Session

The Claude Code documentation at https://code.claude.com/docs/en/worktrees shows that passing --worktree (or -w) creates an isolated worktree and starts the session inside it:

claude --worktree feature-auth

By default the worktree is created under .claude/worktrees/<value>/ at the repository root, on a new branch named worktree-<value>. Running the same command with a different name in another terminal starts a second isolated session. If the name is omitted, Claude Code generates one such as bright-running-fox.

The documentation notes that worktrees branch from the repository’s default branch, origin/HEAD, so each one starts from a clean tree matching the remote. If no remote is configured or the fetch fails, the worktree falls back to the current local HEAD. Setting worktree.baseRef to "head" in settings makes new worktrees carry unpushed commits and feature-branch state instead. A worktree can also be created from a specific pull request by passing the PR number prefixed with #, which fetches pull/<number>/head and places the worktree at .claude/worktrees/pr-<number>.

Handling Untracked Configuration

Because a worktree is a fresh checkout, untracked files such as .env or .env.local from the main repository are not present. The documentation describes a .worktreeinclude file, placed at the project root and written in .gitignore syntax, that tells Claude Code which gitignored files to copy into each new worktree. Only files that match a pattern and are also gitignored are copied, so tracked files are never duplicated. This applies to worktrees made with --worktree, subagent worktrees, and parallel sessions in the desktop app.

Subagents and Cleanup

Subagents can run in their own worktrees so parallel edits do not conflict. According to the documentation, adding isolation: worktree to a custom subagent’s frontmatter gives each subagent a temporary worktree that is removed automatically when it finishes without changes.

Cleanup of interactive sessions depends on the state of the worktree. If there are no uncommitted changes, untracked files, or new commits, the worktree and its branch are removed automatically, though named sessions prompt first so the work can be kept. If changes do exist, Claude Code prompts to keep or remove the worktree. Worktrees created with --worktree alongside -p in non-interactive runs are not cleaned up automatically and must be removed with git worktree remove.

Managing Worktrees Directly

For full control over location and branch configuration, the documentation recommends creating worktrees with Git itself. A worktree on a new branch is made with git worktree add ../project-feature-a -b feature-a, an existing branch with git worktree add ../project-bugfix bugfix-123, and the session is started by changing into that directory and running claude. The git worktree list command shows current worktrees, and git worktree remove deletes one when the work is finished. The documentation also notes that each new worktree needs its development environment set up separately, including installing dependencies and any required virtual environments. For version control systems other than Git, such as SVN, Perforce, or Mercurial, isolation can be configured through WorktreeCreate and WorktreeRemove hooks.