🤖 feat: add VS Code extension for cmux workspace switching (#553)

## Overview

Adds a VS Code/Cursor extension that allows users to quickly open cmux
workspaces directly from the editor.

## Features

- **Command Palette Integration**: Access cmux workspaces via `cmux:
Open Workspace` command
- **Local Workspaces**: Opens local cmux workspaces (git worktrees) in
new editor windows
- **SSH Workspaces**: Opens remote SSH workspaces using Remote-SSH
extension
- Automatically detects VS Code Remote-SSH
(`ms-vscode-remote.remote-ssh`)
  - Automatically detects Cursor Remote-SSH (`anysphere.remote-ssh`)
- **UI-Only Extension**: Runs locally, available in all contexts (local
and remote workspaces)
- **Smart Detection**: Reads workspace list from `~/.cmux/config.json`
- **Error Handling**: Provides clear guidance for SSH setup and missing
extensions

Co-authored-by: Ammar Bandukwala <ammar@ammar.io>

Author: ammar-agent

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

bun.lock

@@ -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/SUMMARY.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)

docs/img/vscode-ext.webp

@@ -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",