Fix system message to conditionally describe workspace type

ammar-agent · ammar-agent · commit 42d93f069476 · 2025-10-26T20:28:05.000Z
System message incorrectly stated all workspaces are git worktrees.
With SSHRuntime, workspaces can be either worktrees (LocalRuntime) or
regular git clones (SSHRuntime).

Changes:
- buildEnvironmentContext() now uses runtime type to determine message
  - LocalRuntime: 'git worktree' with worktree-specific warnings
  - SSHRuntime: 'git repository' without worktree warnings
- Updated buildSystemMessage() to accept Runtime parameter
- Added test to verify different messages for different runtimes
- Removed unused isGitWorktree() function (cleaner than git detection)

Worktree Reference Audit:
- Updated 30+ user-facing references from 'worktree' to 'workspace'
- Fixed documentation (workspaces.md, intro.md, fork.md, etc.)
- Updated UI components (NewWorkspaceModal, ForceDeleteModal)
- Fixed comments in types, config, and service files
- Kept 170+ accurate references (git commands, LocalRuntime specifics)

The codebase now correctly distinguishes:
- 'Workspace' (generic isolated environment)
- 'Git worktree' (LocalRuntime-specific implementation)
- 'Git clone' (SSHRuntime-specific implementation)
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -105,7 +105,7 @@ Verify with React DevTools Profiler - MarkdownCore should only re-render when co
 - `src/App.tsx` - Main React component
 - `src/config.ts` - Configuration management
 - `~/.cmux/config.json` - User configuration file
-- `~/.cmux/src/<project_name>/<branch>` - Workspace directories for git worktrees
+- `~/.cmux/src/<project_name>/<branch>` - Local workspace directories (git worktrees)
 - `~/.cmux/sessions/<workspace_id>/chat.jsonl` - Session chat histories
 
 ## Documentation Guidelines
@@ -137,7 +137,7 @@ in `/tmp/ai-sdk-docs/**.mdx`.
 ## Key Features
 
 - Projects sidebar (left panel)
-- Workspaces using git worktrees
+- Workspaces (local uses git worktrees, SSH uses remote git clones)
 - Configuration persisted to `~/.cmux/config.json`
 
 ## Performance Patterns
@@ -179,7 +179,7 @@ This project uses **Make** as the primary build orchestrator. See `Makefile` for
 
 - When refactoring, use `git mv` to preserve file history instead of rewriting files from scratch
 
-**⚠️ NEVER kill the running cmux process** - The main cmux instance is used for active development. Use `make test` or `make typecheck` to verify changes instead of starting the app in test worktrees.
+**⚠️ NEVER kill the running cmux process** - The main cmux instance is used for active development. Use `make test` or `make typecheck` to verify changes instead of starting the app in test workspaces.
 
 ## Testing
 
diff --git a/docs/fork.md b/docs/fork.md
@@ -1,6 +1,6 @@
 # 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.
+Use `/fork` to clone a workspace with its full conversation history and UI state. The forked workspace gets a new workspace on a new branch (using the same backend as the current workspace).
 
 Usage:
 
diff --git a/docs/intro.md b/docs/intro.md
@@ -2,7 +2,7 @@
 
 ![cmux product screenshot](img/product-hero.webp)
 
-**cmux** (Coding Agent Multiplexer) is a cross-platform desktop application for AI-assisted development with git worktree integration.
+**cmux** (Coding Agent Multiplexer) is a cross-platform desktop application for AI-assisted development with isolated workspace management.
 
 ## What is cmux?
 
