🤖 fix: allow non-git directories and clarify trunk branch requirement (#1068)

## Summary

Two issues addressed:

### 1. Trunk branch warning was confusing on local workspaces
Local runtime doesn't use trunk branch at all (it works directly in the
project directory). The trunk branch selector was already hidden for
local runtime, but the backend still required a trunk branch value -
this led to confusing validation errors.

**Fix:** Made `trunkBranch` optional in the API. Backend now only
validates trunk branch for worktree/SSH runtimes that actually need it.

### 2. Git repo requirement was unnecessary  
Users should be able to add any directory as a project, even if it's not
a git repository. Non-git directories are perfectly valid for local
runtime which just runs Claude in the directory.

**Fix:** 
- Removed git repository validation from `validateProjectPath`
- Added `isGitRepository` helper to check git status separately
- `listBranches` returns empty array (not error) for non-git repos
- Runtime selector disables worktree/SSH with tooltip "Requires git
repository"
- UI auto-selects local runtime for non-git directories

### Changes

| File | Change |
|------|--------|
| `src/common/orpc/schemas/api.ts` | Make `trunkBranch` optional |
| `src/common/orpc/schemas/message.ts` | `recommendedTrunk` nullable |
| `src/node/utils/pathUtils.ts` | Remove git requirement, add
`isGitRepository` helper |
| `src/node/services/projectService.ts` | Return empty branches for
non-git |
| `src/node/services/workspaceService.ts` | Trunk branch validation only
for worktree/SSH |
| `src/browser/components/RuntimeIconSelector.tsx` | New `disabledModes`
prop with tooltip |
| `src/browser/components/ChatInput/CreationControls.tsx` | Force local
runtime for non-git |

### Testing
- Updated `pathUtils.test.ts` - validates non-git directories pass
- Updated `projectCreate.test.ts` - validates non-git projects work with
local runtime
- All existing tests continue to pass

_Generated with `mux`_

Author: ammar-agent

docs/system-prompt.mdx

@@ -46,8 +46,39 @@ When the user asks you to remember something:
 
 /**
  * Build environment context XML block describing the workspace.
+ * @param workspacePath - Workspace directory path
+ * @param runtimeType - Runtime type: "local", "worktree", or "ssh"
  */
