🤖 Persist runtime preference per project (#428)

## Overview

Adds persistent runtime preference storage per project, so users don't
have to repeatedly select local vs SSH runtime when creating multiple
workspaces for the same project.

## Changes

### 1. Persist runtime preference on workspace creation
- Added `getRuntimeKey()` to storage constants (format:
`runtime:{projectPath}`)
- Save runtime string to localStorage after successful workspace
creation
- Only saves when runtime is explicitly provided (not default local)

### 2. Load saved preferences in NewWorkspaceModal
- Modal now accepts `projectPath` prop
- Loads saved preference when modal opens
- Pre-fills form with user's last choice

### 3. Created `useNewWorkspaceOptions` hook
- Centralized runtime options management with localStorage persistence
- Provides `runtimeMode`, `sshHost`, and `getRuntimeString()` helper
- Eliminates duplication between modal and command-line paths
- Single source of truth for runtime preference logic

### 4. Updated `/new` command to respect saved preferences
- When `-r` flag not provided, loads saved runtime for the project
- Explicit `-r` flag still overrides saved preference
- Consistent behavior across all workspace creation paths

### 5. Deduplicated runtime mode types and constants
- Added shared `RuntimeMode` type and `RUNTIME_MODE` constants to
`src/types/runtime.ts`
- Added `SSH_RUNTIME_PREFIX` constant
- Added `parseRuntimeModeAndHost()` and `buildRuntimeString()` utilities
- Eliminated magic strings (`"local"`, `"ssh"`, `"ssh "`) across
codebase
- Updated hook, modal, and command utilities to use shared types

## Behavior

- **First time creating a workspace**: Uses default (local) or user's
explicit choice
- **After successful creation**: Runtime preference is saved for that
project
- **Next workspace creation (modal)**: Saved preference pre-fills the
form
- **Next workspace creation (`/new`)**: Saved preference used if `-r`
not specified
- **Explicit override**: `-r` flag in `/new` command always takes
precedence

## Testing

- All tests pass (4 pre-existing unrelated failures)
- Typecheck passes
- Updated Storybook stories to include `projectPath` prop

## Benefits

✅ **Better UX** - Users set their preference once per project, not every
workspace
✅ **Consistency** - Same behavior across modal and `/new` command  
✅ **Type safety** - Compiler catches typos and misuse  
✅ **No magic strings** - Constants prevent string literal bugs  
✅ **Easier refactoring** - Adding new runtime modes only requires
updating one file
✅ **Reduced duplication** - Centralized logic in reusable hook

_Generated with `cmux`_

Author: ammar-agent

src/App.tsx

@@ -25,7 +25,7 @@ import type { ThinkingLevel } from "./types/thinking";
 import type { RuntimeConfig } from "./types/runtime";
 import { CUSTOM_EVENTS } from "./constants/events";
 import { isWorkspaceForkSwitchEvent } from "./utils/workspaceFork";
-import { getThinkingLevelKey } from "./constants/storage";
+import { getThinkingLevelKey, getRuntimeKey } from "./constants/storage";
 import type { BranchListResult } from "./types/ipc";
 import { useTelemetry } from "./hooks/useTelemetry";
 import { parseRuntimeString } from "./utils/chatCommands";
@@ -268,6 +268,12 @@ function AppInner() {
       // Track workspace creation
       telemetry.workspaceCreated(newWorkspace.workspaceId);
       setSelectedWorkspace(newWorkspace);
+
+      // Save runtime preference for this project if provided
+      if (runtime) {
+        const runtimeKey = getRuntimeKey(workspaceModalProject);
+        localStorage.setItem(runtimeKey, runtime);
+      }
     }
   };
 
