feat(settings): choose the branch new worktrees start from

apps/mobile/src/features/settings/SettingsServerControlsRouteScreen.tsx

@@ -25,6 +25,7 @@ import {
 } from "./components/SettingsEnvironmentFilterHeader";
 import { BranchNamingSettings } from "./components/BranchNamingSettings";
 import { DatabaseStorageNotice } from "./components/DatabaseStorageNotice";
+import { WorktreeBaseBranchField } from "./components/WorktreeBaseBranchField";
 import { SettingsChoiceRow } from "./components/SettingsChoiceRow";
 import { SettingsSection } from "./components/SettingsSection";
 import { SettingsSwitchRow } from "./components/SettingsSwitchRow";
@@ -55,6 +56,7 @@ const PAGE_PROJECT_KEYS: Record<SettingsPage, readonly ProjectScopedServerSettin
     "defaultAutoPull",
     "removeAgentCreditsOnMerge",
     "newWorktreesStartFromOrigin",
+    "newWorktreesBaseBranch",
     "branchNamingMode",
     "branchNamePrefix",
     "branchNameInstructions",
@@ -393,6 +395,11 @@ function ServerSettingsDetail(props: { readonly page: SettingsPage }) {
                       disabled={disabledFor("newWorktreesStartFromOrigin")}
                       onValueChange={(value) => write({ newWorktreesStartFromOrigin: value })}
                     />
+                    <WorktreeBaseBranchField
+                      value={uniform("newWorktreesBaseBranch")}
+                      disabled={disabledFor("newWorktreesBaseBranch")}
+                      onChange={write}
+                    />
                   </SettingsSection>
                 </>
               ) : null}

apps/mobile/src/features/settings/components/WorktreeBaseBranchField.tsx

@@ -0,0 +1,50 @@
+import type { ServerSettingsPatch } from "@t3tools/contracts";
+import { useEffect, useEffectEvent, useRef } from "react";
+import { View } from "react-native";
+
+import { AppText as Text, AppTextInput } from "../../../components/ui/AppText";
+
+/** Base branch for new worktrees. `null` means the selected targets differ. */
+export function WorktreeBaseBranchField(props: {
+  value: string | null;
+  disabled: boolean;
+  onChange: (patch: ServerSettingsPatch) => void;
+}) {
+  // Typed text waits here until it saves. Android's Back closes the keyboard
+  // without ending editing, so leaving the screen saves it too.
+  const draft = useRef<{ text: string; over: string | null } | null>(null);
+  // A newer saved value remounts the input, so a draft typed over an older
+  // one is no longer on screen and is dropped.
+  const save = () => {
+    const current = draft.current;
+    draft.current = null;
+    if (current === null || current.over !== props.value) return;
+    const value = current.text.trim();
+    if (props.value === null || value !== props.value) {
+      props.onChange({ newWorktreesBaseBranch: value });
+    }
+  };
+  const saveOnLeave = useEffectEvent(save);
+  useEffect(() => () => saveOnLeave(), []);
+  return (
+    <View className="gap-2 px-4 py-3">
+      <Text className="text-sm text-foreground-muted">
+        New worktrees start from this branch. Leave empty to use the default branch.
+      </Text>
+      <AppTextInput
+        key={props.value}
+        accessibilityLabel="Worktree base branch"
+        onChangeText={(text) => {
+          draft.current = { text, over: props.value };
+        }}
+        defaultValue={props.value ?? ""}
+        placeholder={props.value === null ? "Mixed" : "Default branch"}
+        editable={!props.disabled}
+        autoCapitalize="none"
+        autoCorrect={false}
+        className="min-h-10 rounded-xl px-3 py-2 text-base text-foreground"
+        onEndEditing={save}
+      />
+    </View>
+  );
+}

apps/mobile/src/features/threads/new-task-flow-provider.tsx

@@ -892,9 +892,14 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
     if (live && (live.mode !== "worktree" || live.branch !== null)) {
       return;
     }