-function buildEnvironmentContext(workspacePath: string): string {
+function buildEnvironmentContext(
+  workspacePath: string,
+  runtimeType: "local" | "worktree" | "ssh"
+): string {
+  if (runtimeType === "local") {
+    // Local runtime works directly in project directory - may or may not be git
+    return `
+<environment>
+You are working in a directory at ${workspacePath}
+
+- Tools run here automatically
+- You are meant to do your work isolated from the user and other agents
+</environment>
+`;
+  }
+
+  if (runtimeType === "ssh") {
+    // SSH runtime clones the repository on a remote host
+    return `
+<environment>
+You are in a clone of a git repository at ${workspacePath}
+
+- This IS a git repository - run git commands directly (no cd needed)
+- Tools run here automatically
+- You are meant to do your work isolated from the user and other agents
+</environment>
+`;
+  }
+
+  // Worktree runtime creates a git worktree locally
   return `
 <environment>
 You are in a git worktree at ${workspacePath}

src/browser/App.tsx

@@ -318,16 +318,17 @@ function AppInner() {
   const getBranchesForProject = useCallback(
     async (projectPath: string): Promise<BranchListResult> => {
       if (!api) {
-        return { branches: [], recommendedTrunk: "" };
+        return { branches: [], recommendedTrunk: null };
       }
       const branchResult = await api.projects.listBranches({ projectPath });
       const sanitizedBranches = branchResult.branches.filter(
         (branch): branch is string => typeof branch === "string"
       );
 
-      const recommended = sanitizedBranches.includes(branchResult.recommendedTrunk)
-        ? branchResult.recommendedTrunk
-        : (sanitizedBranches[0] ?? "");
+      const recommended =
+        branchResult.recommendedTrunk && sanitizedBranches.includes(branchResult.recommendedTrunk)
+          ? branchResult.recommendedTrunk
+          : (sanitizedBranches[0] ?? null);
 
       return {
         branches: sanitizedBranches,

src/browser/components/ChatInput/CreationControls.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback } from "react";
+import React, { useCallback, useEffect } from "react";
 import { RUNTIME_MODE, type RuntimeMode } from "@/common/types/runtime";
 import { Select } from "../Select";
 import { RuntimeIconSelector } from "../RuntimeIconSelector";
@@ -9,6 +9,8 @@ import type { WorkspaceNameState } from "@/browser/hooks/useWorkspaceName";
 
 interface CreationControlsProps {
   branches: string[];
+  /** Whether branches have finished loading (to distinguish loading vs non-git repo) */
+  branchesLoaded: boolean;
   trunkBranch: string;
   onTrunkBranchChange: (branch: string) => void;
   runtimeMode: RuntimeMode;
@@ -25,15 +27,26 @@ interface CreationControlsProps {
 /**
  * Additional controls shown only during workspace creation
  * - Trunk branch selector (which branch to fork from) - hidden for Local runtime
- * - Runtime mode (Local, Worktree, SSH)
+ * - Runtime mode (Local, Worktree, SSH) - only Local available for non-git directories
  * - Workspace name (auto-generated with manual override)
  */
 export function CreationControls(props: CreationControlsProps) {
+  // Non-git directories (empty branches after loading completes) can only use local runtime
+  // Don't check until branches have loaded to avoid prematurely switching runtime
+  const isNonGitRepo = props.branchesLoaded && props.branches.length === 0;
+
   // Local runtime doesn't need a trunk branch selector (uses project dir as-is)
   const showTrunkBranchSelector =
     props.branches.length > 0 && props.runtimeMode !== RUNTIME_MODE.LOCAL;
 
-  const { nameState } = props;
+  const { runtimeMode, onRuntimeModeChange, nameState } = props;
+
+  // Force local runtime for non-git directories (only after branches loaded)
+  useEffect(() => {
+    if (isNonGitRepo && runtimeMode !== RUNTIME_MODE.LOCAL) {
+      onRuntimeModeChange(RUNTIME_MODE.LOCAL);
+    }
+  }, [isNonGitRepo, runtimeMode, onRuntimeModeChange]);
 
   const handleNameChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -121,6 +134,7 @@ export function CreationControls(props: CreationControlsProps) {
           defaultMode={props.defaultRuntimeMode}
           onSetDefault={props.onSetDefaultRuntime}
           disabled={props.disabled}
+          disabledModes={isNonGitRepo ? [RUNTIME_MODE.WORKTREE, RUNTIME_MODE.SSH] : undefined}
         />
 
         {/* Trunk Branch Selector - hidden for Local runtime */}

src/browser/components/ChatInput/index.tsx

@@ -1605,6 +1605,7 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
             {variant === "creation" && (
               <CreationControls
                 branches={creationState.branches}
+                branchesLoaded={creationState.branchesLoaded}
                 trunkBranch={creationState.trunkBranch}
                 onTrunkBranchChange={creationState.setTrunkBranch}
                 runtimeMode={creationState.runtimeMode}

src/browser/components/ChatInput/useCreationWorkspace.ts

@@ -58,6 +58,8 @@ function syncCreationPreferences(projectPath: string, workspaceId: string): void
 
 interface UseCreationWorkspaceReturn {
   branches: string[];
+  /** Whether listBranches has completed (to distinguish loading vs non-git repo) */
+  branchesLoaded: boolean;
   trunkBranch: string;
   setTrunkBranch: (branch: string) => void;
   runtimeMode: RuntimeMode;
@@ -94,6 +96,7 @@ export function useCreationWorkspace({
 }: UseCreationWorkspaceOptions): UseCreationWorkspaceReturn {
   const { api } = useAPI();
   const [branches, setBranches] = useState<string[]>([]);
+  const [branchesLoaded, setBranchesLoaded] = useState(false);
   const [recommendedTrunk, setRecommendedTrunk] = useState<string | null>(null);
   const [toast, setToast] = useState<Toast | null>(null);
   const [isSending, setIsSending] = useState(false);
@@ -133,13 +136,16 @@ export function useCreationWorkspace({
     if (!projectPath.length || !api) {
       return;
     }
+    setBranchesLoaded(false);
     const loadBranches = async () => {
       try {
         const result = await api.projects.listBranches({ projectPath });
         setBranches(result.branches);
         setRecommendedTrunk(result.recommendedTrunk);
       } catch (err) {
         console.error("Failed to load branches:", err);
+      } finally {
+        setBranchesLoaded(true);
       }
     };
     void loadBranches();
@@ -249,6 +255,7 @@ export function useCreationWorkspace({
 
   return {
     branches,
+    branchesLoaded,
     trunkBranch: settings.trunkBranch,
     setTrunkBranch,
     runtimeMode: settings.runtimeMode,

src/browser/components/RuntimeIconSelector.tsx

@@ -12,6 +12,8 @@ interface RuntimeIconSelectorProps {
   /** Called when user checks "Default for project" in tooltip */
   onSetDefault: (mode: RuntimeMode) => void;
   disabled?: boolean;
+  /** Modes that cannot be selected (e.g., worktree/SSH for non-git repos) */
+  disabledModes?: RuntimeMode[];
   className?: string;
 }
 
@@ -58,6 +60,8 @@ interface RuntimeIconButtonProps {
   onClick: () => void;
   onSetDefault: () => void;
   disabled?: boolean;
+  /** Why this mode is unavailable (shown in tooltip when disabled) */
+  unavailableReason?: string;
 }
 
 function RuntimeIconButton(props: RuntimeIconButtonProps) {
@@ -98,15 +102,19 @@ function RuntimeIconButton(props: RuntimeIconButtonProps) {
       >
         <strong>{info.label}</strong>
         <p className="text-muted mt-0.5 text-xs">{info.description}</p>
-        <label className="mt-1.5 flex cursor-pointer items-center gap-1.5 text-xs">
-          <input
-            type="checkbox"
-            checked={props.isDefault}
-            onChange={() => props.onSetDefault()}
-            className="accent-accent h-3 w-3"
-          />
-          <span className="text-muted">Default for project</span>
-        </label>
+        {props.unavailableReason ? (
+          <p className="mt-1 text-xs text-yellow-500">{props.unavailableReason}</p>
+        ) : (
+          <label className="mt-1.5 flex cursor-pointer items-center gap-1.5 text-xs">
+            <input
+              type="checkbox"
+              checked={props.isDefault}
+              onChange={() => props.onSetDefault()}
+              className="accent-accent h-3 w-3"
+            />
+            <span className="text-muted">Default for project</span>
+          </label>
+        )}
       </TooltipContent>
     </Tooltip>
   );
@@ -120,24 +128,29 @@ function RuntimeIconButton(props: RuntimeIconButtonProps) {
  */
 export function RuntimeIconSelector(props: RuntimeIconSelectorProps) {
   const modes: RuntimeMode[] = [RUNTIME_MODE.LOCAL, RUNTIME_MODE.WORKTREE, RUNTIME_MODE.SSH];
+  const disabledModes = props.disabledModes ?? [];
 
   return (
     <div
       className={cn("inline-flex items-center gap-1", props.className)}
       data-component="RuntimeIconSelector"
       data-tutorial="runtime-selector"
     >
-      {modes.map((mode) => (
-        <RuntimeIconButton
-          key={mode}
-          mode={mode}
-          isSelected={props.value === mode}
-          isDefault={props.defaultMode === mode}
-          onClick={() => props.onChange(mode)}
-          onSetDefault={() => props.onSetDefault(mode)}
-          disabled={props.disabled}
-        />
-      ))}
+      {modes.map((mode) => {
+        const isModeDisabled = disabledModes.includes(mode);
+        return (
+          <RuntimeIconButton
+            key={mode}
+            mode={mode}
+            isSelected={props.value === mode}
+            isDefault={props.defaultMode === mode}
+            onClick={() => props.onChange(mode)}
+            onSetDefault={() => props.onSetDefault(mode)}
+            disabled={Boolean(props.disabled) || isModeDisabled}
+            unavailableReason={isModeDisabled ? "Requires git repository" : undefined}
+          />
+        );
+      })}
     </div>
   );
 }

src/browser/contexts/ProjectContext.tsx

@@ -172,7 +172,7 @@ export function ProjectProvider(props: { children: ReactNode }) {
         setWorkspaceModalState((prev) => ({
           ...prev,
           branches,
-          defaultTrunkBranch: recommendedTrunk,
+          defaultTrunkBranch: recommendedTrunk ?? undefined,
           loadErrorMessage: null,
           isLoading: false,
         }));

src/common/orpc/schemas/api.ts

@@ -179,7 +179,8 @@ export const workspace = {
     input: z.object({
       projectPath: z.string(),
       branchName: z.string(),
-      trunkBranch: z.string(),
+      /** Trunk branch to fork from - only required for worktree/SSH runtimes, ignored for local */
+      trunkBranch: z.string().optional(),
       /** Human-readable title (e.g., "Fix plan mode over SSH") - optional for backwards compat */
       title: z.string().optional(),
       runtimeConfig: RuntimeConfigSchema.optional(),

src/common/orpc/schemas/message.ts

@@ -97,5 +97,6 @@ export const MuxMessageSchema = z.object({
 
 export const BranchListResultSchema = z.object({
   branches: z.array(z.string()),
-  recommendedTrunk: z.string(),
+  /** Recommended trunk branch, or null for non-git directories */
+  recommendedTrunk: z.string().nullable(),
 });

src/node/services/projectService.ts

@@ -1,5 +1,5 @@
 import type { Config, ProjectConfig } from "@/node/config";
-import { validateProjectPath } from "@/node/utils/pathUtils";
+import { validateProjectPath, isGitRepository } from "@/node/utils/pathUtils";
 import { listLocalBranches, detectDefaultTrunkBranch } from "@/node/git";
 import type { Result } from "@/common/types/result";
 import { Ok, Err } from "@/common/types/result";
@@ -138,6 +138,12 @@ export class ProjectService {
         throw new Error(validation.error ?? "Invalid project path");
       }
       const normalizedPath = validation.expandedPath!;
+
+      // Non-git repos return empty branches - they're restricted to local runtime only
+      if (!(await isGitRepository(normalizedPath))) {
+        return { branches: [], recommendedTrunk: null };
+      }
+
       const branches = await listLocalBranches(normalizedPath);
       const recommendedTrunk = await detectDefaultTrunkBranch(normalizedPath, branches);
       return { branches, recommendedTrunk };