diff --git a/docs/system-prompt.md b/docs/system-prompt.md
@@ -33,8 +33,11 @@ Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for
 </prelude>
 `;
 
-function buildEnvironmentContext(workspacePath: string): string {
-  return `
+function buildEnvironmentContext(runtime: Runtime, workspacePath: string): string {
+  const isWorktree = runtime instanceof LocalRuntime;
+  
+  if (isWorktree) {
+    return `
 <environment>
 You are in a git worktree at ${workspacePath}
 
@@ -44,5 +47,16 @@ You are in a git worktree at ${workspacePath}
 - You are meant to do your work isolated from the user and other agents
 </environment>
 `;
+  } else {
+    return `
+<environment>
+You are in 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>
+`;
+  }
 }
 ```
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -1,9 +1,11 @@
 # Workspaces
 
-Currently, cmux supports one Workspace backend: [git worktrees](https://git-scm.com/docs/git-worktree).
+cmux supports multiple workspace backends for different use cases:
 
-We plan on adding support for SSH and Docker backends in the near future for
-additional isolation and security.
+- **Local workspaces**: [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine
+- **SSH workspaces**: Regular git clones on a remote server accessed via SSH
+
+The backend is selected based on your runtime configuration. Local workspaces use git worktrees which share the `.git` directory with your main repository, while SSH workspaces are independent git clones on the remote machine.
 
 ## Basics of worktrees
 
@@ -43,7 +45,9 @@ dev server (e.g. `bun dev`) there directly and observe the agent's work in real-
 
 ## Filesystem Layout
 
-All worktrees are stored in `~/.cmux/src/<project-name>/<workspace-name>`.
+Local workspaces are stored in `~/.cmux/src/<project-name>/<workspace-name>`.
+
+SSH workspaces are stored on the remote machine at `~/workspace/<project-name>/<workspace-name>` (or your configured remote path).
 
 Example layout:
 
diff --git a/src/App.tsx b/src/App.tsx
@@ -156,7 +156,7 @@ function AppInner() {
 
   const openWorkspaceInTerminal = useCallback(
     (workspaceId: string) => {
-      // Look up workspace metadata to get the worktree path (directory uses workspace name)
+      // Look up workspace metadata to get the workspace path (directory uses workspace name)
       const metadata = workspaceMetadata.get(workspaceId);
       if (metadata) {
         void window.api.workspace.openTerminal(metadata.namedWorkspacePath);
diff --git a/src/components/ForceDeleteModal.tsx b/src/components/ForceDeleteModal.tsx
@@ -47,7 +47,7 @@ export const ForceDeleteModal: React.FC<ForceDeleteModalProps> = ({
     <Modal
       isOpen={isOpen}
       title="Force Delete Workspace?"
-      subtitle="The worktree could not be removed normally"
+      subtitle="The workspace could not be removed normally"
       onClose={onClose}
       maxWidth="600px"
       isLoading={isDeleting}
@@ -60,7 +60,7 @@ export const ForceDeleteModal: React.FC<ForceDeleteModalProps> = ({
       <WarningBox>
         <WarningTitle>This action cannot be undone</WarningTitle>
         <WarningText>
-          Force deleting will permanently remove the worktree and may discard uncommitted work or
+          Force deleting will permanently remove the workspace and may discard uncommitted work or
           lose data.
         </WarningText>
       </WarningBox>
diff --git a/src/components/Modal.stories.tsx b/src/components/Modal.stories.tsx
@@ -106,7 +106,7 @@ export const WithInfoBox: Story = {
       <>
         <ModalInfo>
           <p>
-            This operation will create a new git worktree at <code>~/cmux/project/branch</code>
+            This operation will create a new workspace at <code>~/cmux/project/branch</code>
           </p>
           <p>Existing files will not be affected.</p>
         </ModalInfo>
diff --git a/src/components/NewWorkspaceModal.tsx b/src/components/NewWorkspaceModal.tsx
@@ -137,8 +137,9 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
               <Tooltip width="wide" position="bottom" interactive>
                 <strong>About Workspaces:</strong>
                 <ul className="my-1 pl-4">
-                  <li>Uses git worktrees (separate directories sharing .git)</li>
-                  <li>All committed changes visible across all worktrees</li>
+                  <li>Isolated directories for parallel development</li>
+                  <li>Local: git worktrees sharing .git (fast, efficient)</li>
+                  <li>SSH: independent git clones on remote server</li>
                   <li>Agent can switch branches freely during session</li>
                   <li>Define branching strategy in AGENTS.md</li>
                 </ul>
@@ -243,7 +244,7 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
         )}
 
         <ModalInfo id={infoId}>
-          <p>This will create a git worktree at:</p>
+          <p>This will create a workspace at:</p>
           <code className="block break-all">
             {runtimeMode === RUNTIME_MODE.SSH
               ? `${sshHost || "<host>"}:~/cmux/${branchName || "<branch-name>"}`
diff --git a/src/config.ts b/src/config.ts
@@ -126,7 +126,7 @@ export class Config {
   }
 
   /**
-   * Get the workspace worktree path for a given directory name.
+   * Get the workspace directory path for a given directory name.
    * The directory name is the workspace name (branch name).
    */
 
@@ -200,7 +200,7 @@ export class Config {
    * - Worktree directory name: uses workspace.name (the branch name)
    * - Workspace ID: stable random identifier for identity and sessions (not used for directories)
    *
-   * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for worktree directory paths
+   * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for workspace directory paths
    * Frontend: Gets enriched metadata with paths via IPC (FrontendWorkspaceMetadata)
    *
    * WorkspaceMetadata.workspacePath is deprecated and will be removed. Use computed
diff --git a/src/services/aiService.ts b/src/services/aiService.ts
@@ -508,6 +508,7 @@ export class AIService extends EventEmitter {
       // Build system message from workspace metadata
       const systemMessage = await buildSystemMessage(
         metadata,
+        runtime,
         workspacePath,
         mode,
         additionalSystemInstructions
diff --git a/src/services/ipcMain.ts b/src/services/ipcMain.ts
@@ -553,7 +553,7 @@ export class IpcMain {
           // Generate stable workspace ID for the new workspace
           const newWorkspaceId = this.config.generateStableId();
 
-          // Create new git worktree branching from source workspace's branch
+          // Create new workspace branching from source workspace's branch
           const result = await createWorktree(this.config, foundProjectPath, newName, {
             trunkBranch: sourceBranch,
             directoryName: newName,
@@ -603,7 +603,7 @@ export class IpcMain {
             }
           } catch (copyError) {
             // If copy fails, clean up everything we created
-            // 1. Remove the git worktree
+            // 1. Remove the workspace
             await removeWorktree(foundProjectPath, newWorkspacePath);
             // 2. Remove the session directory (may contain partial copies)
             try {
diff --git a/src/services/systemMessage.test.ts b/src/services/systemMessage.test.ts
@@ -5,6 +5,8 @@ import { buildSystemMessage } from "./systemMessage";
 import type { WorkspaceMetadata } from "@/types/workspace";
 import { spyOn, describe, test, expect, beforeEach, afterEach } from "bun:test";
 import type { Mock } from "bun:test";
+import { LocalRuntime } from "@/runtime/LocalRuntime";
+import { SSHRuntime } from "@/runtime/SSHRuntime";
 
 describe("buildSystemMessage", () => {
   let tempDir: string;
@@ -52,7 +54,8 @@ Use diagrams where appropriate.
       projectPath: tempDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const runtime = new LocalRuntime(tempDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include the mode-specific content
     expect(systemMessage).toContain("<plan>");
@@ -83,7 +86,8 @@ Focus on planning and design.
       projectPath: tempDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir);
+    const runtime = new LocalRuntime(tempDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir);
 
     // Should NOT include the <plan> mode-specific tag
     expect(systemMessage).not.toContain("<plan>");
@@ -122,7 +126,8 @@ Workspace plan instructions (should win).
       projectPath: tempDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const runtime = new LocalRuntime(tempDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include workspace mode section in the <plan> tag (workspace wins)
     expect(systemMessage).toMatch(/<plan>\s*Workspace plan instructions \(should win\)\./s);
@@ -157,7 +162,8 @@ Just general workspace stuff.
       projectPath: tempDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
+    const runtime = new LocalRuntime(tempDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "plan");
 
     // Should include global mode section as fallback
     expect(systemMessage).toContain("Global plan instructions");
@@ -178,11 +184,38 @@ Special mode instructions.
       projectPath: tempDir,
     };
 
-    const systemMessage = await buildSystemMessage(metadata, workspaceDir, "My-Special_Mode!");
+    const runtime = new LocalRuntime(tempDir);
+    const systemMessage = await buildSystemMessage(metadata, runtime, workspaceDir, "My-Special_Mode!");
 
     // Tag should be sanitized to only contain valid characters
     expect(systemMessage).toContain("<my-special_mode->");
     expect(systemMessage).toContain("Special mode instructions");
     expect(systemMessage).toContain("</my-special_mode->");
   });
+
+  test("environment context differs between LocalRuntime and SSHRuntime", async () => {
+    const metadata: WorkspaceMetadata = {
+      id: "test-workspace",
+      name: "test-workspace",
+      projectName: "test-project",
+      projectPath: tempDir,
+    };
+
+    // Test with LocalRuntime
+    const localRuntime = new LocalRuntime(tempDir);
+    const localMessage = await buildSystemMessage(metadata, localRuntime, workspaceDir);
+    
+    // Should mention "git worktree" and include worktree-specific warnings
+    expect(localMessage).toContain("git worktree");
+    expect(localMessage).toContain("Do not modify or visit other worktrees");
+
+    // Test with SSHRuntime
+    const sshRuntime = new SSHRuntime({ host: "test-host", srcBaseDir: "/remote/path" });
+    const sshMessage = await buildSystemMessage(metadata, sshRuntime, workspaceDir);
+    
+    // Should mention "git repository" but not "worktree"
+    expect(sshMessage).toContain("git repository");
+    expect(sshMessage).not.toContain("git worktree");
+    expect(sshMessage).not.toContain("Do not modify or visit other worktrees");
+  });
 });
diff --git a/src/services/systemMessage.ts b/src/services/systemMessage.ts
@@ -3,6 +3,8 @@ import * as path from "path";
 import type { WorkspaceMetadata } from "@/types/workspace";
 import { gatherInstructionSets, readInstructionSet } from "@/utils/main/instructionFiles";
 import { extractModeSection } from "@/utils/main/markdown";
+import type { Runtime } from "@/runtime/Runtime";
+import { LocalRuntime } from "@/runtime/LocalRuntime";
 
 // NOTE: keep this in sync with the docs/models.md file
 
@@ -28,8 +30,11 @@ Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for
 </prelude>
 `;
 
