Claude Code worktree base branch: why your unpushed commits are missing

TL;DR If your worktrees or subagents need to build on work you haven't pushed yet, put "worktree": { "baseRef": "head" } in .claude/settings.json. If you want every worktree to start clean from main, leave it alone: that's the default.

claude --worktree doesn't branch from the branch you're on. It branches from the remote's default branch, usually origin/main. So if you have three unpushed commits on your feature branch and open a worktree for Claude to pick up from there, those three commits aren't in it. One setting decides this, worktree.baseRef, with two values: fresh (the default) and head.

I tested it on a repo with one pushed commit and one unpushed:

$ git log --oneline
31ef515 unpushed: my local work
a785234 pushed: initial

# baseRef "fresh" (default)
$ claude -w fresh-test -p "git log --oneline"
a785234 pushed: initial

# baseRef "head"
$ claude -w head-test -p "git log --oneline"
31ef515 unpushed: my local work
a785234 pushed: initial

Same repo, same command. With fresh, the worktree starts at a785234 and your commit is left behind. With head, it starts at 31ef515 and has it.

Where it bites

Not only with claude -w. The same setting decides the starting point for:

• claude --worktree from the terminal.
• The EnterWorktree tool, when you ask Claude mid-session to "work in a worktree".
• Subagents with isolation: worktree. This is the expensive one: you hand a subagent something you're halfway through, and it works on main, without your code.

How to change it

1. Add the setting

In .claude/settings.json to apply it to the whole team, or in .claude/settings.local.json for yourself only:

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

2. Open a worktree and check

claude -w test

Ask it for git log --oneline -3 and look for your latest commit.

Which one to pick

It doesn't take a branch name. To start from a specific branch, create the worktree with git worktree add and open Claude inside it.

Three things worth knowing about fresh:

• It keeps origin/HEAD current. If the repo hasn't been fetched in 24 hours, it runs a fetch capped at five seconds before creating the worktree. If that fails (no network, or git asks for a password), it uses the local copy.
• No remote means head. If there's no remote, or it can't get origin/HEAD, it branches from your local HEAD.
• Reused names start clean. Reuse the name of a worktree that has no changes and no commits of its own, or whose PR was merged, and it resets to the default branch instead of reopening at its old tip. With head it doesn't.

And neither value carries uncommitted changes: a worktree is a checkout of a commit. If you need them there, commit first. Ignored files like .env are a different problem, the one .worktreeinclude solves.

If worktrees are new to you, start with putting several Claudes to work at once. And to review a PR, claude --worktree "#123" already fetches the PR's branch, whatever this setting says.

Official docs: Choose the base branch

Requirements

• A Claude Code release from May 2026 or later: the setting shipped between v2.1.128 and v2.1.136. Tested on v2.1.293.