[BUG] `claude --worktree <name>` bases on origin/<default> not parent HEAD + prepends `worktree-` to branch name — breaks multi-session identifier-verbatim convention
Describe the bug
claude --worktree <chat-name> has two silent defaults that together break a multi-session coordination convention many users rely on — every team I've talked to that runs N parallel sessions for a single repo treats the worktree dir / branch name / per-session pointer file / cross-session log session field as a single shared identifier per session. The harness defaults silently rewrite both the base and the branch name, so the identifier the user typed at claude --worktree is no longer byte-identical with the worktree dir or the branch:
- Wrong base — the worktree is created on
origin/<github-default-branch>(typicallymainormaster) instead of the parent shell's current HEAD branch. For repos where the GitHub default branch is far behind the active integration branch (long-lived feature lines, release cuts, post-merge tracking branches), the worktree is born missing recent commits — including, in our empirical case, the very plan doc the session was asked to execute. See related #45316 for the wrong-base symptom in isolation. worktree-branch-name prefix — the harness names the branchworktree-<chat-name>instead of clean<chat-name>. This meansgit worktree listandgit branch --show-currentreturn a different string than the worktree directory name, breaking any multi-session reconciliation that keys on a single identifier (e.g. cross-referencinggit worktree listagainst per-session pointer files or a coordination log). Related #54653 / #31969 touch branch naming from different angles.
Steps to reproduce
- Have a repo where the parent shell's current HEAD is not the GitHub default branch (e.g. on a long-lived integration branch
round-6-post-merge-trackingwhile default ismaster). - Run
claude --worktree my-session-name. - Observe:
git rev-parse HEADin the new worktree points atorigin/master(or wherever the GitHub default is), not at the parent shell's HEAD.git branch --show-currentreturnsworktree-my-session-name, notmy-session-name.
Expected behavior
claude --worktree <name>bases the worktree on the parent shell's current HEAD by default (the working set the user just came from is the most likely intended base).- An explicit
--worktree-base <ref>flag for when the default isn't right. - The branch name is exactly
<name>(noworktree-prefix). The convention should be: the string the user typed is the string everywhere — worktree dir, branch, anything else.
Actual behavior
- Worktree based on
origin/<github-default-branch>regardless of parent shell HEAD. - Branch named
worktree-<name>, so the worktree dir is<name>but the branch isworktree-<name>— they no longer match.
Empirical anchor (2-event, ~24h apart, same repo)
- 2026-05-23
worktree-review-archivesession-start — parent shell onround-6-post-merge-tracking(~140 commits ahead oforigin/master);claude --worktree worktree-review-archiveproduced a worktree onorigin/masterwith branchworktree-worktree-review-archive. The plan doc the session was asked to execute didn't exist on the harness-chosen base. Reconciled manually viagit reset --hard origin/round-6-post-merge-tracking+git branch -m worktree-worktree-review-archive worktree-review-archive. - 2026-05-24
track-and-addresssession-start — deliberately avoidedclaude --worktreeand usedgit worktree add .claude/worktrees/track-and-address -b track-and-address origin/round-6-post-merge-trackingmanually exactly to dodge the same defaults a second time. This session (the one filing this issue,b669-upstream-report) did the same.
In-repo mitigation we shipped
Because the parent shell can't always rely on the harness defaults, our SESSION_RESUME/README.md § "When a new chat session starts" now has a sub-section "Harness-defaults reconciliation (known operator step)" that documents the 2-step verify-and-reconcile (git reset --hard origin/<intended-base> + git branch -m worktree-<name> <name>) plus the recommended alternative: don't use claude --worktree at all for sessions opened off a non-default integration branch; run git worktree add .claude/worktrees/<name> -b <name> origin/<intended-base> manually and start Claude inside it. That manual path is what this very session (b669-upstream-report) used to file this issue.
The mitigation closes the gap operationally but the harness defaults still surprise everyone the first time, and every multi-session cohort pays a per-session reconciliation tax.
Proposed fix
- Base — default to the parent shell's HEAD (via
git rev-parse HEADin the cwd at invocation time). Accept an explicit--worktree-base <ref>flag for override. - Branch name — use
<name>verbatim. Drop theworktree-prefix from the auto-generated branch name. If a<name>branch already exists, fail loudly rather than silently mangling.
Together, these would let claude --worktree <name> honor the "the string you typed is the string everywhere" convention, eliminating per-session reconciliation friction for multi-session coordination workflows.
Related
- #45316 — wrong-base symptom in isolation
- #31969 / #54653 / #61419 / #60588 — adjacent worktree branch-naming / base-selection concerns
This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