Add isolated dev mode per worktree

.gitignore

@@ -57,6 +57,7 @@ playwright-report/
 coverage/
 
 .channels/
+.codemux-dev/
 
 continuous-analysis/
 .settings.json

README.md

@@ -187,6 +187,36 @@ bun run update:cloudflared
 bun run dev
 ```
 
+### Isolated Electron Dev Instances
+
+Use isolated dev mode when you want to debug CodeMux from a separate git worktree without interrupting your normal running app session:
+
+```bash
+bun run dev:isolated
+```
+
+This keeps `bun run dev` unchanged. The isolated command writes all Electron app state for that worktree under a gitignored `.codemux-dev/` directory:
+
+```text
+.codemux-dev/
+  userData/
+  sessionData/
+  logs/
+  ports.json
+```
+
+Each worktree can have its own `.codemux-dev/` directory and port allocation. The first run automatically reserves a non-default port offset and stores it in `.codemux-dev/ports.json`; later runs reuse that saved offset so the same worktree stays stable. If the saved ports become stale or conflict with another process, stop the existing isolated instance, delete `.codemux-dev/ports.json` to reallocate, or set an explicit `CODEMUX_PORT_OFFSET`.
+
+Supported port overrides:
+
+- `CODEMUX_PORT_OFFSET`
+- `CODEMUX_WEB_PORT`
+- `CODEMUX_WEB_STANDALONE_PORT`
+- `CODEMUX_GATEWAY_PORT`
+- `CODEMUX_OPENCODE_PORT`
+- `CODEMUX_AUTH_API_PORT`
+- `CODEMUX_WEBHOOK_PORT`
+
 ### Linux Server / Headless Dev
 
 On headless Linux hosts, `bun run dev` may exit early because Electron needs a virtual display, a DBus session, and a correctly configured `chrome-sandbox` helper. This repo includes Linux server helpers for that workflow:

electron.vite.config.ts

@@ -6,6 +6,7 @@ import { resolve } from 'path';
 import { createLogger } from 'vite';
 import { createAuthProxyPlugin } from './scripts/auth-proxy-plugin';
 import { tunnelManager } from './scripts/tunnel-manager';
+import { GATEWAY_PORT, OPENCODE_PORT, WEBHOOK_PORT, WEB_PORT } from './shared/ports';
 
 // Custom logger that suppresses proxy errors during startup
 const logger = createLogger();
@@ -70,7 +71,7 @@ export default defineConfig({
       // Proxy auth/device API requests to Electron's internal Auth API server
       createAuthProxyPlugin({
         tunnelManager,
-        defaultPort: 8233,
+        defaultPort: WEB_PORT,
       }),
     ],
     resolve: {
@@ -81,29 +82,29 @@ export default defineConfig({
     server: {
       hmr: false,
       host: true,
-      port: 8233,
+      port: WEB_PORT,
       allowedHosts: true,
       proxy: {
         // Proxy Gateway WebSocket to the Gateway server
         '/ws': {
-          target: 'http://localhost:4200',
+          target: `http://localhost:${GATEWAY_PORT}`,
           ws: true,
         },
         // Proxy OpenCode API requests to the OpenCode server
         '/opencode-api': {
-          target: 'http://localhost:4096',
+          target: `http://localhost:${OPENCODE_PORT}`,
           changeOrigin: true,
           rewrite: (path) => path.replace(/^\/opencode-api/, ''),
           // Handle SSE connections properly
           ws: false,
         },
         // Proxy webhook endpoints to the WebhookServer
         '/api/messages': {
-          target: 'http://localhost:4098',
+          target: `http://localhost:${WEBHOOK_PORT}`,
           changeOrigin: true,
         },
         '/webhook': {
-          target: 'http://localhost:4098',
+          target: `http://localhost:${WEBHOOK_PORT}`,
           changeOrigin: true,
         },
       },