🤖 feat: add VS Code extension for cmux workspace switching

.github/actions/build-vscode-extension/action.yml

@@ -0,0 +1,9 @@
+name: "Build VS Code Extension"
+description: "Build the cmux VS Code extension"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Build VS Code extension
+      shell: bash
+      run: make vscode-ext

.github/workflows/build.yml

@@ -89,3 +89,24 @@ jobs:
           path: release/*.AppImage
           retention-days: 30
           if-no-files-found: error
+
+  build-vscode-extension:
+    name: Build VS Code Extension
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for git describe to find tags
+
+      - uses: ./.github/actions/setup-cmux
+
+      - uses: ./.github/actions/build-vscode-extension
+
+      - name: Upload VS Code extension artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: vscode-extension
+          path: vscode/cmux-*.vsix
+          retention-days: 30
+          if-no-files-found: error

.github/workflows/release.yml

@@ -58,3 +58,24 @@ jobs:
         run: bun x electron-builder --linux --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-vscode-extension:
+    name: Build and Release VS Code Extension
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for git describe to find tags
+
+      - uses: ./.github/actions/setup-cmux
+
+      - uses: ./.github/actions/build-vscode-extension
+
+      - name: Upload VS Code extension to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload ${{ github.event.release.tag_name }} \
+            vscode/cmux-*.vsix \
+            --clobber

Makefile

@@ -37,6 +37,7 @@ include fmt.mk
 .PHONY: lint lint-fix typecheck static-check
 .PHONY: test test-unit test-integration test-watch test-coverage test-e2e
 .PHONY: dist dist-mac dist-win dist-linux
+.PHONY: vscode-ext vscode-ext-install
 .PHONY: docs docs-build docs-watch
 .PHONY: storybook storybook-build test-storybook chromatic
 .PHONY: benchmark-terminal
@@ -83,6 +84,10 @@ node_modules/.installed: package.json bun.lock
 # Legacy target for backwards compatibility
 ensure-deps: node_modules/.installed
 
+
+
+
+
 ## Help
 help: ## Show this help message
 	@echo 'Usage: make [target]'
@@ -267,6 +272,14 @@ dist-win: build ## Build Windows distributable
 dist-linux: build ## Build Linux distributable
 	@bun x electron-builder --linux --publish never
 
+## VS Code Extension (delegates to vscode/Makefile)
+
+vscode-ext: ## Build VS Code extension (.vsix)
+	@$(MAKE) -C vscode build
+
+vscode-ext-install: ## Build and install VS Code extension locally
+	@$(MAKE) -C vscode install
+
 ## Documentation
 docs: ## Serve documentation locally
 	@./scripts/docs.sh

README.md

@@ -36,6 +36,7 @@ Here are some specific use cases we enable:
 - 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))
+- **VS Code Extension**: Jump into cmux workspaces directly from VS Code ([docs](https://cmux.io/vscode-extension.html))
 - Multi-model (`sonnet-4-*`, `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

@@ -13,6 +13,7 @@
   - [SSH](./ssh.md)
   - [Forking](./fork.md)
   - [Init Hooks](./init-hooks.md)
+- [VS Code Extension](./vscode-extension.md)
 - [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.md)
   - [Vim Mode](./vim-mode.md)

docs/vscode-extension.md

@@ -0,0 +1,88 @@
+# VS Code Extension
+
+The cmux VS Code extension allows you to quickly jump into your cmux workspaces directly from Visual Studio Code or Cursor. This enables a more seamless back and forth between a purely agentic workflow and traditional editing. It's
+especially useful for completing the "last mile" of a task or establishing the initial architecture.
+
+## Overview
+
+The extension has a small initial surface area: a command to open a workspace.
+
+![cmux VS Code extension screenshot](./img/vscode-ext.webp)
+
+1. Press `Cmd+Shift+P` (or `Ctrl+Shift+P` on Windows/Linux)
+2. Type "cmux: Open Workspace"
+   - Optional: Set a custom keybinding in the Command Palette settings
+3. Select your workspace
+4. It opens in a new editor window
+
+The extension works seamlessly with both local and SSH workspaces.
+
+## Installation
+
+### Download
+
+Download the latest `.vsix` file from the [GitHub releases page](https://github.com/coder/cmux/releases).
+
+### Install
+
+**Command line:**
+
+```bash
+# For VS Code
+code --install-extension cmux-*.vsix
+
+# For Cursor
+cursor --install-extension cmux-*.vsix
+```
+
+**From editor UI:**
+
+1. Open Command Palette (`Cmd+Shift+P`)
+2. Type "Extensions: Install from VSIX..."
+3. Select the downloaded file
+
+### Workspace Types
+
+The extension displays workspaces differently based on their type:
+
+- **Local**: `📁 [project-name] workspace-name`
+- **SSH**: `🔗 [project-name] workspace-name (ssh: hostname)`
+
+## SSH Workspaces
+
+### Requirements
+
+For SSH workspaces to work, you need:
+
+1. **Remote-SSH Extension** installed
+   - VS Code: `ms-vscode-remote.remote-ssh`
+   - Cursor: `anysphere.remote-ssh`
+   - The extension automatically detects which one you have
+2. **SSH host configured** in `~/.ssh/config` or in the Remote-SSH extension
+
+### Setup SSH Host
+
+If you haven't configured the SSH host yet:
+
+1. Open `~/.ssh/config` and add:
+
+   ```ssh
+   Host myserver
+     HostName 192.168.1.100
+     User username
+     IdentityFile ~/.ssh/id_rsa
+   ```
+
+2. Or use VS Code's Remote-SSH command:
+   - `Cmd+Shift+P` → "Remote-SSH: Add New SSH Host..."
+
+## Development
+
+For development instructions, see `vscode/README.md` and `vscode/DEVELOPMENT.md` in the
+repository.
+
+## Related
+
+- [Workspaces Overview](./workspaces.md)
+- [SSH Workspaces](./ssh.md)
+- [VS Code Remote-SSH Documentation](https://code.visualstudio.com/docs/remote/ssh)

package.json

@@ -41,8 +41,7 @@
     "docs:watch": "make docs-watch",
     "storybook": "make storybook",
     "storybook:build": "make storybook-build",
-    "test:storybook": "make test-storybook",
-    "rebuild": "echo \"No native modules to rebuild\""
+    "test:storybook": "make test-storybook"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.29",
@@ -82,6 +81,7 @@
     "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
+    "@electron/rebuild": "^4.0.1",
     "@eslint/js": "^9.36.0",
     "@playwright/test": "^1.56.0",
     "@storybook/addon-docs": "^10.0.0",

src/App.stories.tsx

@@ -5,6 +5,7 @@ import type { ProjectConfig } from "./config";
 import type { FrontendWorkspaceMetadata } from "./types/workspace";
 import type { IPCApi } from "./types/ipc";
 import type { ChatStats } from "./types/chatStats";
+import { DEFAULT_RUNTIME_CONFIG } from "@/constants/workspace";
 
 // Stable timestamp for visual testing (Apple demo time: Jan 24, 2024, 9:41 AM PST)
 const STABLE_TIMESTAMP = new Date("2024-01-24T09:41:00-08:00").getTime();
@@ -47,6 +48,7 @@ function setupMockAPI(options: {
             projectPath,
             projectName: projectPath.split("/").pop() ?? "project",
             namedWorkspacePath: `/mock/workspace/${branchName}`,
+            runtimeConfig: DEFAULT_RUNTIME_CONFIG,
           },
         }),
       list: () => Promise.resolve(mockWorkspaces),
@@ -173,6 +175,7 @@ export const SingleProject: Story = {
         projectPath: "/home/user/projects/my-app",
         projectName: "my-app",
         namedWorkspacePath: "/home/user/.cmux/src/my-app/main",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
       {
         id: "f6g7h8i9j0",
@@ -192,6 +195,7 @@ export const SingleProject: Story = {
         projectPath: "/home/user/projects/my-app",
         projectName: "my-app",
         namedWorkspacePath: "/home/user/.cmux/src/my-app/bugfix",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
     ];
 
@@ -247,20 +251,23 @@ export const MultipleProjects: Story = {
         projectPath: "/home/user/projects/frontend",
         projectName: "frontend",
         namedWorkspacePath: "/home/user/.cmux/src/frontend/main",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
       {
         id: "2b3c4d5e6f",
         name: "redesign",
         projectPath: "/home/user/projects/frontend",
         projectName: "frontend",
         namedWorkspacePath: "/home/user/.cmux/src/frontend/redesign",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
       {
         id: "3c4d5e6f7a",
         name: "main",
         projectPath: "/home/user/projects/backend",
         projectName: "backend",
         namedWorkspacePath: "/home/user/.cmux/src/backend/main",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
       {
         id: "4d5e6f7a8b",
@@ -292,6 +299,7 @@ export const MultipleProjects: Story = {
         projectPath: "/home/user/projects/mobile",
         projectName: "mobile",
         namedWorkspacePath: "/home/user/.cmux/src/mobile/main",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
     ];
 
@@ -335,6 +343,7 @@ export const ManyWorkspaces: Story = {
       projectPath: "/home/user/projects/big-app",
       projectName: "big-app",
       namedWorkspacePath: `/home/user/.cmux/src/big-app/${name}`,
+      runtimeConfig: DEFAULT_RUNTIME_CONFIG,
     }));
 
     return <AppWithMocks projects={projects} workspaces={workspaces} />;
@@ -362,6 +371,7 @@ export const ActiveWorkspaceWithChat: Story = {
         projectPath: "/home/user/projects/my-app",
         projectName: "my-app",
         namedWorkspacePath: "/home/user/.cmux/src/my-app/feature",
+        runtimeConfig: DEFAULT_RUNTIME_CONFIG,
       },
     ];
 
@@ -388,6 +398,7 @@ export const ActiveWorkspaceWithChat: Story = {
                     projectPath,
                     projectName: projectPath.split("/").pop() ?? "project",
                     namedWorkspacePath: `/mock/workspace/${branchName}`,
+                    runtimeConfig: DEFAULT_RUNTIME_CONFIG,
                   },
                 }),
               list: () => Promise.resolve(workspaces),
@@ -696,6 +707,7 @@ export const MarkdownTables: Story = {
             projectPath: "/home/user/projects/my-app",
             projectName: "my-app",
             namedWorkspacePath: "/home/user/.cmux/src/my-app/feature",
+            runtimeConfig: DEFAULT_RUNTIME_CONFIG,
           },
         ];
 
@@ -723,6 +735,7 @@ export const MarkdownTables: Story = {
                     projectPath,
                     projectName: projectPath.split("/").pop() ?? "project",
                     namedWorkspacePath: `/mock/workspace/${branchName}`,
+                    runtimeConfig: DEFAULT_RUNTIME_CONFIG,
                   },
                 }),
               list: () => Promise.resolve(workspaces),

src/bench/headlessEnvironment.ts

@@ -105,6 +105,7 @@ export async function createHeadlessEnvironment(
   const mockIpcRendererModule = mockedElectron.ipcRenderer;
 
   const ipcMain = new IpcMain(config);
+  await ipcMain.initialize();
   ipcMain.register(mockIpcMainModule, mockWindow);
 
   const dispose = async () => {

src/config.test.ts

@@ -36,23 +36,23 @@ describe("Config", () => {
   });
 
   describe("getAllWorkspaceMetadata with migration", () => {
-    it("should migrate legacy workspace without metadata file", () => {
+    it("should migrate legacy workspace without metadata file", async () => {
       const projectPath = "/fake/project";
       const workspacePath = path.join(config.srcDir, "project", "feature-branch");
 
       // Create workspace directory
       fs.mkdirSync(workspacePath, { recursive: true });
 
       // Add workspace to config without metadata file
-      config.editConfig((cfg) => {
+      await config.editConfig((cfg) => {
         cfg.projects.set(projectPath, {
           workspaces: [{ path: workspacePath }],
         });
         return cfg;
       });
 
       // Get all metadata (should trigger migration)
-      const allMetadata = config.getAllWorkspaceMetadata();
+      const allMetadata = await config.getAllWorkspaceMetadata();
 
       expect(allMetadata).toHaveLength(1);
       const metadata = allMetadata[0];
@@ -71,7 +71,7 @@ describe("Config", () => {
       expect(workspace.name).toBe("feature-branch");
     });
 
-    it("should use existing metadata file if present (legacy format)", () => {
+    it("should use existing metadata file if present (legacy format)", async () => {
       const projectPath = "/fake/project";
       const workspaceName = "my-feature";
       const workspacePath = path.join(config.srcDir, "project", workspaceName);
@@ -95,15 +95,15 @@ describe("Config", () => {
       fs.writeFileSync(metadataPath, JSON.stringify(existingMetadata));
 
       // Add workspace to config (without id/name, simulating legacy format)
-      config.editConfig((cfg) => {
+      await config.editConfig((cfg) => {
         cfg.projects.set(projectPath, {
           workspaces: [{ path: workspacePath }],
         });
         return cfg;
       });
 
       // Get all metadata (should use existing metadata and migrate to config)
-      const allMetadata = config.getAllWorkspaceMetadata();
+      const allMetadata = await config.getAllWorkspaceMetadata();
 
       expect(allMetadata).toHaveLength(1);
       const metadata = allMetadata[0];