-    // The default may only exist as origin/<default> (isRemote), which
-    // availableBranches filters out — search the unfiltered refs for it.
+    // The project's configured base branch wins. The default may only exist
+    // as origin/<default> (isRemote), which availableBranches filters out —
+    // search the unfiltered refs for it.
+    const configuredBaseBranch = projectSettings.settings.newWorktreesBaseBranch;
     const preferredBranch =
+      (configuredBaseBranch.length > 0
+        ? allBranchRefs.find((branch) => branch.name === configuredBaseBranch)
+        : undefined) ??
       allBranchRefs.find((branch) => branch.isDefault) ??
       availableBranches.find((branch) => branch.current) ??
       null;
@@ -905,6 +910,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
     allBranchRefs,
     availableBranches,
     defaultWorkspaceModeSettled,
+    projectSettings.settings.newWorktreesBaseBranch,
     selectBranch,
     selectedBranchName,
     selectedProjectDraftKey,

apps/web/src/components/BranchToolbar.logic.test.ts

@@ -7,6 +7,7 @@ import {
   resolveDraftEnvModeAfterBranchChange,
   resolveEffectiveEnvMode,
   resolveBranchToolbarPrBranch,
+  resolveWorktreeBaseBranch,
   resolveLocalCheckoutBranchMismatch,
   sanitizeNewRefName,
   shouldIncludeBranchPickerItem,
@@ -254,3 +255,32 @@ describe("sanitizeNewRefName", () => {
     expect(sanitizeNewRefName("foo--bar")).toBe("foo--bar");
   });
 });
+
+describe("resolveWorktreeBaseBranch", () => {
+  it("prefers the project's configured base branch over the repo default", () => {
+    expect(
+      resolveWorktreeBaseBranch({
+        configuredBaseBranch: "develop",
+        defaultBranch: "main",
+        currentGitBranch: "feature/x",
+      }),
+    ).toBe("develop");
+  });
+
+  it("falls back to the repo default, then the checked-out branch", () => {
+    expect(
+      resolveWorktreeBaseBranch({
+        configuredBaseBranch: "",
+        defaultBranch: "main",
+        currentGitBranch: "feature/x",
+      }),
+    ).toBe("main");
+    expect(
+      resolveWorktreeBaseBranch({
+        configuredBaseBranch: "",
+        defaultBranch: null,
+        currentGitBranch: "feature/x",
+      }),
+    ).toBe("feature/x");
+  });
+});

apps/web/src/components/BranchToolbar.logic.ts

