Claude Code Worktree From Current Branch

To make a Claude Code worktree start from your current feature branch and include its commits, set worktree.baseRef to "head", then launch claude --worktree while that branch is checked out. By default, Claude Code starts new worktrees from the remote default branch, usually main, so commits that exist only on your feature branch are absent. The setting changes the starting commit for new worktrees; it does not copy uncommitted edits.

Why the new worktree looks like main

A worktree has its own checkout and branch. Sharing a repository’s history does not mean every checkout starts at the branch currently open in another checkout. Claude Code’s "fresh" base uses the remote default branch; "head" uses the local HEAD of the checkout where you start the session.

For example, suppose feature/auth has commits that origin/main does not. Running claude --worktree review-auth with the default base creates an agent branch from the remote default branch. Files introduced by those feature commits will therefore be missing. Running the same command with worktree.baseRef set to "head" starts the new branch at feature/auth’s current commit, so its committed files and history are available to the agent.

Base setting	Starting point	Useful when
"fresh"	Remote default branch, when available	The task should begin independently of local feature work
"head"	Current checkout’s local HEAD	The agent needs commits already made on your feature branch

If the repository has no usable remote default-branch ref, Claude Code’s fresh base can fall back to local HEAD. That makes it especially useful to check the actual starting commit when the result matters.

Set the base to your current branch

For a personal choice in one repository, put the setting in .claude/settings.local.json at the repository root. Project-local settings override the shared .claude/settings.json file. If the local file already exists, add the worktree key to its existing JSON object rather than replacing its other settings.

{
  "worktree": {
    "baseRef": "head"
  }
}

Before your first interactive worktree run in an unfamiliar repository, run claude in that checkout and accept the workspace trust dialog. Otherwise, claude --worktree exits with an error prompting you to do so. Add .claude/worktrees/ to the repository’s .gitignore so worktree contents do not appear as untracked files in the main checkout.

Check out the feature branch in your main checkout, then give the new worktree a name:

claude --worktree review-auth

Claude Code creates the named worktree under .claude/worktrees/review-auth/ on a new branch named worktree-review-auth. Use a new name when you need a newly created worktree: passing an existing worktree name can reopen that worktree at its previous tip. Changing the setting does not retroactively change a worktree you already created.

Choose the settings scope deliberately. Put the same JSON in the repository’s .claude/settings.json if everyone working on that project should inherit their current checkout’s commits. Use ~/.claude/settings.json if that is your usual starting point across projects. For a local file you created by hand, make sure .claude/settings.local.json is ignored before committing; Claude Code does not automatically exclude a hand-created file.

The value must be "head" or "fresh". worktree.baseRef cannot name feature/auth or another arbitrary branch. It also follows the checkout where Claude starts: if you launch Claude from inside an existing worktree, "head" means that worktree’s HEAD.

Check that the feature commits are present

Before launching Claude, inspect the branch and outstanding file edits. The short branch status shows both branch information and changed paths:

git status --short --branch

Then list the commits you expect the agent to inherit. A git log range such as origin/main..feature/auth selects commits reachable from the feature branch but not from the first ref:

git log --oneline origin/main..feature/auth

If your remote default branch has another name, substitute it for origin/main. An empty result means this particular comparison found no commits exclusive to feature/auth; it does not tell you whether there are uncommitted edits.

For a direct base check, record the current commit ID with git rev-parse --verify HEAD before launching Claude:

git rev-parse --verify HEAD
claude --worktree review-auth

In another terminal, inspect the new checkout before the agent commits anything:

cd .claude/worktrees/review-auth
git rev-parse --verify HEAD

The two IDs should match. Once the agent has made commits, equality is no longer the right check. Instead, test whether the recorded feature commit is an ancestor of the agent branch with git merge-base --is-ancestor, substituting the recorded commit ID for BASE_COMMIT_ID:

git merge-base --is-ancestor BASE_COMMIT_ID worktree-review-auth

