feat(git): let users choose the worktree branch prefix

[t3dotgg]

Generated worktree branches always start with t3code/, which conflicts with personal and team branch conventions.

Add a server-owned Worktree branch prefix setting under Settings > General. It defaults to t3code, accepts validated custom prefixes, and can be cleared to create branches without a prefix. Temporary branches stay unchanged, and the server applies the prefix when it generates the final branch name for web, desktop, mobile, and remote clients.

Inspired by and with thanks to:

• @yasinkavakli for #7887
• @filipgutica for #6037
• @jssblck for #3954
• @MrSimmmons for #6428

Verified with 116 focused tests, targeted lint, and scoped typechecks for contracts, shared, client runtime, server, web, and mobile.

Model: GPT-5.6 Sol
Harness: Codex in T3 Code

---

Note

Medium Risk
Touches git branch naming and persisted server settings. Invalid prefixes are schema-validated, but misconfigured prefixes still change how worktrees are renamed for all clients.

Overview
Users can now set a Worktree branch prefix in Settings > General. Generated worktree names still default to t3code/…, but a custom prefix (including nested paths like teams/platform) is applied server-side, and clearing the field creates unprefixed branches.

buildGeneratedWorktreeBranchName strips a leftover t3code/ from the model output when it is not the configured prefix, then sanitizes the remainder. Temporary worktree branches are unchanged.

The new worktreeBranchPrefix setting is validated (lowercase, max 64, no // or leading/trailing separators) and wired through dirty/reset/search plus user docs.

^{Reviewed by Cursor Bugbot for commit 5e5ed3f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add configurable worktreeBranchPrefix setting defaulting to t3code

• Adds a worktreeBranchPrefix field to ServerSettings, defaulting to t3code and validated by the new WorktreeBranchPrefix schema (max 64 chars, lowercase alphanumerics, no adjacent slashes).
• Updates buildGeneratedWorktreeBranchName in ProviderCommandReactor.ts to accept a prefix argument and sanitize it via sanitizeBranchFragment.
• Adds a UI control in the General Settings panel to edit the prefix, with settings search indexing and restore-defaults support.
• Behavioral Change: buildGeneratedWorktreeBranchName now requires a prefix parameter; existing callers must be updated.

^{Macroscope summarized 5e5ed3f.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bd599c0a-8952-4a17-8434-437982ab0bd6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.4 KiB	13.4 KiB	+6 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+2 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+4 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.0 KiB	55.0 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.4 KiB	−29 B (−0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−1 B (−0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.6 KiB	6.5 KiB	−28 B (−0.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	55.8 KiB	55.8 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: e6a109b · PR result: 5e5ed3f · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e2c3e50. Configure here.}

[macroscopeapp]

Approvability

Verdict: Approved at 5e5ed3f

Macroscope's review found this PR approvable — This adds a persisted and validated worktree branch-prefix setting while retaining t3code for legacy and default configurations. Custom behavior is limited to the existing first-turn branch rename path, with focused server and contract test coverage.

Notes:

• Diff unchanged. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[MrSimmmons]

For my example of #6428, do you have thoughts on allowing full branch name customization at worktree creation rather than just the prefix instead?
The way that my teams works is we use the prefix of the branch to indicate the type of branch (so bug/..., feat/... etc) and just allowing the customization of it wouldn't really work for that use case.
Otherwise I don't really see the a use for the prefix of a branch?

Where as if you gave people the option to just fully customize the branch name on worktree creation, they can then have whatever they want and everyone wins

[jetpham]

@MrSimmmons branch prefixes are conventionally used for distinguishing the main developer of a branch in the form "MrSimmons/fix-ssrf" so having settings globally to set your "name" then that being used as your branch prefix seems correct here. I've seen in the past conventional commit style for commits and pr titles which can be helpful for categorization.

[vitorpacheco]

Cool feature! One question though — is worktreeBranchPrefix meant to stay global/server-wide, or could it also work as a per-project override?

I bounce between a few repos that each have their own branch convention.

[dev2adventure]

I feel like this doesn't fully resolve the issue at hand, since, for example, the branch names supplied by Linear follow a strict pattern, and we would need full customization for that and not just branch name prefixes.

[kevhardy]

I think people are focusing on this PR as if it’s the one PR meant to fix every single branch naming problem they have. But the reality is, the only fixed portion of what we can’t change today is this t3code/ prefix. If this PR allows us to either remove that or change the value, I think that is a very good step in the right direction.

There may be more branch naming options in the future, like naming the branch yourself when creating a thread or allowing a custom prompt for the source control writer to determine branch names. I personally think those are out of scope for this PR, especially considering there are already plenty of workarounds, such as telling your agents to rename branches to fit your needs.

[GuusDeGraeve]

Agreed with @kevhardy, being able to change or remove the prefix is more than enough. Anything beyond that can be handled by putting branch naming guidelines in AGENTS.md or CLAUDE.md. As long as the t3code/ prefix isn't enforced, everything stays possible.

[Rasalas]

also agreeing with @kevhardy and @GuusDeGraeve here.

This should be merged "as is" (if the issues are fixed)- this probably solves like 95% of people's problems. Linear compat could be separate ticket/MR.

I was experimenting with an optional input in the "new worktree" flow.
In my imagination - if you hit this:

you just open an optional input that allows you to put anything you want there.
If you send, it autogenerates. If you switch to the prompt, it defaults to autogenerate. Only if you set "New worktree" and then type, it sets what you decided.
I feel like this would solve 99% of peoples problems.

[aaronkerckhoff]

I agree that this PR probably should be merged as-is.
But I would be open to file a stacked PR to expand the branch naming feature. I'd add custom naming rules as well as the ability for maintainers to set certain naming rules for their repo (perhaps in t3.json?) as requested by @juliusmarminge in #6865.

[match-josephcampuzano]

Wondering if we can get this through. I agree that this is a good first step and solves the 80% problem for most people. Those with more strict naming conventions or something along those lines could probably be solved later.

Atm I just ask the agent to rename my branches before PR's but this would remove that extra step.

Thanks!

[JSMike]

I would prefer something closer to #8967, as the naming conventions vary. But this would be good for setting a global default.

[tarurar]

Would be really nice to have this feature.