Parallel Sessions And Worktree — Claude Code Guide

A branch, a session, and a worktree are different levels

A branch belongs to Git and defines the change history. A Claude session stores dialogue context and focus. A worktree is an additional physical folder for the same repository with shared Git history.

A new branch does not automatically create a new session, and a new session does not isolate files. Two editing sessions in one checkout can change the same state and interfere with each other.

Create a worktree

git switch -c refund-refactor
git branch --show-current
git status

git worktree add -b hotfix/refund-amount-typo ../commerce-os-hotfix main
cd ../commerce-os-hotfix
pwd
git branch --show-current
git status -sb

Parallel hotfix

1. Continue the large refactor in the main folder.
2. Create a neighboring worktree from main for the urgent task.
3. Open a separate terminal, IDE, or Claude session in the new folder.
4. Test and commit the hotfix independently of the unfinished work.
5. After merging, remove the temporary worktree with the standard Git command.

./gradlew test --tests "*Refund*"
git worktree list
git worktree remove ../commerce-os-hotfix
git branch -d hotfix/refund-amount-typo

Warnings for parallel work

• Do not run parallel edits in one folder without coordination.
• Do not equate a Claude session with file isolation.
• Git usually does not allow one branch to be attached to two worktrees.
• Do not leave old worktrees around without a reason.
• A worktree does not transfer Claude context automatically.

When a worktree is unnecessary

A separate branch is enough for a simple task. A worktree is needed when several local states must preserve their own uncommitted changes at the same time without interfering with one another.