An exit status of zero means that commit is in the agent branch’s history. Use the recorded ID rather than the current name feature/auth if that branch may have moved since the worktree was created.

Start from a specific branch with Git

Use Git directly when the starting branch is neither the current checkout nor the remote default. The final argument to git worktree add -b sets the new branch’s starting commit. For the example branch and a sibling directory:

git worktree add -b agent-auth ../project-agent-auth feature/auth
cd ../project-agent-auth
claude

This creates a separate branch at the current tip of feature/auth, then starts Claude inside that checkout. If you are already on feature/auth, you can use HEAD as the final argument instead. This route also lets you choose a location outside .claude/worktrees/.

Give each agent a distinct new branch and directory. Git normally refuses to check out the same branch in two worktrees, so creating agent-auth from feature/auth is different from trying to check out feature/auth again. For more on the relationship between branches and checkouts, see Git worktrees explained.

Account for edits that are not committed

"head" selects a commit, not the entire state of your working directory. Modified tracked files, staged changes, and untracked files in the original checkout do not become part of that commit. If the agent needs those changes as its starting point, commit the intended work on the feature branch before creating the worktree, or move the relevant changes into the new checkout yourself.

Claude Code’s .worktreeinclude handles a narrower case: it can copy matching files that are gitignored, such as a local environment file, into new worktrees. It is not a way to carry ordinary uncommitted source edits from the original checkout. Check what an agent actually needs before copying local files, especially configuration containing credentials.

Also distinguish an absent commit from an absent dependency or local configuration file. A worktree is a separate checkout, so project setup may need to be run there. If a committed feature file is missing, investigate the base commit first; if only a gitignored local file is missing, investigate setup and .worktreeinclude.

Fix a worktree that already started from main

Changing worktree.baseRef affects newly created worktrees. If the existing worktree has no work you need to keep, start a new one with a new name after changing the setting, verify its base, and remove the old worktree when safe.

If the agent has already made commits you need, bring your feature branch into the agent branch. First finish or save any uncommitted edits in the agent checkout. Then, from that checkout, merge the feature branch into the current branch:

cd .claude/worktrees/review-auth
git status --short
git merge feature/auth

This updates the agent branch, not feature/auth. If Git reports conflicts, resolve them and continue the merge; git merge --abort cancels an unresolved merge. Review the resulting files before the agent proceeds, because its earlier edits were made without the feature branch’s changes in view.

Afterward, a three-dot diff shows changes on the agent branch since its common ancestor with the feature branch:

git diff feature/auth...worktree-review-auth

If feature/auth has moved since the merge, interpret that diff against its new tip with care. Review the agent branch’s commits and final diff before integrating it; merging parallel agent branches covers the next step.

Where Parallel Code fits

Our product, Parallel Code, is a free, open-source desktop app for macOS and Linux that runs Claude Code and other AI coding agents in parallel, each in its own git worktree. Its diff-first review surface helps you inspect the resulting changes when multiple agents work at once.

Frequently asked questions

Does claude --worktree use my current branch by default?

No. Its usual "fresh" base is the remote default branch, so local feature commits may be absent. Set worktree.baseRef to "head" to start new Claude Code worktrees at the current checkout’s commit.

Can I pass my feature branch name to worktree.baseRef?

No. The setting accepts "fresh" and "head", not a branch name. For a specific branch that is not currently checked out, create the worktree with git worktree add -b NEW_BRANCH PATH feature/auth, then run claude from that directory.

Will "head" include my uncommitted changes?

No. It inherits the commit at local HEAD, including that commit’s ancestors, but not edits still in the original working directory. Commit the changes you want as a shared starting point, or transfer them separately.

Why did changing the setting leave my existing worktree on main?

The setting determines the base when a worktree is created; it does not rewrite an existing branch. Create a new named worktree, or merge the feature branch into the existing agent branch after safeguarding any unfinished edits.