-function buildEnvironmentContext(workspacePath: string): string {
-  return `
+function buildEnvironmentContext(runtime: Runtime, workspacePath: string): string {
+  const isWorktree = runtime instanceof LocalRuntime;
+  
+  if (isWorktree) {
+    return `
 <environment>
 You are in a git worktree at ${workspacePath}
 
@@ -39,6 +44,17 @@ You are in a git worktree at ${workspacePath}
 - You are meant to do your work isolated from the user and other agents
 </environment>
 `;
+  } else {
+    return `
+<environment>
+You are in 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>
+`;
+  }
 }
 
 /**
@@ -69,14 +85,16 @@ function getSystemDirectory(): string {
  * checked and appended when building the instruction set (useful for personal preferences not committed to git).
  *
  * @param metadata - Workspace metadata
- * @param workspacePath - Absolute path to the workspace worktree directory
+ * @param runtime - Runtime instance (used to determine workspace type)
+ * @param workspacePath - Absolute path to the workspace directory
  * @param mode - Optional mode name (e.g., "plan", "exec") - looks for {MODE}.md files if provided
  * @param additionalSystemInstructions - Optional additional system instructions to append at the end
  * @returns System message string with all instruction sources combined
  * @throws Error if metadata is invalid
  */
 export async function buildSystemMessage(
   metadata: WorkspaceMetadata,
+  runtime: Runtime,
   workspacePath: string,
   mode?: string,
   additionalSystemInstructions?: string
@@ -115,7 +133,7 @@ export async function buildSystemMessage(
   }
 
   // Build the final system message
-  const environmentContext = buildEnvironmentContext(workspaceDir);
+  const environmentContext = buildEnvironmentContext(runtime, workspaceDir);
   const trimmedPrelude = PRELUDE.trim();
   let systemMessage = `${trimmedPrelude}\n\n${environmentContext}`;
 
diff --git a/src/stores/WorkspaceStore.test.ts b/src/stores/WorkspaceStore.test.ts
@@ -52,7 +52,7 @@ function createAndAddWorkspace(
     name: options.name ?? `test-branch-${workspaceId}`,
     projectName: options.projectName ?? "test-project",
     projectPath: options.projectPath ?? "/path/to/project",
-    namedWorkspacePath: options.namedWorkspacePath ?? "/path/to/worktree",
+    namedWorkspacePath: options.namedWorkspacePath ?? "/path/to/workspace",
     createdAt: options.createdAt ?? new Date().toISOString(),
   };
   store.addWorkspace(metadata);
@@ -83,7 +83,7 @@ describe("WorkspaceStore", () => {
         name: "test-branch",
         projectName: "test-project",
         projectPath: "/path/to/project",
-        namedWorkspacePath: "/path/to/worktree",
+        namedWorkspacePath: "/path/to/workspace",
         createdAt,
       };
 
@@ -110,7 +110,7 @@ describe("WorkspaceStore", () => {
         name: "test-branch-2",
         projectName: "test-project",
         projectPath: "/path/to/project",
-        namedWorkspacePath: "/path/to/worktree",
+        namedWorkspacePath: "/path/to/workspace",
         createdAt,
       };
 
diff --git a/src/types/project.ts b/src/types/project.ts
@@ -25,7 +25,7 @@ import type { RuntimeConfig } from "./runtime";
  * For legacy entries, metadata is read from ~/.cmux/sessions/{workspaceId}/metadata.json
  */
 export interface Workspace {
-  /** Absolute path to workspace worktree - REQUIRED for backward compatibility */
+  /** Absolute path to workspace directory - REQUIRED for backward compatibility */
   path: string;
 
   /** Stable workspace ID (10 hex chars for new workspaces) - optional for legacy */
diff --git a/src/types/workspace.ts b/src/types/workspace.ts

Original file line number	Diff line number	Diff line change
`@@ -126,7 +126,7 @@ export class Config {`
`126`	`126`	`}`
`127`	`127`
`128`	`128`	`/**`
`129`		`- * Get the workspace worktree path for a given directory name.`
	`129`	`+ * Get the workspace directory path for a given directory name.`
`130`	`130`	`* The directory name is the workspace name (branch name).`
`131`	`131`	`*/`
`132`	`132`
`@@ -200,7 +200,7 @@ export class Config {`
`200`	`200`	`* - Worktree directory name: uses workspace.name (the branch name)`
`201`	`201`	`* - Workspace ID: stable random identifier for identity and sessions (not used for directories)`
`202`	`202`	`*`
`203`		`- * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for worktree directory paths`
	`203`	`+ * Backend: Uses getWorkspacePath(metadata.projectPath, metadata.name) for workspace directory paths`
`204`	`204`	`* Frontend: Gets enriched metadata with paths via IPC (FrontendWorkspaceMetadata)`
`205`	`205`	`*`
`206`	`206`	`* WorkspaceMetadata.workspacePath is deprecated and will be removed. Use computed`