🤖 Add /fork command for workspace cloning (#291)

Adds `/fork <new-name>` slash command to clone workspaces during
development, enabling quick exploration of alternative approaches
without losing the current context.

## What Changed

**Command syntax:**
```
/fork new-workspace-name
Optional multiline start message
```

**Clones entire workspace:**
- Git worktree with independent branch
- Chat history (committed messages only)
- UI preferences (model, mode, thinking level, etc.)

**Seamless mid-stream forking:** If a stream is active when forking, the
partial response is automatically committed to history first. Both
workspaces get the response content up to the fork point, then continue
independently.

## Implementation

**Backend (`src/services/ipcMain.ts`):**
- Validates workspace name
- Auto-commits streaming responses before fork
- Creates git worktree from current branch (not trunk)
- Copies `chat.jsonl`, skips `partial.json`
- Generates stable workspace ID (10-char hex)

**Frontend (`src/components/ChatInput.tsx`):**
- Parses `/fork` command with optional start message
- Copies workspace storage to new workspace
- Switches UI to forked workspace
- Optionally sends start message after 300ms

**Type safety:**
- Imports `WorkspaceMetadata` in IPC layer
- Uses `metadata.name` for directory paths (not ID)

## Testing

6 integration tests covering:
- Name validation (invalid formats rejected)
- Successful workspace creation
- Chat history copying
- Config updates
- Independent git branches
- `partial.json` handling (not copied)

All tests run concurrently for speed.

## Technical Notes

**Stable IDs architecture:** Workspaces have separate ID (stable,
10-char hex) and name (mutable, user-facing). Directories use names,
metadata uses IDs. Fork handler correctly uses `metadata.name` for path
computation via `getWorkspacePath()`.

**Auto-commit rationale:** `PartialService.commitToHistory()` is
idempotent and file-locked, making it safe to call during streaming.
This preserves work without forcing manual interruption (ESC → fork
workflow).

_Generated with `cmux`_

---------

Co-authored-by: Ammar Bandukwala <ammar@ammar.io>

Author: ammar-agent

docs/SUMMARY.md

@@ -9,6 +9,7 @@
 # Features
 
 - [Workspaces](./workspaces.md)
+  - [Forking](./fork.md)
 - [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.md)
   - [Vim Mode](./vim-mode.md)

docs/fork.md

@@ -0,0 +1,30 @@
+# Forking Workspaces
+
+Use `/fork` to clone a workspace with its full conversation history and UI state. The forked workspace gets a new git worktree on a new branch.
+
+Usage:
+
+```
+/fork <new-workspace-name>
+
+[start-message (optional)]
+```
+
+## Use cases
+
+- **Explore alternatives**: Fork mid-conversation to try a different implementation
+  approach.
+- **Isolate tangents**: See an unrelated bug or opportunity in the course of a change? Fork to keep the main conversation on track.
+- **Create backup**: Fork to keep a copy of an old conversation before a risky change in direction.
+
+## What happens when you fork
+
+The new workspace:
+
+- Appears at the top of the workspace list (most recent)
+- Gets a unique auto-generated name (customize via rename after creation)
+- Branches from the current workspace's HEAD commit
+
+**What's copied**: Conversation history, model selection, thinking level, auto-retry setting, UI mode (plan/exec), chat input text
+
+**What's not copied**: Uncommitted file changes (new branch starts from HEAD)

src/App.tsx

@@ -29,6 +29,7 @@ import { buildCoreSources, type BuildSourcesParams } from "./utils/commands/sour
 
 import type { ThinkingLevel } from "./types/thinking";
 import { CUSTOM_EVENTS } from "./constants/events";
+import { isWorkspaceForkSwitchEvent } from "./utils/workspaceFork";
 import { getThinkingLevelKey } from "./constants/storage";
 import type { BranchListResult } from "./types/ipc";
 import { useTelemetry } from "./hooks/useTelemetry";
@@ -201,6 +202,7 @@ function AppInner() {
 
   const {
     workspaceMetadata,
+    setWorkspaceMetadata,
     loading: metadataLoading,
     createWorkspace,
     removeWorkspace,
@@ -727,6 +729,45 @@ function AppInner() {
     openCommandPalette,
   ]);
 
+  // Handle workspace fork switch event
+  useEffect(() => {
+    const handleForkSwitch = (e: Event) => {
+      if (!isWorkspaceForkSwitchEvent(e)) return;
+
+      const workspaceInfo = e.detail;
+
+      // Find the project in config
+      const project = projects.get(workspaceInfo.projectPath);
+      if (!project) {
+        console.error(`Project not found for path: ${workspaceInfo.projectPath}`);
+        return;
+      }
+
+      // Update metadata Map immediately (don't wait for async metadata event)
+      // This ensures the title bar effect has the workspace name available
+      setWorkspaceMetadata((prev) => {
+        const updated = new Map(prev);
+        updated.set(workspaceInfo.id, workspaceInfo);
+        return updated;
+      });
+
+      // Switch to the new workspace
+      setSelectedWorkspace({
+        workspaceId: workspaceInfo.id,
+        projectPath: workspaceInfo.projectPath,
+        projectName: workspaceInfo.projectName,
+        namedWorkspacePath: workspaceInfo.namedWorkspacePath,
+      });
+    };
+
+    window.addEventListener(CUSTOM_EVENTS.WORKSPACE_FORK_SWITCH, handleForkSwitch as EventListener);
+    return () =>
+      window.removeEventListener(
+        CUSTOM_EVENTS.WORKSPACE_FORK_SWITCH,
+        handleForkSwitch as EventListener
+      );
+  }, [projects, setSelectedWorkspace, setWorkspaceMetadata]);
+
   return (
     <>
       <GlobalColors />

src/components/ChatInput.tsx

@@ -11,6 +11,7 @@ import { useMode } from "@/contexts/ModeContext";
 import { ChatToggles } from "./ChatToggles";
 import { useSendMessageOptions } from "@/hooks/useSendMessageOptions";
 import { getModelKey, getInputKey } from "@/constants/storage";
+import { forkWorkspace } from "@/utils/workspaceFork";
 import { ToggleGroup } from "./ToggleGroup";
 import { CUSTOM_EVENTS } from "@/constants/events";
 import type { UIMode } from "@/types/mode";
@@ -237,6 +238,26 @@ const createCommandToast = (parsed: ParsedCommand): Toast | null => {
         ),
       };
 
+    case "fork-help":
+      return {
+        id: Date.now().toString(),
+        type: "error",
+        title: "Fork Command",
+        message: "Fork current workspace with a new name",
+        solution: (
+          <>
+            <SolutionLabel>Usage:</SolutionLabel>
+            /fork &lt;new-name&gt; [optional start message]
+            <br />
+            <br />
+            <SolutionLabel>Examples:</SolutionLabel>
+            /fork experiment-branch
+            <br />
+            /fork refactor Continue with refactoring approach
+          </>
+        ),
+      };
+
     case "unknown-command": {
       const cmd = "/" + parsed.command + (parsed.subcommand ? " " + parsed.subcommand : "");
       return {
@@ -738,6 +759,52 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           return;
         }
 
+        // Handle /fork command
+        if (parsed.type === "fork") {
+          setInput(""); // Clear input immediately
+          setIsSending(true);
+
+          try {
+            const forkResult = await forkWorkspace({
+              sourceWorkspaceId: workspaceId,
+              newName: parsed.newName,
+              startMessage: parsed.startMessage,
+              sendMessageOptions,
+            });
+
+            if (!forkResult.success) {
+              const errorMsg = forkResult.error ?? "Failed to fork workspace";
+              console.error("Failed to fork workspace:", errorMsg);
+              setToast({
+                id: Date.now().toString(),
+                type: "error",
+                title: "Fork Failed",
+                message: errorMsg,
+              });
+              setInput(messageText); // Restore input on error
+            } else {
+              setToast({
+                id: Date.now().toString(),
+                type: "success",
+                message: `Forked to workspace "${parsed.newName}"`,
+              });
+            }
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : "Failed to fork workspace";
+            console.error("Fork error:", error);
+            setToast({
+              id: Date.now().toString(),
+              type: "error",
+              title: "Fork Failed",
+              message: errorMsg,
+            });
+            setInput(messageText); // Restore input on error
+          }
+
+          setIsSending(false);
+          return;
+        }
+
         // Handle all other commands - show display toast
         const commandToast = createCommandToast(parsed);
         if (commandToast) {

src/constants/events.ts

@@ -34,6 +34,12 @@ export const CUSTOM_EVENTS = {
    * useResumeManager handles this idempotently - safe to emit multiple times
    */
   RESUME_CHECK_REQUESTED: "cmux:resumeCheckRequested",
+
+  /**
+   * Event to switch to a different workspace after fork
+   * Detail: { workspaceId: string, projectPath: string, projectName: string, workspacePath: string, branch: string }
+   */
+  WORKSPACE_FORK_SWITCH: "cmux:workspaceForkSwitch",
 } as const;
 
 /**

src/constants/ipc-constants.ts

@@ -24,6 +24,7 @@ export const IPC_CHANNELS = {
   WORKSPACE_CREATE: "workspace:create",
   WORKSPACE_REMOVE: "workspace:remove",
   WORKSPACE_RENAME: "workspace:rename",
+  WORKSPACE_FORK: "workspace:fork",
   WORKSPACE_STREAM_META: "workspace:streamMeta",
   WORKSPACE_SEND_MESSAGE: "workspace:sendMessage",
   WORKSPACE_RESUME_STREAM: "workspace:resumeStream",

src/constants/storage.ts

@@ -69,3 +69,29 @@ export const USE_1M_CONTEXT_KEY = "use1MContext";
 export function getCompactContinueMessageKey(workspaceId: string): string {
   return `compactContinueMessage:${workspaceId}`;
 }
+
+/**
+ * Copy all workspace-specific localStorage keys from source to destination workspace
+ * This includes: model, input, mode, thinking level, auto-retry, retry state
+ */
+export function copyWorkspaceStorage(sourceWorkspaceId: string, destWorkspaceId: string): void {
+  // List of key-generating functions to copy
+  // Note: We deliberately skip getCompactContinueMessageKey as it's ephemeral
+  const keyFunctions: Array<(workspaceId: string) => string> = [
+    getModelKey,
+    getInputKey,
+    getModeKey,
+    getThinkingLevelKey,
+    getAutoRetryKey,
+    getRetryStateKey,
+  ];
+
+  for (const getKey of keyFunctions) {
+    const sourceKey = getKey(sourceWorkspaceId);
+    const destKey = getKey(destWorkspaceId);
+    const value = localStorage.getItem(sourceKey);
+    if (value !== null) {
+      localStorage.setItem(destKey, value);
+    }
+  }
+}

src/git.ts

@@ -27,7 +27,7 @@ export async function listLocalBranches(projectPath: string): Promise<string[]>
     .sort((a, b) => a.localeCompare(b));
 }
 
-async function getCurrentBranch(projectPath: string): Promise<string | null> {
+export async function getCurrentBranch(projectPath: string): Promise<string | null> {
   try {
     using proc = execAsync(`git -C "${projectPath}" rev-parse --abbrev-ref HEAD`);
     const { stdout } = await proc.result;

src/hooks/useWorkspaceManagement.ts

@@ -55,12 +55,25 @@ export function useWorkspaceManagement({
       (event: { workspaceId: string; metadata: FrontendWorkspaceMetadata | null }) => {
         setWorkspaceMetadata((prev) => {
           const updated = new Map(prev);
+          const isNewWorkspace = !prev.has(event.workspaceId) && event.metadata !== null;
+
           if (event.metadata === null) {
             // Workspace deleted - remove from map
             updated.delete(event.workspaceId);
           } else {
             updated.set(event.workspaceId, event.metadata);
           }
+
+          // If this is a new workspace (e.g., from fork), reload projects
+          // to ensure the sidebar shows the updated workspace list
+          if (isNewWorkspace) {
+            void (async () => {
+              const projectsList = await window.api.projects.list();
+              const loadedProjects = new Map<string, ProjectConfig>(projectsList);
+              onProjectsUpdate(loadedProjects);
+            })();
+          }
+
           return updated;
         });
       }
@@ -69,7 +82,7 @@ export function useWorkspaceManagement({
     return () => {
       unsubscribe();
     };
-  }, []);
+  }, [onProjectsUpdate]);
 
   const createWorkspace = async (projectPath: string, branchName: string, trunkBranch: string) => {
     console.assert(
@@ -164,6 +177,7 @@ export function useWorkspaceManagement({
 
   return {
     workspaceMetadata,
+    setWorkspaceMetadata,
     loading,
     createWorkspace,
     removeWorkspace,

src/preload.ts

@@ -55,6 +55,8 @@ const api: IPCApi = {
       ipcRenderer.invoke(IPC_CHANNELS.WORKSPACE_REMOVE, workspaceId, options),
     rename: (workspaceId: string, newName: string) =>
       ipcRenderer.invoke(IPC_CHANNELS.WORKSPACE_RENAME, workspaceId, newName),
+    fork: (sourceWorkspaceId: string, newName: string) =>
+      ipcRenderer.invoke(IPC_CHANNELS.WORKSPACE_FORK, sourceWorkspaceId, newName),
     sendMessage: (workspaceId, message, options) =>
       ipcRenderer.invoke(IPC_CHANNELS.WORKSPACE_SEND_MESSAGE, workspaceId, message, options),
     resumeStream: (workspaceId, options) =>