feat(git): allow custom worktree branch prefixes

[filipgutica]

Summary

I've been using t3code a lot, I love it, great work! I found this one limitation I keep running into. I love having new threads spawn a new worktree, however, I'd love it if we could specify the branch prefix so I don't have to manually change it (or have the agent to do it) every time.

Allow users to choose the branch prefix for new worktrees instead of always using t3code/.

Changes

• Added a server-owned worktreeBranchPrefix setting to General Settings.
• Applied the selected environment's prefix across web, desktop, and mobile.
• Used the prefix for temporary branch detection, semantic branch names, and drift protection.
• Kept support for legacy t3code branches.
• Documented that T3 Code does not keep previous custom prefixes.

Note

Add configurable worktreeBranchPrefix to ServerSettings and thread it through worktree branch generation

• Introduces WorktreeBranchPrefix schema in settings.ts with default t3code, enforcing trim, lowercase, max length 64, and regex ^[a-z0-9][a-z0-9_-]*$
• Updates buildTemporaryWorktreeBranchName and isTemporaryWorktreeBranch in git.ts to accept an optional prefix; isTemporaryWorktreeBranch matches both configured and legacy UUID-shaped temporary branches
• Adds a settings input row in SettingsPanels.tsx with validation, search indexing, and restore-to-default support
• Updates all worktree bootstrap call sites (mobile, web, outbox drain, checkpoint reactor, provider command reactor) to pass the server-configured prefix instead of relying on a hardcoded or caller-generated temporary name
• Risk: isTemporaryWorktreeBranch in git.ts now matches both the configured prefix and legacy t3code/UUID patterns; callers that previously assumed only the default prefix must pass the configured prefix or detection may misclassify branches

^{Macroscope summarized cec345a.}

---

Note

Medium Risk
Changes thread worktree branch naming and server-side rename/drift logic across web, mobile, and orchestration; misconfiguration or prefix changes can leave older custom-prefix temporaries unmatched.

Overview
Adds a per-server worktreeBranchPrefix setting (default t3code) so new worktree threads can use a custom branch namespace instead of hard-coded t3code/.

Settings & contracts: WorktreeBranchPrefix is validated in server settings; General Settings gets an editable field with reset/search support, and user docs describe behavior (including that changing the prefix does not rename existing branches).

Clients: Web ChatView, mobile new-task creation, and the mobile outbox drain pass the environment’s prefix into thread bootstrap. Mobile centralizes temporary branch naming in buildProjectThreadStartTurnInput (replacing pre-built worktreeBranchName).

Git helpers: buildTemporaryWorktreeBranchName and isTemporaryWorktreeBranch take an optional prefix; matching still treats legacy t3code placeholders as temporary when a custom prefix is configured.

Server: ProviderCommandReactor builds semantic rename targets under the configured prefix and strips duplicate prefixes from generated names. CheckpointReactor and client resolveLiveThreadBranchUpdate use the prefix so drift/reconciliation does not adopt or regress onto temporary placeholder checkouts.

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

[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: bf50f511-2f25-463a-b87f-5b9dc6a9bf90

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

---

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a cross-cutting worktree branch-prefix capability spanning settings, web/mobile creation flows, shared Git logic, and server-side rename and drift handling. An unresolved comment also identifies a settings-failure path that can leave branch metadata stale and affect PR attribution.

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

[macroscopeapp]

One finding on the new worktree branch prefix settings row: the validation message renders in the row's default muted status tone, so it reads like ordinary help text even though the input is flagged aria-invalid.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

UI consistency review of the web changes. One finding on the new General settings row placement; the earlier validation-status color note is resolved in this revision.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

This row is inserted between the new-threads row and the row that is visually nested under it. start-from-origin is rendered as a dependent sub-row of New threads (className="bg-muted/20 sm:pl-9", and SETTINGS_SEARCH_ITEMS points it back with targetId: "new-threads"), so when the default mode is worktree the indented, muted row now sits directly under Worktree branch prefix and reads as its child instead of a child of New threads.

Consider moving this row below the conditional start-from-origin block (and the matching SETTINGS_SEARCH_ITEMS entry after start-from-origin) so the parent/child indentation keeps pointing at the setting it modifies.

^{Posted via Macroscope — UI Consistency}

[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.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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

[cursor]

Settings failure skips branch drift

Medium Severity

A failed getSettings read now returns from followWorktreeBranchDrift before any checkout adoption. That path previously followed non-temporary branch changes without settings. Transient settings errors can leave thread branch metadata stale and orphan PR attribution, including when the checkout is a normal branch that does not need the prefix.

 

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

We're closing this PR as we clean up the T3 Code backlog. Thank you for taking the time to put this together.

This adds configurable worktree branch prefixes through contracts, server behavior, web settings, and mobile settings. We are not adding this new worktree naming option through the current backlog.

If you believe we closed this in error, please reopen the PR and leave a comment explaining what we missed.