🤖 feat: add in-place local runtime mode

Author: kylecarbs

docs/SUMMARY.md

@@ -9,7 +9,8 @@
 # Features
 
 - [Workspaces](./workspaces.md)
-  - [Local](./local.md)
+  - [Worktree](./worktree.md)
+  - [Local (In-Place)](./local-in-place.md)
   - [SSH](./ssh.md)
   - [Forking](./fork.md)
   - [Init Hooks](./init-hooks.md)

docs/init-hooks.md

@@ -34,8 +34,8 @@ Init hooks receive the following environment variables:
 - `MUX_PROJECT_PATH` - Absolute path to the project root on the **local machine**
   - Always refers to your local project path, even on SSH workspaces
   - Useful for logging, debugging, or runtime-specific logic
-- `MUX_RUNTIME` - Runtime type: `"local"` or `"ssh"`
-  - Use this to detect whether the hook is running locally or remotely
+- `MUX_RUNTIME` - Runtime type: `"worktree"`, `"local"`, or `"ssh"`
+  - Use this to detect whether the hook is running in a worktree, directly in your project directory, or on a remote machine
 
 **Note for SSH workspaces:** Since the project is synced to the remote machine, files exist in both locations. The init hook runs in the workspace directory (`$PWD`), so use relative paths to reference project files:
 
@@ -54,11 +54,17 @@ if [ -f "../.env" ]; then
 fi
 
 # Runtime-specific behavior
