🤖 feat: add Local/Worktree runtime distinction (#824)

## Summary

Adds explicit runtime type distinction between Local (project-directory)
and Worktree (isolated git worktrees):

- **Local runtime**: Uses project directory directly, no isolation.
Creation is a no-op (just "use this directory"), delete is a no-op
(won't delete user's project). Good for existing repos where user wants
to work in-place.

- **Worktree runtime**: Creates isolated git worktrees under
`~/.mux/src/<project>/<branch>`. Existing behavior, now made explicit.

- **SSH runtime**: Unchanged, remote execution.

## Changes

- `RuntimeMode` now includes `"local" | "worktree" | "ssh"`
- Extracted `LocalBaseRuntime` for shared exec/file operations between
Local and Worktree
- `LocalRuntime` uses project path directly (no-op create/delete)
- `WorktreeRuntime` manages git worktrees (renamed from old
LocalRuntime)
- UI shows Local/Worktree/SSH options in creation controls
- Updated VS Code extension to handle all runtime types with appropriate
icons
- Runtime badges: SSH (server icon), Worktree (git branch icon), Local
(no badge)

## Backward Compatibility

- `type: "local"` with `srcBaseDir` = legacy worktree config (still
works)
- `type: "local"` without `srcBaseDir` = new project-dir runtime  
- `type: "worktree"` = explicit worktree (new workspaces)

Users can upgrade/downgrade without breaking existing workspaces.

_Generated with `mux`_

---------

Co-authored-by: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>

Author: ammar-agent

README.md

@@ -33,9 +33,10 @@ Here are some specific use cases we enable:
 
 ## Features
 
-- **Isolated workspaces** with central view on git divergence
-  - **Local**: git worktrees on your local machine ([docs](https://cmux.io/local.html))
-  - **SSH**: regular git clones on a remote server ([docs](https://cmux.io/ssh.html))
+- **Isolated workspaces** with central view on git divergence ([docs](https://cmux.io/runtime.html))
+  - **[Local](https://cmux.io/runtime/local.html)**: run directly in your project directory
+  - **[Worktree](https://cmux.io/runtime/worktree.html)**: git worktrees on your local machine
+  - **[SSH](https://cmux.io/runtime/ssh.html)**: remote execution on a server over SSH
 - **Multi-model** (`sonnet-4-*`, `grok-*`, `gpt-5-*`, `opus-4-*`)
   - Ollama supported for local LLMs ([docs](https://cmux.io/models.html#ollama-local))
   - OpenRouter supported for long-tail of LLMs ([docs](https://cmux.io/models.html#openrouter-cloud))

docs/SUMMARY.md

@@ -9,8 +9,10 @@
 # Features
 
 - [Workspaces](./workspaces.md)
-  - [Local](./local.md)
-  - [SSH](./ssh.md)
+  - [Runtimes](./runtime.md)
+    - [Local](./runtime/local.md)
+    - [Worktree](./runtime/worktree.md)
+    - [SSH](./runtime/ssh.md)
   - [Forking](./fork.md)
   - [Init Hooks](./init-hooks.md)
 - [VS Code Extension](./vscode-extension.md)

docs/runtime.md

@@ -0,0 +1,23 @@
+# Runtimes
+
+Runtimes determine where and how mux executes agent workspaces.
+
+| Runtime                               | Isolation                                  | Best For                                 |
+| ------------------------------------- | ------------------------------------------ | ---------------------------------------- |
+| **[Local](./runtime/local.md)**       | All workspaces share the project directory | Quick edits to your working copy         |
+| **[Worktree](./runtime/worktree.md)** | Each workspace gets its own directory      | Running multiple agents in parallel      |
+| **[SSH](./runtime/ssh.md)**           | Remote execution over SSH                  | Security, performance, heavy parallelism |
+
+## Choosing a Runtime
+
+When creating a workspace, select the runtime from the dropdown in the workspace creation UI.
+
+## Init Hooks
+
+[Init hooks](./init-hooks.md) can detect the runtime type via the `MUX_RUNTIME` environment variable:
+
+- `local` — Local runtime
+- `worktree` — Worktree runtime
+- `ssh` — SSH runtime
+
+This lets your init hook adapt behavior, e.g., skip worktree-specific setup when running in local mode.

docs/runtime/local.md

@@ -0,0 +1,19 @@
+# Local Runtime
+
+Local runtime runs the agent directly in your project directory—the same directory you use for development. There's no worktree isolation; the agent works in your actual working copy.
+
+## When to Use
+
+- Quick one-off tasks in your current working copy
+- Reviewing agent work alongside your own uncommitted changes
+- Projects where worktrees don't work well (e.g., some monorepos)
+
+## Caveats
+
+⚠️ **No isolation**: Multiple local workspaces for the same project see and modify the same files. Running them simultaneously can cause conflicts. mux shows a warning when another local workspace is actively streaming.
+
+⚠️ **Affects your working copy**: Agent changes happen in your actual project directory.
+
+## Filesystem
+
+The workspace path is your project directory itself. No additional directories are created.

docs/ssh.md docs/runtime/ssh.mddocs/ssh.md renamed to docs/runtime/ssh.md

@@ -1,17 +1,17 @@
-# SSH Workspaces
+# SSH Runtime
 
 mux supports using remote hosts over SSH for workspaces. When configured, all tool operations will
 execute over SSH and the agent is securely isolated from your local machine.
 
-Our security architecture considers the remote machine potentially hostile. No keys or credentials are implicitly transferred there—just the git archive and [Project Secrets](./project-secrets.md).
+Our security architecture considers the remote machine potentially hostile. No keys or credentials are implicitly transferred there—just the git archive and [Project Secrets](../project-secrets.md).
 
 We highly recommend using SSH workspaces for an optimal experience:
 
 - **Security**: Prompt injection risk is contained to the credentials / files on the remote machine.
-  - SSH remotes pair nicely with [agentic git identities](./agentic-git-identity.md)
+  - SSH remotes pair nicely with [agentic git identities](../agentic-git-identity.md)
 - **Performance**: Run many, many agents in parallel while maintaining good battery life and UI performance
 
-![ssh workspaces](./img/new-workspace-ssh.webp)
+![ssh workspaces](../img/new-workspace-ssh.webp)
 
 The Host can be:
 

docs/local.md docs/runtime/worktree.mddocs/local.md renamed to docs/runtime/worktree.md

@@ -1,6 +1,6 @@
-# Local Workspaces
+# Worktree Runtime
 
-Local workspaces use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes and checkout state.
+Worktree runtime uses [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes and checkout state.
 
 ## How Worktrees Work
 
@@ -10,7 +10,7 @@ It's important to note that a **worktree is not locked to a branch**. The agent
 
 ## Filesystem Layout
 
-Local workspaces are stored in `~/.mux/src/<project-name>/<workspace-name>`.
+Worktree workspaces are stored in `~/.mux/src/<project-name>/<workspace-name>`.
 
 Example layout:
 

docs/vscode-extension.md

@@ -85,5 +85,5 @@ repository.
 ## Related
 
 - [Workspaces Overview](./workspaces.md)
-- [SSH Workspaces](./ssh.md)
+- [SSH Runtime](./runtime/ssh.md)
 - [VS Code Remote-SSH Documentation](https://code.visualstudio.com/docs/remote/ssh)

docs/workspaces.md

@@ -2,20 +2,23 @@
 
 Workspaces in mux provide isolated development environments for parallel agent work. Each workspace maintains its own Git state, allowing you to explore different approaches, run multiple tasks simultaneously, or test changes without affecting your main repository.
 
-## Workspace Types
+## Runtimes
 
-mux supports two workspace backends:
+mux supports three [runtime types](./runtime.md):
 
-- **[Local Workspaces](./local.md)**: Use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes.
+- **[Local](./runtime/local.md)**: Run directly in your project directory. No isolation—best for quick edits to your working copy.
 
-- **[SSH Workspaces](./ssh.md)**: Regular git clones on a remote server accessed via SSH. These are completely independent repositories stored on the remote machine.
+- **[Worktree](./runtime/worktree.md)**: Isolated directories using [git worktrees](https://git-scm.com/docs/git-worktree). Worktrees share `.git` with your main repository while maintaining independent working changes.
 
-## Choosing a Backend
+- **[SSH](./runtime/ssh.md)**: Remote execution over SSH. Ideal for heavy workloads, security isolation, or leveraging remote infrastructure.
 
-The workspace backend is selected when you create a workspace:
+## Choosing a Runtime
 
-- **Local**: Best for fast iteration, local testing, and when you want to leverage your local machine's resources
-- **SSH**: Ideal for heavy workloads, long-running tasks, or when you need access to remote infrastructure
+The runtime is selected when you create a workspace:
+
+- **Local**: Quick tasks in your current working copy
+- **Worktree**: Best for parallel agent work with isolation
+- **SSH**: Heavy workloads, security, or remote infrastructure
 
 ## Key Concepts
 

src/browser/App.tsx

@@ -559,26 +559,31 @@ function AppInner() {
         <div className="mobile-main-content flex min-w-0 flex-1 flex-col overflow-hidden">
           <div className="mobile-layout flex flex-1 overflow-hidden">
             {selectedWorkspace ? (
-              <ErrorBoundary
-                workspaceInfo={`${selectedWorkspace.projectName}/${selectedWorkspace.namedWorkspacePath?.split("/").pop() ?? selectedWorkspace.workspaceId}`}
-              >
-                <AIView
-                  key={selectedWorkspace.workspaceId}
-                  workspaceId={selectedWorkspace.workspaceId}
-                  projectName={selectedWorkspace.projectName}
-                  branch={
-                    selectedWorkspace.namedWorkspacePath?.split("/").pop() ??
-                    selectedWorkspace.workspaceId
-                  }
-                  namedWorkspacePath={selectedWorkspace.namedWorkspacePath ?? ""}
-                  runtimeConfig={
-                    workspaceMetadata.get(selectedWorkspace.workspaceId)?.runtimeConfig
-                  }
-                  incompatibleRuntime={
-                    workspaceMetadata.get(selectedWorkspace.workspaceId)?.incompatibleRuntime
-                  }
-                />
-              </ErrorBoundary>
+              (() => {
+                const currentMetadata = workspaceMetadata.get(selectedWorkspace.workspaceId);
+                // Use metadata.name for workspace name (works for both worktree and local runtimes)
+                // Fallback to path-based derivation for legacy compatibility
+                const workspaceName =
+                  currentMetadata?.name ??
+                  selectedWorkspace.namedWorkspacePath?.split("/").pop() ??
+                  selectedWorkspace.workspaceId;
+                return (
+                  <ErrorBoundary
+                    workspaceInfo={`${selectedWorkspace.projectName}/${workspaceName}`}
+                  >
+                    <AIView
+                      key={selectedWorkspace.workspaceId}
+                      workspaceId={selectedWorkspace.workspaceId}
+                      projectPath={selectedWorkspace.projectPath}
+                      projectName={selectedWorkspace.projectName}
+                      branch={workspaceName}
+                      namedWorkspacePath={selectedWorkspace.namedWorkspacePath ?? ""}
+                      runtimeConfig={currentMetadata?.runtimeConfig}
+                      incompatibleRuntime={currentMetadata?.incompatibleRuntime}
+                    />
+                  </ErrorBoundary>
+                );
+              })()
             ) : creationProjectPath ? (
               (() => {
                 const projectPath = creationProjectPath;

src/browser/components/AIView.tsx

@@ -36,6 +36,7 @@ import { useAIViewKeybinds } from "@/browser/hooks/useAIViewKeybinds";
 import { evictModelFromLRU } from "@/browser/hooks/useModelLRU";
 import { QueuedMessage } from "./Messages/QueuedMessage";
 import { CompactionWarning } from "./CompactionWarning";
+import { ConcurrentLocalWarning } from "./ConcurrentLocalWarning";
 import { checkAutoCompaction } from "@/browser/utils/compaction/autoCompactionCheck";
 import { executeCompaction } from "@/browser/utils/chatCommands";
 import { useProviderOptions } from "@/browser/hooks/useProviderOptions";
@@ -44,6 +45,7 @@ import { useSendMessageOptions } from "@/browser/hooks/useSendMessageOptions";
 
 interface AIViewProps {
   workspaceId: string;
+  projectPath: string;
   projectName: string;
   branch: string;
   namedWorkspacePath: string; // User-friendly path for display and terminal
@@ -55,6 +57,7 @@ interface AIViewProps {
 
 const AIViewInner: React.FC<AIViewProps> = ({
   workspaceId,
+  projectPath,
   projectName,
   branch,
   namedWorkspacePath,
@@ -561,6 +564,11 @@ const AIViewInner: React.FC<AIViewProps> = ({
                   onEdit={() => void handleEditQueuedMessage()}
                 />
               )}
+              <ConcurrentLocalWarning
+                workspaceId={workspaceId}
+                projectPath={projectPath}
+                runtimeConfig={runtimeConfig}
+              />
             </div>
           </div>
           {!autoScroll && (