[FEATURE] Honor the repository's documented branch-naming convention (CLAUDE.md) for auto-created session branches

Status Open
Reported on v2.1.222
Maintainer reply None cached
Activity 3 comments · opened Aug 12, 2026

Environment

  • Claude Code 2.1.222, desktop app, macOS
  • Background / worktree sessions against a repository that documents a branch-naming convention in CLAUDE.md

Summary

Auto-created session branches use a random claude/<adjective>-<surname>-<hash> name (claude/distracted-tharp-9849c2, claude/quizzical-yalow-4ab734) and ignore a branch-naming convention documented in the repository's own CLAUDE.md.

The specific inconsistency: CLAUDE.md already takes precedence over harness git behavior in one place but not the other.

Per agent-view.md and the v2.1.221 release notes, background sessions auto-commit and push unless CLAUDE.md says the user handles git — the harness reads and defers to CLAUDE.md for commit/push. But a branch-naming convention stated in that same file has no effect. Two git behaviors, one config file, opposite treatment.

Example

The repository's CLAUDE.md states that work should use claude/<type>/<slug> branches. Human-initiated and plan-driven work in the repo follows it:

claude/feat/ap3-production-deploy
claude/docs/lp-content-playbook
claude/fix/lp-only-interior-chrome
claude/chore/open-issue-sweep-2

Auto-created session branches in the same repository do not:

claude/distracted-tharp-9849c2
claude/quizzical-yalow-4ab734

Impact

A random name says nothing about the work. In a branch list, a PR queue, or a worktree directory listing, these are unidentifiable without checking out or reading the diff — the same complaint as #18686.

It compounds with worktree naming: worktree directories keep the name of the first branch they ever held, so neither the directory name nor the branch name describes what is in it. See #85997 and #79366.

Request

Any one of these would resolve it, in rough order of preference:

  1. Honor a branch-naming convention documented in CLAUDE.md, consistent with how CLAUDE.md git instructions are already honored for commit/push.
  2. A configurable naming template in settings.json (e.g. branchNameTemplate).
  3. Task-derived slugs instead of random names. #62166 indicates task-derived branch naming previously existed on the web client and regressed to this same <adjective>-<surname>-<hash> pattern, so the capability appears to have existed.

A WorktreeCreate hook can rename after the fact, but that is a post-hoc workaround for a name the harness has already chosen and used.

Related

  • #31969 — open: "Enter/resume existing worktrees, configurable branch naming, hook removal control." This overlaps directly; happy for this to be folded into that issue if maintainers prefer. Filing separately because the CLAUDE.md-precedence angle is not raised there.
  • #62166 — task-derived branch names regressing to <adjective>-<surname>-<hash> (web)
  • #42365, #63458 — configurable worktree branch prefix / desktop parity (both closed as stale)
  • #18686 — generated branch names unidentifiable in the session dropdown
  • #85997 — no visible indication of current branch/worktree in the desktop UI

View original on GitHub ↗

3 Comments

shape-backpac · 1 month ago

Our team hit exactly this, and we now maintain a workaround whose existence is itself the argument for this feature.

Our constraint: a Jira-based branch convention (feature/ICW-xxxxx-<summary>) that feeds our commit rules, PR automation, and CI pipeline branch detection. Native worktree creation can't express it: branches are fixed to worktree-<name> / claude/<random>, and worktree.baseRef only accepts "fresh" | "head" — the docs explicitly say "You can't set worktree.baseRef to a branch name. To start a worktree from a specific existing branch, create it with git directly."

So we create worktrees with plain git worktree add — and that path silently loses the official conveniences: .worktreeinclude copying and worktree.symlinkDirectories only apply to worktrees Claude Code creates itself. In practice this meant our gitignored mkcert certs (*.pem, referenced by our npm dev scripts) were missing from every worktree, breaking the HTTPS dev server each time. A WorktreeCreate hook doesn't close the gap either: per the docs, .worktreeinclude is not processed in hook mode, and the hook input carries only a name (no source ref).

Our bridge: we taught our own worktree-creation skill to re-read the two official declarations (.worktreeinclude via git ls-files -oi --exclude-from, and worktree.symlinkDirectories from .claude/settings.json) and apply them after git worktree add. It works, but it's duplicated logic that exists only because creation takes no branch-name parameter.

A branch-name option (an explicit name or a template, or honoring a convention documented in CLAUDE.md as this issue proposes) on --worktree/EnterWorktree would let us delete the bridge and go fully native. Related: #31969, #86239.

Technotraxx · 1 month ago

Seconding this from a team that hits it on every web session.

Our repositories document the branch convention in CLAUDE.md (<type>/[TICKET-<nr>-]<short>, with type in feat·fix·chore·docs·refactor) and enforce it in CI: a workflow checks the PR head ref against ^(feat|fix|chore|docs|refactor)/[A-Za-z0-9._/-]+$ and fails the check otherwise. Claude Code on the web creates branches like dev/inspiring-euler-91qsjn. That name fails our check, so every web session produces a PR with a red check until a human renames the branch and the agent re-pushes. The rename cannot be done by the agent either — the session is pinned to the generated branch name. The inconsistency in the issue title is exactly right, and it is worth restating: the harness already defers to CLAUDE.md for how to commit and when to push. It does not defer to it for the one decision that is hardest to undo later, because the branch name is already published by the time anyone reads it. Any of the three proposals would fix it for us. In preference order: honour the convention documented in CLAUDE.md; a branchNameTemplate in settings.json; task-derived slugs (which, per #62166, used to work on the web client).
tomcasaburi · 13 days ago

Desktop app user here. The random adjective-surname-hash worktree names make the sidebar and git worktree list unreadable at a glance. The app already generates a descriptive session title from the first prompt; please derive the worktree directory and branch name from that (or rename them once the title exists), or at minimum pass the prompt/session title to the WorktreeCreate hook so users can implement it themselves.