Fix system message to conditionally describe workspace type (#436)

System message incorrectly stated all workspaces are git worktrees. With
SSHRuntime, workspaces can be either worktrees (LocalRuntime) or regular
git clones (SSHRuntime).

## Changes

### System Message Fix (based on review feedback)
- `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
- Uses `runtime instanceof LocalRuntime` - cleaner than git detection
- Added test to verify different messages for different runtimes

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

## Testing
- ✅ All tests passing (6/6 in systemMessage.test.ts)
- ✅ New test: verifies LocalRuntime vs SSHRuntime produce different
messages

## Result
The codebase now correctly distinguishes:
- **Workspace** - Generic term for isolated development environments
- **Git worktree** - Specific LocalRuntime implementation
- **Git clone** - Specific SSHRuntime implementation

---

**Files changed**: 17 files, +107 insertions, -36 deletions

Author: ammar-agent

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
 

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:
 

docs/instruction-files.md

@@ -2,17 +2,13 @@
 
 ## Overview
 
-cmux layers instructions from two sources:
+cmux layers instructions from two locations:
 
-1. **Global**: `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — always included
-2. **Project**: Either workspace OR project AGENTS.md (not both):
-   - **Workspace**: `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — if exists
-   - **Project**: `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — fallback if workspace doesn't exist
+1. `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
+2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context
 
 Priority within each location: `AGENTS.md` → `AGENT.md` → `CLAUDE.md` (first match wins). If the base file is found, cmux also appends `AGENTS.local.md` from the same directory when present.
 
-**Fallback behavior**: Workspace instructions **replace** project instructions (not layered). If a workspace doesn't have AGENTS.md, the project root's AGENTS.md is used. This is particularly useful for SSH workspaces where files may not be fully cloned yet.
-
 ## Mode Prompts
 
 > Use mode-specific sections to optimize context and customize the behavior specific modes.
@@ -23,7 +19,7 @@ cmux reads mode context from sections inside your instruction files. Add a headi
 
 Rules:
 
-- Project instructions (workspace or project fallback) are checked first, then global instructions
+- Workspace instructions are checked first, then global instructions
 - The first matching section wins (at most one section is used)
 - The section's content is everything until the next heading of the same or higher level
 - Missing sections are ignored (no error)

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?
 

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>
+`;
+  }
 }
 ```

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:
 

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);

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>

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>

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>"}`