@@ -201,6 +201,21 @@ export function resolveBranchToolbarValue(input: {
   return currentGitBranch ?? activeThreadBranch;
 }
 
+/**
+ * Base branch a new worktree draft starts from: the project's configured base
+ * branch, then the repo default branch (origin/HEAD), then the checked-out one.
+ */
+export function resolveWorktreeBaseBranch(input: {
+  configuredBaseBranch: string;
+  defaultBranch: string | null;
+  currentGitBranch: string | null;
+}): string | null {
+  if (input.configuredBaseBranch.length > 0) {
+    return input.configuredBaseBranch;
+  }
+  return input.defaultBranch ?? input.currentGitBranch;
+}
+
 export function resolveBranchTriggerLabel(input: {
   activeWorktreePath: string | null;
   effectiveEnvMode: EnvMode;

apps/web/src/components/BranchToolbarBranchSelector.tsx

@@ -34,6 +34,8 @@ import { readLocalApi } from "../localApi";
 import { useOpenPrLink } from "../lib/openPullRequestLink";
 import { usePaginatedBranches } from "../state/queries";
 import { useProject, useQuietThreadShell } from "../state/entities";
+import { useEnvironmentSettings } from "../hooks/useSettings";
+import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
 import { useEnvironmentQuery } from "../state/query";
 import { readEnvironmentScope, useEnvironmentScope } from "~/state/session";
 import { threadEnvironment } from "../state/threads";
@@ -53,6 +55,7 @@ import {
   resolveBranchToolbarValue,
   resolveDraftEnvModeAfterBranchChange,
   resolveEffectiveEnvMode,
+  resolveWorktreeBaseBranch,
   sanitizeNewRefName,
   shouldIncludeBranchPickerItem,
 } from "./BranchToolbar.logic";
@@ -143,6 +146,7 @@ export function BranchToolbarBranchSelector({
       ? scopeProjectRef(draftThread.environmentId, draftThread.projectId)
       : null;
   const activeProject = useProject(activeProjectRef);
+  const settings = useEnvironmentSettings(environmentId);
 
   const activeThreadId = serverThread?.id ?? (draftThread ? threadId : undefined);
   const activeThreadBranch =
@@ -477,9 +481,18 @@ export function BranchToolbarBranchSelector({
     });
   };
 
+  const configuredBaseBranch = resolveProjectSettings(
+    settings,
+    activeProject?.id ?? null,
+    activeProject ?? undefined,
+  ).settings.newWorktreesBaseBranch;
   const worktreeBaseBranchCandidate = isInitialBranchesLoadPending
     ? null
-    : (defaultBranchName ?? currentGitBranch);
+    : resolveWorktreeBaseBranch({
+        configuredBaseBranch,
+        defaultBranch: defaultBranchName,
+        currentGitBranch,
+      });
 
   // A started thread's server is creating its worktree and records the branch
   // itself; defaulting it here would reset the thread to the base checkout and

apps/web/src/components/settings/SettingsPanels.tsx

@@ -171,6 +171,7 @@ import {
   useSettingsSearchTargetId,
 } from "./settingsLayout";
 import { searchableSetting } from "./settingsSearch";
+import { WorktreeBaseBranchSetting } from "./WorktreeBaseBranchSetting";
 import { ProjectFavicon } from "../ProjectFavicon";
 import { PanelAnimationsPreview } from "./PanelAnimationsPreview";
 
@@ -3024,6 +3025,7 @@ export function GeneralSettingsPanel() {
             />
           }
         />
+        <WorktreeBaseBranchSetting />
         <SettingsRow
           serverScoped
           settingKeys={["addProjectBaseDirectory"]}

apps/web/src/components/settings/WorktreeBaseBranchSetting.tsx

@@ -0,0 +1,62 @@
+import { useRef } from "react";
+import { DEFAULT_SERVER_SETTINGS } from "@t3tools/contracts";
+
+import { Input } from "../ui/input";
+import { SettingsRow, SettingResetButton } from "./settingsLayout";
+import { useSettingsScope } from "./SettingsScopeContext";
+import { searchableSetting } from "./settingsSearch";
+import {
+  useScopedSettings,
+  useScopedSettingsMixed,
+  useUpdateScopedSettings,
+} from "./useScopedSettings";
+
+export function WorktreeBaseBranchSetting() {
+  const settings = useScopedSettings();
+  const { targets } = useSettingsScope();
+  const scopeKey = targets.map((target) => `${target.environmentId}:${target.projectId}`).join(",");
+  const edited = useRef(false);
+  const updateSettings = useUpdateScopedSettings();
+  const mixed = useScopedSettingsMixed(["newWorktreesBaseBranch"]);
+
+  return (
+    <SettingsRow
+      serverScoped
+      settingKeys={["newWorktreesBaseBranch"]}
+      {...searchableSetting("worktree-base-branch")}
+      description="New worktrees start from this branch. Leave empty to use the repository default branch."
+      resetAction={
+        mixed ||
+        settings.newWorktreesBaseBranch !== DEFAULT_SERVER_SETTINGS.newWorktreesBaseBranch ? (
+          <SettingResetButton
+            label="worktree base branch"
+            onClick={() =>
+              updateSettings({
+                newWorktreesBaseBranch: DEFAULT_SERVER_SETTINGS.newWorktreesBaseBranch,
+              })
+            }
+          />
+        ) : null
+      }
+      control={
+        <Input
+          key={`${scopeKey}:${mixed}:${settings.newWorktreesBaseBranch}`}
+          aria-label="Worktree base branch"
+          autoCapitalize="none"
+          spellCheck={false}
+          onChange={() => {
+            edited.current = true;
+          }}
+          placeholder={mixed ? "Mixed" : "Default branch"}
+          defaultValue={mixed ? "" : settings.newWorktreesBaseBranch}
+          onBlur={(event) => {
+            const value = event.target.value.trim();
+            if (edited.current && (mixed || value !== settings.newWorktreesBaseBranch))
+              updateSettings({ newWorktreesBaseBranch: value });
+            edited.current = false;
+          }}
+        />
+      }
+    />
+  );
+}

apps/web/src/components/settings/settingsSearch.ts

@@ -485,6 +485,13 @@ export const SETTINGS_SEARCH_ITEMS = [
     scope: "project-defaults",
     searchTerms: ["new worktrees start remote origin latest fetched branch local"],
   },
+  {
+    id: "worktree-base-branch",
+    title: "Worktree base branch",
+    to: "/settings/general",
+    scope: "project-defaults",
+    searchTerms: ["new worktrees start from develop main default branch origin head"],
+  },
   {
     id: "add-project-starts-in",
     title: "Add project starts in",

docs/user/project-settings.md

@@ -60,6 +60,15 @@ to override its environment defaults. Worktree directories keep their original n
 If generation fails, or a custom name is invalid or already taken, the temporary
 branch name remains.
 
+## Worktree base branch
+
+New worktrees start from the repository default branch. To start them from another branch,
+such as `develop`, set **Settings → General → Worktree base branch**. Select a project to set it
+for that project only. On mobile, use **Settings → Source control → Worktrees**.
+
+Leave the field empty to use the default branch again. You can still pick another branch for one
+thread in the branch selector before you send the first message.
+
 ## Scheduled tasks on mobile
 
 Open **Settings → Scheduled tasks** to create recurring tasks or manage existing

packages/contracts/src/settings.ts

@@ -936,6 +936,7 @@ export const PROJECT_SCOPED_SERVER_SETTING_KEYS = [
   "defaultRuntimeMode",
   "defaultThreadEnvMode",
   "newWorktreesStartFromOrigin",
+  "newWorktreesBaseBranch",
   "worktreeSubmodules",
   "defaultAutoPull",
   "defaultProjectScripts",
@@ -979,6 +980,7 @@ export const ProjectSettingsOverrides = Schema.Struct({
   defaultRuntimeMode: Schema.optionalKey(RuntimeMode),
   defaultThreadEnvMode: Schema.optionalKey(ThreadEnvMode),
   newWorktreesStartFromOrigin: Schema.optionalKey(Schema.Boolean),
+  newWorktreesBaseBranch: Schema.optionalKey(TrimmedString),
   worktreeSubmodules: ForwardCompatibleOptional(WorktreeSubmodules),
   defaultAutoPull: Schema.optionalKey(Schema.Boolean),
   defaultProjectScripts: Schema.optionalKey(Schema.Array(ProjectScript)),
@@ -1202,6 +1204,8 @@ export const ServerSettings = Schema.Struct({
   newWorktreesStartFromOrigin: Schema.Boolean.pipe(
     Schema.withDecodingDefault(Effect.succeed(true)),
   ),
+  /** Branch new worktrees start from. Empty uses the repository default branch (origin/HEAD). */
+  newWorktreesBaseBranch: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
   /**
    * Null defers to the repository's t3.json, then to recursive. A value
    * picked on a newer server decodes as null here rather than failing the
@@ -1494,6 +1498,7 @@ export const ServerSettingsPatch = Schema.Struct({
   environmentIcon: Schema.optionalKey(Schema.NullOr(EnvironmentMachineKind)),
   defaultThreadEnvMode: Schema.optionalKey(Schema.NullOr(ThreadEnvMode)),
   newWorktreesStartFromOrigin: Schema.optionalKey(Schema.Boolean),
+  newWorktreesBaseBranch: Schema.optionalKey(TrimmedString),
   worktreeSubmodules: Schema.optionalKey(Schema.NullOr(WorktreeSubmodules)),
   addProjectBaseDirectory: Schema.optionalKey(TrimmedString),
   textGenerationModelSelection: Schema.optionalKey(ModelSelectionPatch),