@@ -669,6 +675,7 @@ function AppInner() {
           <NewWorkspaceModal
             isOpen={workspaceModalOpen}
             projectName={workspaceModalProjectName}
+            projectPath={workspaceModalProject}
             branches={workspaceModalBranches}
             defaultTrunkBranch={workspaceModalDefaultTrunk}
             loadErrorMessage={workspaceModalLoadError}

src/components/NewWorkspaceModal.stories.tsx

@@ -21,6 +21,10 @@ const meta = {
       control: "text",
       description: "Name of the project",
     },
+    projectPath: {
+      control: "text",
+      description: "Path to the project",
+    },
     branches: {
       control: "object",
       description: "List of available branches",
@@ -47,6 +51,7 @@ export const Default: Story = {
   args: {
     isOpen: true,
     projectName: "my-project",
+    projectPath: "/path/to/my-project",
     branches: ["main", "develop", "feature/new-feature"],
     defaultTrunkBranch: "main",
   },
@@ -56,6 +61,7 @@ export const LongProjectName: Story = {
   args: {
     isOpen: true,
     projectName: "very-long-project-name-that-demonstrates-wrapping",
+    projectPath: "/path/to/very-long-project-name-that-demonstrates-wrapping",
     branches: ["main", "develop"],
     defaultTrunkBranch: "main",
   },
@@ -65,6 +71,7 @@ export const NoBranches: Story = {
   args: {
     isOpen: true,
     projectName: "empty-project",
+    projectPath: "/path/to/empty-project",
     branches: [],
   },
 };
@@ -73,6 +80,7 @@ export const ManyBranches: Story = {
   args: {
     isOpen: true,
     projectName: "active-project",
+    projectPath: "/path/to/active-project",
     branches: [
       "main",
       "develop",
@@ -90,6 +98,7 @@ export const Closed: Story = {
   args: {
     isOpen: false,
     projectName: "my-project",
+    projectPath: "/path/to/my-project",
     branches: ["main", "develop"],
     defaultTrunkBranch: "main",
   },

src/components/NewWorkspaceModal.tsx

@@ -2,10 +2,13 @@ import React, { useEffect, useId, useState } from "react";
 import { Modal, ModalInfo, ModalActions, CancelButton, PrimaryButton } from "./Modal";
 import { TooltipWrapper, Tooltip } from "./Tooltip";
 import { formatNewCommand } from "@/utils/chatCommands";
+import { useNewWorkspaceOptions } from "@/hooks/useNewWorkspaceOptions";
+import { RUNTIME_MODE } from "@/types/runtime";
 
 interface NewWorkspaceModalProps {
   isOpen: boolean;
   projectName: string;
+  projectPath: string;
   branches: string[];
   defaultTrunkBranch?: string;
   loadErrorMessage?: string | null;
@@ -20,6 +23,7 @@ const formFieldClasses =
 const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
   isOpen,
   projectName,
+  projectPath,
   branches,
   defaultTrunkBranch,
   loadErrorMessage,
@@ -28,13 +32,15 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
 }) => {
   const [branchName, setBranchName] = useState("");
   const [trunkBranch, setTrunkBranch] = useState(defaultTrunkBranch ?? branches[0] ?? "");
-  const [runtimeMode, setRuntimeMode] = useState<"local" | "ssh">("local");
-  const [sshHost, setSshHost] = useState("");
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const infoId = useId();
   const hasBranches = branches.length > 0;
 
+  // Load runtime preferences from localStorage for this project
+  const [runtimeOptions, setRuntimeOptions] = useNewWorkspaceOptions(projectPath);
+  const { runtimeMode, sshHost, getRuntimeString } = runtimeOptions;
+
   useEffect(() => {
     setError(loadErrorMessage ?? null);
   }, [loadErrorMessage]);
@@ -59,8 +65,7 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
   const handleCancel = () => {
     setBranchName("");
     setTrunkBranch(defaultTrunkBranch ?? branches[0] ?? "");
-    setRuntimeMode("local");
-    setSshHost("");
+    setRuntimeOptions(RUNTIME_MODE.LOCAL, "");
     setError(loadErrorMessage ?? null);
     onClose();
   };
@@ -83,7 +88,7 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
     console.assert(trimmedBranchName.length > 0, "Expected branch name to be validated");
 
     // Validate SSH host if SSH runtime selected
-    if (runtimeMode === "ssh") {
+    if (runtimeMode === RUNTIME_MODE.SSH) {
       const trimmedHost = sshHost.trim();
       if (trimmedHost.length === 0) {
         setError("SSH host is required (e.g., hostname or user@host)");
@@ -97,14 +102,13 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
     setError(null);
 
     try {
-      // Build runtime string if SSH selected
-      const runtime = runtimeMode === "ssh" ? `ssh ${sshHost.trim()}` : undefined;
+      // Get runtime string from hook helper
+      const runtime = getRuntimeString();
 
       await onAdd(trimmedBranchName, normalizedTrunkBranch, runtime);
       setBranchName("");
       setTrunkBranch(defaultTrunkBranch ?? branches[0] ?? "");
-      setRuntimeMode("local");
-      setSshHost("");
+      setRuntimeOptions(RUNTIME_MODE.LOCAL, "");
       onClose();
     } catch (err) {
       const message = err instanceof Error ? err.message : "Failed to create workspace";
@@ -203,25 +207,28 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
             id="runtimeMode"
             value={runtimeMode}
             onChange={(event) => {
-              setRuntimeMode(event.target.value as "local" | "ssh");
+              const newMode = event.target.value as
+                | typeof RUNTIME_MODE.LOCAL
+                | typeof RUNTIME_MODE.SSH;
+              setRuntimeOptions(newMode, newMode === RUNTIME_MODE.LOCAL ? "" : sshHost);
               setError(null);
             }}
             disabled={isLoading}
           >
-            <option value="local">Local</option>
-            <option value="ssh">SSH Remote</option>
+            <option value={RUNTIME_MODE.LOCAL}>Local</option>
+            <option value={RUNTIME_MODE.SSH}>SSH Remote</option>
           </select>
         </div>
 
-        {runtimeMode === "ssh" && (
+        {runtimeMode === RUNTIME_MODE.SSH && (
           <div className={formFieldClasses}>
             <label htmlFor="sshHost">SSH Host:</label>
             <input
               id="sshHost"
               type="text"
               value={sshHost}
               onChange={(event) => {
-                setSshHost(event.target.value);
+                setRuntimeOptions(RUNTIME_MODE.SSH, event.target.value);
                 setError(null);
               }}
               placeholder="hostname or user@hostname"
@@ -238,7 +245,7 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
         <ModalInfo id={infoId}>
           <p>This will create a git worktree at:</p>
           <code className="block break-all">
-            {runtimeMode === "ssh"
+            {runtimeMode === RUNTIME_MODE.SSH
               ? `${sshHost || "<host>"}:~/cmux/${branchName || "<branch-name>"}`
               : `~/.cmux/src/${projectName}/${branchName || "<branch-name>"}`}
           </code>
@@ -251,7 +258,7 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
               {formatNewCommand(
                 branchName.trim(),
                 trunkBranch.trim() || undefined,
-                runtimeMode === "ssh" && sshHost.trim() ? `ssh ${sshHost.trim()}` : undefined
+                getRuntimeString()
               )}
             </div>
           </div>

src/constants/storage.ts

@@ -63,6 +63,15 @@ export function getModeKey(workspaceId: string): string {
   return `mode:${workspaceId}`;
 }
 
+/**
+ * Get the localStorage key for the default runtime for a project
+ * Stores the last successfully used runtime config when creating a workspace
+ * Format: "runtime:{projectPath}"
+ */
+export function getRuntimeKey(projectPath: string): string {
+  return `runtime:${projectPath}`;
+}
+
 /**
  * Get the localStorage key for the 1M context preference (global)
  * Format: "use1MContext"

src/hooks/useNewWorkspaceOptions.ts

@@ -0,0 +1,68 @@
+import { useState, useEffect } from "react";
+import { getRuntimeKey } from "@/constants/storage";
+import {
+  type RuntimeMode,
+  RUNTIME_MODE,
+  parseRuntimeModeAndHost,
+  buildRuntimeString,
+} from "@/types/runtime";
+
+export interface WorkspaceRuntimeOptions {
+  runtimeMode: RuntimeMode;
+  sshHost: string;
+  /**
+   * Returns the runtime string for IPC calls (format: "ssh <host>" or undefined for local)
+   */
+  getRuntimeString: () => string | undefined;
+}
+
+/**
+ * Hook to manage workspace creation runtime options with localStorage persistence.
+ * Loads saved runtime preference for a project and provides consistent state management.
+ *
+ * @param projectPath - Path to the project (used as key for localStorage)
+ * @returns Runtime options state and setter
+ */
+export function useNewWorkspaceOptions(
+  projectPath: string | null | undefined
+): [WorkspaceRuntimeOptions, (mode: RuntimeMode, host?: string) => void] {
+  const [runtimeMode, setRuntimeMode] = useState<RuntimeMode>(RUNTIME_MODE.LOCAL);
+  const [sshHost, setSshHost] = useState("");
+
+  // Load saved runtime preference when projectPath changes
+  useEffect(() => {
+    if (!projectPath) {
+      // Reset to defaults when no project
+      setRuntimeMode(RUNTIME_MODE.LOCAL);
+      setSshHost("");
+      return;
+    }
+
+    const runtimeKey = getRuntimeKey(projectPath);
+    const savedRuntime = localStorage.getItem(runtimeKey);
+    const parsed = parseRuntimeModeAndHost(savedRuntime);
+
+    setRuntimeMode(parsed.mode);
+    setSshHost(parsed.host);
+  }, [projectPath]);
+
+  // Setter for updating both mode and host
+  const setRuntimeOptions = (mode: RuntimeMode, host?: string) => {
+    setRuntimeMode(mode);
+    setSshHost(host ?? "");
+  };
+
+  // Helper to get runtime string for IPC calls
+  const getRuntimeString = (): string | undefined => {
+    return buildRuntimeString(runtimeMode, sshHost);
+  };
+
+  return [
+    {
+      runtimeMode,
+      sshHost,
+      getRuntimeString,
+    },
+    setRuntimeOptions,
+  ];
+}

src/types/runtime.ts

@@ -2,6 +2,18 @@
  * Runtime configuration types for workspace execution environments
  */
 
+/** Runtime mode type - used in UI and runtime string parsing */
+export type RuntimeMode = "local" | "ssh";
+
+/** Runtime mode constants */
+export const RUNTIME_MODE = {
+  LOCAL: "local" as const,
+  SSH: "ssh" as const,
+} as const;
+
+/** Runtime string prefix for SSH mode (e.g., "ssh hostname") */
+export const SSH_RUNTIME_PREFIX = "ssh ";
+
 export type RuntimeConfig =
   | {
       type: "local";
@@ -19,3 +31,46 @@ export type RuntimeConfig =
       /** Optional: SSH port (default: 22) */
       port?: number;
     };
+
+/**
+ * Parse runtime string from localStorage or UI input into mode and host
+ * Format: "ssh <host>" -> { mode: "ssh", host: "<host>" }
+ *         "local" or undefined -> { mode: "local", host: "" }
+ *
+ * Use this for UI state management (localStorage, form inputs)
+ */
+export function parseRuntimeModeAndHost(runtime: string | null | undefined): {
+  mode: RuntimeMode;
+  host: string;
+} {
+  if (!runtime) {
+    return { mode: RUNTIME_MODE.LOCAL, host: "" };
+  }
+
+  const trimmed = runtime.trim();
+  const lowerTrimmed = trimmed.toLowerCase();
+
+  if (lowerTrimmed === RUNTIME_MODE.LOCAL) {
+    return { mode: RUNTIME_MODE.LOCAL, host: "" };
+  }
+
+  if (lowerTrimmed.startsWith(SSH_RUNTIME_PREFIX)) {
+    const host = trimmed.substring(SSH_RUNTIME_PREFIX.length).trim();
+    return { mode: RUNTIME_MODE.SSH, host };
+  }
+
+  // Default to local for unrecognized strings
+  return { mode: RUNTIME_MODE.LOCAL, host: "" };
+}
+
+/**
+ * Build runtime string for storage/IPC from mode and host
+ * Returns: "ssh <host>" for SSH, undefined for local
+ */
+export function buildRuntimeString(mode: RuntimeMode, host: string): string | undefined {
+  if (mode === RUNTIME_MODE.SSH) {
+    const trimmedHost = host.trim();
+    return trimmedHost ? `${SSH_RUNTIME_PREFIX}${trimmedHost}` : undefined;
+  }
+  return undefined;
+}