-if [ "$MUX_RUNTIME" = "local" ]; then
-  echo "Running on local machine"
-else
-  echo "Running on SSH remote"
-fi
+case "$MUX_RUNTIME" in
+  worktree)
+    echo "Running in local worktree"
+    ;;
+  local)
+    echo "Running directly in project directory"
+    ;;
+  ssh)
+    echo "Running on SSH remote"
+    ;;
+esac
 
 bun install
 ```

docs/local-in-place.md

@@ -0,0 +1,28 @@
+# Local (In-Place) Workspaces
+
+Local (in-place) workspaces operate directly inside your project directory. Unlike [worktree workspaces](./worktree.md), they do **not** create a separate checkout. The agent works with the branch, index, and working tree that you already have checked out.
+
+## When to Use
+
+- You want zero-copy workflows (benchmarks, quick experiments, or short-lived agents)
+- You need the agent to see files that are too large to duplicate efficiently
+- You plan to drive the session from another terminal that is already inside the project directory
+
+## Key Behavior
+
+- **Single workspace per project**: mux enforces one in-place workspace per project to avoid conflicting agent sessions.
+- **Current branch only**: the agent starts on whatever branch is currently checked out in your repository. Branch switches affect your main working tree immediately.
+- **Shared Git state**: any uncommitted changes are visible to both you and the agent. The agent can stage, commit, and push directly from your checkout.
+- **No automatic cleanup**: deleting the workspace inside mux only removes it from the workspace list—your project directory remains untouched.
+- **Init hooks**: `.mux/init` still runs in the project directory. Use `MUX_RUNTIME=local` to special-case logic if needed.
+
+## Recommended Safeguards
+
+- Commit or stash important work before starting an in-place session.
+- Consider creating a temporary branch manually before opening the workspace if you want to isolate commits.
+- Use descriptive workspace names so it is clear what the agent is attempting.
+- Review the agent's Git operations carefully—there is no isolation layer to fall back on.
+
+## Switching Between Modes
+
+You can select **Local (in-place)** from the workspace creation dialog or via the `/new` command (`/new -r local`). Switch back to **Worktree** or **SSH** at any time for isolated workspaces.

docs/workspaces.md

@@ -4,25 +4,26 @@ Workspaces in mux provide isolated development environments for parallel agent w
 
 ## Workspace Types
 
-mux supports two workspace backends:
-
-- **[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.
+mux supports three workspace backends:
 
+- **[Worktree Workspaces](./worktree.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 (In-Place) Workspaces](./local-in-place.md)**: Reuse your existing project directory with no additional checkout. The agent operates on the branch and working tree you already have checked out.
 - **[SSH Workspaces](./ssh.md)**: Regular git clones on a remote server accessed via SSH. These are completely independent repositories stored on the remote machine.
 
 ## Choosing a Backend
 
 The workspace backend is selected when you create a workspace:
 
-- **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
+- **Worktree**: Best for fast iteration, local testing, and when you want an isolated checkout that still lives on your machine.
+- **Local (in-place)**: Ideal for zero-copy workflows or when you need the agent to operate on your existing working tree without creating a new worktree.
+- **SSH**: Ideal for heavy workloads, long-running tasks, or when you need access to remote infrastructure.
 
 ## Key Concepts
 
 - **Isolation**: Each workspace has independent working changes and Git state
 - **Branch flexibility**: Workspaces can switch branches, enter detached HEAD state, or create new branches as needed
 - **Parallel execution**: Run multiple workspaces simultaneously on different tasks
-- **Shared commits**: Local workspaces (using worktrees) share commits with the main repository immediately
+- **Shared commits**: Worktree and local (in-place) workspaces share commits with the main repository immediately; SSH workspaces require pushing to sync
 
 ## Reviewing Code
 
@@ -39,9 +40,9 @@ Here are a few practical approaches to reviewing changes from workspaces, depend
 Some changes (especially UI ones) require the Human to determine acceptability. An effective approach for this is:
 
 1. Ask agent to commit WIP when it's ready for Human review
-2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach <workspace-branch>` (for local workspaces)
+2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach <workspace-branch>` (for worktree workspaces)
 
-**Note**: For local workspaces, this workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees.
+**Note**: For worktree workspaces, this workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees. For local (in-place) workspaces, the agent and human are literally sharing the same checkout—coordinate commits carefully.
 
 If you want faster iteration in between commits, you can hop into the workspace directory and run a dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time.
 

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

@@ -1,6 +1,6 @@
-# Local Workspaces
+# Worktree Workspaces
 
-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 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.
 
 ## 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:
 

src/browser/components/ChatInput/CreationControls.tsx

@@ -22,7 +22,7 @@ export function CreationControls(props: CreationControlsProps) {
   return (
     <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
       {/* Trunk Branch Selector */}
-      {props.branches.length > 0 && (
+      {props.branches.length > 0 && props.runtimeMode !== RUNTIME_MODE.LOCAL && (
         <div className="flex items-center gap-1" data-component="TrunkBranchGroup">
           <label htmlFor="trunk-branch" className="text-muted text-xs">
             From:
@@ -44,12 +44,14 @@ export function CreationControls(props: CreationControlsProps) {
         <Select
           value={props.runtimeMode}
           options={[
-            { value: RUNTIME_MODE.LOCAL, label: "Local" },
+            { value: RUNTIME_MODE.WORKTREE, label: "Worktree" },
+            { value: RUNTIME_MODE.LOCAL, label: "Local (in-place)" },
             { value: RUNTIME_MODE.SSH, label: "SSH" },
           ]}
           onChange={(newMode) => {
             const mode = newMode as RuntimeMode;
-            props.onRuntimeChange(mode, mode === RUNTIME_MODE.LOCAL ? "" : props.sshHost);
+            const nextHost = mode === RUNTIME_MODE.SSH ? props.sshHost : "";
+            props.onRuntimeChange(mode, nextHost);
           }}
           disabled={props.disabled}
           aria-label="Runtime mode"
@@ -69,7 +71,8 @@ export function CreationControls(props: CreationControlsProps) {
           <Tooltip className="tooltip" align="center" width="wide">
             <strong>Runtime:</strong>
             <br />
-            • Local: git worktree in ~/.mux/src
+            • Worktree: git worktree in ~/.mux/src
+            <br />• Local (in-place): work directly in the project directory
             <br />• SSH: remote clone in ~/mux on SSH host
           </Tooltip>
         </TooltipWrapper>

src/browser/contexts/WorkspaceContext.test.tsx

@@ -18,7 +18,7 @@ const createWorkspaceMetadata = (
   name: "main",
   namedWorkspacePath: "/test-main",
   createdAt: "2025-01-01T00:00:00.000Z",
-  runtimeConfig: { type: "local", srcBaseDir: "/home/user/.mux/src" },
+  runtimeConfig: { type: "worktree", srcBaseDir: "/home/user/.mux/src" },
   ...overrides,
 });
 

src/browser/hooks/useStartWorkspaceCreation.test.ts

@@ -21,11 +21,17 @@ type PersistFn = typeof updatePersistedState;
 type PersistCall = [string, unknown, unknown?];
 
 describe("normalizeRuntimePreference", () => {
-  test("returns undefined for local or empty runtime", () => {
+  test("returns undefined for empty or worktree runtime", () => {
     expect(normalizeRuntimePreference(undefined)).toBeUndefined();
     expect(normalizeRuntimePreference(" ")).toBeUndefined();
-    expect(normalizeRuntimePreference("local")).toBeUndefined();
-    expect(normalizeRuntimePreference("LOCAL")).toBeUndefined();
+    expect(normalizeRuntimePreference("worktree")).toBeUndefined();
+    expect(normalizeRuntimePreference("WORKTREE")).toBeUndefined();
+  });
+
+  test("normalizes local runtime tokens", () => {
+    expect(normalizeRuntimePreference("local")).toBe("local");
+    expect(normalizeRuntimePreference("LOCAL")).toBe("local");
+    expect(normalizeRuntimePreference(" local-in-place ")).toBe("local");
   });
 
   test("normalizes ssh runtimes", () => {

src/browser/hooks/useStartWorkspaceCreation.ts

@@ -27,10 +27,15 @@ export function normalizeRuntimePreference(runtime: string | undefined): string
   }
 
   const lower = trimmed.toLowerCase();
-  if (lower === RUNTIME_MODE.LOCAL) {
+  const normalized = lower.replace(/[\s_()-]/g, "");
+  if (normalized === RUNTIME_MODE.WORKTREE) {
     return undefined;
   }
 
+  if (normalized === RUNTIME_MODE.LOCAL || normalized === "localinplace") {
+    return RUNTIME_MODE.LOCAL;
+  }
+
   if (lower === RUNTIME_MODE.SSH) {
     return RUNTIME_MODE.SSH;
   }

src/browser/utils/chatCommands.test.ts

@@ -3,14 +3,19 @@ import { parseRuntimeString } from "./chatCommands";
 describe("parseRuntimeString", () => {
   const workspaceName = "test-workspace";
 
-  test("returns undefined for undefined runtime (default to local)", () => {
+  test("returns undefined for undefined runtime (default to worktree)", () => {
     expect(parseRuntimeString(undefined, workspaceName)).toBeUndefined();
   });
 
-  test("returns undefined for explicit 'local' runtime", () => {
-    expect(parseRuntimeString("local", workspaceName)).toBeUndefined();
-    expect(parseRuntimeString("LOCAL", workspaceName)).toBeUndefined();
-    expect(parseRuntimeString(" local ", workspaceName)).toBeUndefined();
+  test("returns undefined for explicit 'worktree' runtime", () => {
+    expect(parseRuntimeString("worktree", workspaceName)).toBeUndefined();
+    expect(parseRuntimeString(" WORKTREE ", workspaceName)).toBeUndefined();
+  });
+
+  test("parses local runtime token", () => {
+    expect(parseRuntimeString("local", workspaceName)).toEqual({ type: "local" });
+    expect(parseRuntimeString("LOCAL", workspaceName)).toEqual({ type: "local" });
+    expect(parseRuntimeString(" local-in-place ", workspaceName)).toEqual({ type: "local" });
   });
 
   test("parses valid SSH runtime", () => {
@@ -77,10 +82,10 @@ describe("parseRuntimeString", () => {
 
   test("throws error for unknown runtime type", () => {
     expect(() => parseRuntimeString("docker", workspaceName)).toThrow(
-      "Unknown runtime type: 'docker'"
+      "Unknown runtime type: 'docker'. Use 'worktree', 'local', or 'ssh <host>'"
     );
     expect(() => parseRuntimeString("remote", workspaceName)).toThrow(
-      "Unknown runtime type: 'remote'"
+      "Unknown runtime type: 'remote'. Use 'worktree', 'local', or 'ssh <host>'"
     );
   });
 });