Claude Code worktrees: run parallel sessions without edit conflicts

Claude Code worktrees, explained

Git has supported worktrees for years: git worktree add checks a branch out into a second directory, backed by the same .git data. Claude Code builds on that. With --worktree (or -w) it creates the worktree for you, starts the session inside it, blocks edits that would land in your main checkout, and offers to clean up when you exit.

Worktrees isolate files, nothing else. To split one task between workers inside a single conversation, use subagents; to compare the options, see multiple Claude Code agents.

• Default location: .claude/worktrees/<name>/ at the repository root.
• Default branch name: worktree-<name>. Leave out the name and Claude Code picks one, such as bright-running-fox.
• Shared with your checkout: the .git directory (so commits and branches are visible everywhere), project-scope plugins, and "don't ask again" permission approvals.
• Not shared: anything gitignored, such as .env, node_modules and build output. A worktree is a fresh checkout.

The worktree workflow, step by step

1. Ignore the worktree folder

   Add .claude/worktrees/ to .gitignore, so worktree files don't show up as untracked in your main checkout. If you've never run Claude in this repository, run claude once first to accept the workspace trust prompt; interactive --worktree runs exit until you do.

2. Start one session per task

   Run claude --worktree <name> in one terminal for each task. Running it again with an existing name reopens that worktree instead of making a new one. You can also ask Claude mid-session to "work in a worktree", and it moves itself into one with the EnterWorktree tool.

   # Two isolated sessions, each in its own terminal
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # Branch a worktree from pull request 1234 (quote the #)
   claude --worktree "#1234"
   
   # Keep worktrees out of git status
   echo ".claude/worktrees/" >> .gitignore

3. Bring the untracked files along

   List gitignored files the project needs, such as .env and .env.local, in a .worktreeinclude file at the repository root, using .gitignore syntax. Claude Code copies matching files into every worktree it creates, including subagent and desktop worktrees. Then install dependencies in the worktree, or set it up in settings: this example branches from your current work, reuses one node_modules and checks out only the web package.

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. Let the sessions work

   While a session is isolated, Claude Code refuses file edits that target the main checkout, commands whose working directory is the main checkout, and git commands redirected into it (git -C, --git-dir, GIT_DIR). It doesn't track what a plain shell command such as cp writes, so permissions and sandboxing still matter.

5. Review and merge like any branch

   Each worktree is a normal branch. Commit and push from inside it, open a pull request, and review it as you would a teammate's. Because all worktrees share .git, the branch is visible from your main checkout straight away.

6. Exit and clean up

   When you exit, Claude Code checks the worktree. A clean one from an unnamed session is removed with its branch automatically; a named session asks first. If there are changes, untracked files or new commits, it asks whether to keep or remove the worktree, and prints a claude --worktree <name> --resume command to come back later.

Source: Claude Code docs, Run parallel sessions with worktrees

Worktree settings in Claude Code

All of these go under worktree in a settings file (~/.claude/settings.json, .claude/settings.json or .claude/settings.local.json).

Claude Code worktree vs branch vs git worktree

Doing it by hand with git worktree

Use plain git when you want a specific existing branch or a folder outside the repository; worktree.baseRef can't name a branch. Claude Code still shares plugins and permission approvals with these worktrees.

1. Create the worktree, start Claude, remove it when done

   Replace feature-a with a new branch name, or drop -b to check out a branch that already exists.

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

Subagents and background sessions in worktrees

• Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter in .claude/agents/, and each subagent edits in its own temporary worktree.
• A subagent worktree without changes is removed when the subagent finishes. One with changes stays until a periodic sweep can remove it without losing work, after cleanupPeriodDays.
• Background sessions (claude --bg) edit only inside a worktree by default; start one with claude --bg --worktree or set worktree.bgIsolation to "none".
• In the desktop app, turn on Worktree under the prompt box before you start a session.

Worktree cleanup and common problems

• claude -p --worktree runs have no exit prompt, so they leave their worktrees behind. Remove them with git worktree remove, after git worktree unlock if git says it's locked.
• Can only use --worktree in a git repository: run git init and make a first commit, or set up a WorktreeCreate hook for SVN, Perforce or Mercurial.
• Git LFS files show up as pointer files when LFS was installed with --local: run git lfs pull inside the worktree.
• Claude Code won't create a worktree when .claude or .claude/worktrees is a symlink.
• Hooks keep ${CLAUDE_PROJECT_DIR} pointing at the main checkout; read the cwd field of the hook input to get the worktree path.
• A worktree with "fresh" base and no commits of its own, or whose PR was merged, resets to the default branch when you reopen it by name.

Worktrees keep sessions apart. Crewmark keeps them busy.

Worktrees solve the collision problem, but each session still sits idle until you type. Crewmark turns a Claude Code, Codex, DeepSeek Harness or OpenCode session into an AI employee with a role, a goal and working hours, and wakes it on a heartbeat to take the next issue from a board.

1. One employee per worktree

   Give each employee its own worktree and role, such as a programmer and a reviewer in the same repository, as in multiple Claude Code agents.

2. Let the heartbeat start the work

   During its working hours each employee wakes every 15, 30 or 60 minutes in the same conversation; see how to make Claude Code proactive.

3. Assign issues and review branches

   Put work on the board; each employee takes an issue, commits on its own branch and messages you when it needs a decision. Read what an AI employee is.

Claude Code worktree FAQ