Make worktree placement configurable

[colonelpanic8]

What Changed

• Add a persisted worktreePathTemplate server setting.
• Expand {worktreesDir}, {repoRoot}, {repoName}, and {branch} when creating worktrees.
• Keep {worktreesDir}/{repoName}/{branch} as the default, preserving the existing centralized layout.
• Add a General settings control with a one-click reset to the default.
• Apply the setting to new-session, explicit VCS, and pull-request worktree creation flows.
• Normalize relative repository roots and allow review previews for worktrees matching the configured template.

Why

Some users keep worktrees alongside each repository, while others prefer T3 Code's centralized worktree directory. A configurable template supports both layouts without changing existing behavior.

For example, {repoRoot}/.worktrees/{branch} creates repository-local worktrees.

UI Changes

The General settings panel now exposes the worktree path template and documents its available variables. Browser verification covered the default value, persisting a repository-local template, and resetting to the default.

Default centralized template	Repository-local template persisted after reload

These current screenshots were recaptured from PR head 366d6e021814242392c778d49fd195397a8cbf11 in the combined package 0.0.29-patched-main-20260724 (integration 4dd4cef4039303179929a1dbdbf0c9b358c076f9).

Checklist

• pnpm exec vp test run packages/contracts/src/settings.test.ts apps/server/src/serverSettings.test.ts apps/server/src/vcs/GitVcsDriverCore.test.ts apps/server/src/server.test.ts -t 'bootstraps first-send worktree turns|ServerSettings worktree path template|ServerSettingsPatch string normalization|server settings|uses the configured repository-local worktree path template|keeps the centralized worktree path as the default' (21 passed)
• pnpm exec vp test run apps/server/src/review/ReviewService.test.ts apps/server/src/vcs/GitVcsDriverCore.test.ts (40 passed)
• Targeted vp check for the final review-fix files (no warnings)
• pnpm exec vp check (passes with 12 pre-existing warnings in untouched files)
• pnpm --filter t3 typecheck
• pnpm --filter @t3tools/contracts typecheck
• Integrated web verification in an isolated authenticated environment against the exact combined package; default value, repository-local edit, and persistence after reload verified
• pnpm exec vp run typecheck (workspace baseline fails in untouched web/mobile files: existing implicit-any and unknown AtomRegistry errors; the affected server and contracts package checks pass)

---

Note

Medium Risk
Changes where new worktrees are created and tightens review path validation; default template preserves existing layout, but custom templates and symlinked repo roots affect filesystem layout and security boundaries.

Overview
Adds a persisted worktreePathTemplate setting (default {worktreesDir}/{repoName}/{branch}) in contracts and a Worktree path control in General settings.

Worktree creation now expands {worktreesDir}, {repoRoot}, {repoName}, and {branch} via new worktreePathTemplate helpers instead of a fixed centralized path. The template is read from server settings and passed through bootstrap, VCS createWorktree, and PR worktree flows in ws / GitManager.

Review diff preview accepts optional repositoryRoots, loads active project workspace roots through a new lightweight getActiveProjectWorkspaceRoots projection query (avoiding full shell snapshots), and allows cwd when it matches the configured template for those roots—not only the main workspace and legacy worktrees dir.

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

Note

Make worktree placement configurable via a path template setting

• Adds a worktreePathTemplate field (default {worktreesDir}/{repoName}/{branch}) to ServerSettings and ServerSettingsPatch in settings.ts, with a UI input in the General settings panel.
• Introduces resolveWorktreePathTemplate and matchesWorktreePathTemplate utilities in worktreePathTemplate.ts to expand and validate template placeholders.
• createWorktree in GitVcsDriverCore.ts now resolves the worktree path via the configured template instead of the hardcoded {worktreesDir}/{repoName}/{sanitizedBranch} scheme.
• ReviewService.getDiffPreview in ReviewService.ts now accepts optional repositoryRoots and validates candidate cwd values against the configured template in addition to existing workspace root checks.
• ProjectionSnapshotQuery gains getActiveProjectWorkspaceRoots() to supply repository roots to the diff-preview path without hydrating full shell snapshots.
• Risk: worktree paths produced by createWorktree will differ from the previous fixed scheme for any server using a custom or migrated template.

^{Macroscope summarized 72afbca.}

[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: 53bfca1a-423f-4665-b818-1e87c80817cb

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

New feature adding configurable worktree placement with a path template system. Changes runtime worktree creation behavior and modifies workspace boundary validation logic, which has security implications. The cross-cutting nature and new user-facing capability warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

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

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