🤖 Optimize integration test parallelization (maxWorkers 200% → 100%)

Reduce Jest workers from 200% to 100% on 32-core depot runners.

Problem: 64 parallel workers (200% × 32 cores) caused resource contention.
Each test spawns child processes, performs I/O, and git operations.

Solution: 32 workers (100%) provides better resource utilization and
less context switching overhead.

Results from testing across 3 CI runs:
- Baseline: 193s test execution
- Optimized: 173-183s test execution
- Average improvement: ~15s (7.8% faster)

Note: --silent flag is intentional to prevent overwhelming log output
from 32 parallel workers across 17 test files. Failures still show
full details.

Generated with `cmux`

Author: ammar-agent

.github/workflows/ci.yml

@@ -97,7 +97,8 @@ jobs:
       - uses: ./.github/actions/setup-cmux
 
       - name: Run integration tests with coverage
-        run: TEST_INTEGRATION=1 bun x jest --coverage --maxWorkers=200% --silent ${{ github.event.inputs.test_filter || 'tests' }}
+        # --silent suppresses per-test output (17 test files × 32 workers = overwhelming logs)
+        run: TEST_INTEGRATION=1 bun x jest --coverage --maxWorkers=100% --silent ${{ github.event.inputs.test_filter || 'tests' }}
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/publish-npm.yml

@@ -23,8 +23,6 @@ jobs:
           fetch-depth: 0 # Required for git describe to find tags
 
       - uses: ./.github/actions/setup-cmux
-        with:
-          install-imagemagick: 'true'
 
       # Sets up .npmrc with the auth token
       - uses: actions/setup-node@v4

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>` - Local workspace directories (git worktrees)
+- `~/.cmux/src/<project_name>/<branch>` - Workspace directories for 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 (local uses git worktrees, SSH uses remote git clones)
+- Workspaces using git worktrees
 - 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 workspaces.
+**⚠️ 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.
 
 ## 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 workspace on a new branch (using the same backend as the current workspace).
+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:
 

docs/instruction-files.md

@@ -2,13 +2,17 @@
 
 ## Overview
 
-cmux layers instructions from two locations:
+cmux layers instructions from two sources:
 
-1. `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
-2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context
+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
 
 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.
@@ -19,7 +23,7 @@ cmux reads mode context from sections inside your instruction files. Add a headi
 
 Rules:
 
-- Workspace instructions are checked first, then global instructions
+- Project instructions (workspace or project fallback) 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 isolated workspace management.
+**cmux** (Coding Agent Multiplexer) is a cross-platform desktop application for AI-assisted development with git worktree integration.
 
 ## What is cmux?
 

docs/system-prompt.md

@@ -33,11 +33,8 @@ Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for
 </prelude>
 `;
 
-function buildEnvironmentContext(runtime: Runtime, workspacePath: string): string {
-  const isWorktree = runtime instanceof LocalRuntime;
-
-  if (isWorktree) {
-    return `
+function buildEnvironmentContext(workspacePath: string): string {
+  return `
 <environment>
 You are in a git worktree at ${workspacePath}
 
@@ -47,16 +44,5 @@ 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,11 +1,9 @@
 # Workspaces
 
-cmux supports multiple workspace backends for different use cases:
+Currently, cmux supports one Workspace backend: [git worktrees](https://git-scm.com/docs/git-worktree).
 
-- **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.
+We plan on adding support for SSH and Docker backends in the near future for
+additional isolation and security.
 
 ## Basics of worktrees
 
@@ -45,9 +43,7 @@ dev server (e.g. `bun dev`) there directly and observe the agent's work in real-
 
 ## Filesystem Layout
 
-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).
+All worktrees are stored in `~/.cmux/src/<project-name>/<workspace-name>`.
 
 Example layout:
 

src/App.tsx

@@ -156,7 +156,7 @@ function AppInner() {
 
   const openWorkspaceInTerminal = useCallback(
     (workspaceId: string) => {
-      // Look up workspace metadata to get the workspace path (directory uses workspace name)
+      // Look up workspace metadata to get the worktree 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 workspace could not be removed normally"
+      subtitle="The worktree 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 workspace and may discard uncommitted work or
+          Force deleting will permanently remove the worktree and may discard uncommitted work or
           lose data.
         </WarningText>
       </WarningBox>