BuzzbeeSCD/openchamber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update desktop platform docs

Browse Source 
Document macOS and Windows desktop support
Add Electron desktop development README
Refresh contributing scripts and platform notes
This commit is contained in:
Bohdan Triapitsyn
2026-06-05 23:58:43 +03:00
parent 48b0a4f292
commit 45bad4c12b
3 changed files with 228 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+68 -8
View File
@@ -10,37 +10,91 @@ bun install
## Dev Scripts
Run commands from the project root unless a section says otherwise.
### Web
| Script | Description | Ports |
|--------|-------------|-------|
| `bun run dev` | Default web HMR dev flow. | auto-selected dev ports |
| `bun run dev:web:full` | Build watcher + Express server. No HMR — manual refresh after changes. | `3001` (server + static) |
| `bun run dev:web:hmr` | Vite dev server + Express API. **Open the Vite URL for HMR**, not the backend. | `5180` (Vite HMR), `3902` (API) |
| `bun run start:web` | Start the packaged web server. | `3000` by default |
Both are configurable via env vars: `OPENCHAMBER_PORT`, `OPENCHAMBER_HMR_UI_PORT`, `OPENCHAMBER_HMR_API_PORT`.
### Desktop (Electron)
```bash
bun run electron:dev
bun run electron:dev # HMR web UI + Electron shell
bun run electron:dev:bundled # Electron shell using built web assets
bun run electron:build # Package desktop app for the current platform
```
Launches the Electron desktop shell in dev mode.
Desktop supports macOS and Windows. The build output is written to `packages/electron/dist`.
macOS builds create `dmg` and `zip` files. You need Xcode/build tools for notarized packaging and icon asset work.
Windows builds create an NSIS installer. If signing env vars are not set, the build script makes an unsigned installer.
For desktop-specific details, see [`packages/electron/README.md`](./packages/electron/README.md).
### VS Code Extension
```bash
bun run vscode:dev # Watch mode (extension + webview rebuild on save)
bun run vscode:dev # Watch mode + Extension Development Host
bun run vscode:build # Build extension + webview
bun run vscode:package # Create a local .vsix package
```
To test in VS Code:
```bash
bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode"
```
`bun run vscode:dev` opens an Extension Development Host automatically. You can override the editor or workspace with `OPENCHAMBER_VSCODE_BIN` and `OPENCHAMBER_VSCODE_DEV_WORKSPACE`.
Example: `OPENCHAMBER_VSCODE_BIN=cursor bun run vscode:dev`.
### Shared UI (`packages/ui`)
No dev server — this is a source-level library consumed by other packages. During development, `bun run dev` runs type-checking in watch mode.
No standalone app server. This is a source-level library used by Web, Desktop, and VS Code.
Useful package commands:
```bash
bun run build:ui
bun run type-check:ui
bun run lint:ui
```
## Build And Package Commands
| Command | What it does |
|---------|--------------|
| `bun run build` | Build all workspaces |
| `bun run build:web` | Build only `packages/web` |
| `bun run build:ui` | Build only `packages/ui` |
| `bun run build:electron` | Run Electron package build script without full packaging |
| `bun run electron:build` | Build packaged desktop app for the current OS |
| `bun run vscode:build` | Build the VS Code extension |
| `bun run vscode:package` | Package the VS Code extension as `.vsix` |
| `bun run pack:web` | Create a package archive for `@openchamber/web` |
## Platform Build Notes
You usually build desktop installers on the target platform.
macOS:
```bash
bun run electron:build
bun run release:test:intel
bun run release:test:arm
```
Windows:
```bash
bun run electron:build
```
Linux is supported for web/CLI development. A Linux desktop app is still planned, so Electron packaging is mainly macOS and Windows right now.
## Before Submitting
@@ -50,6 +104,12 @@ bun run lint # Must pass
bun run build # Must succeed
```
For docs-only changes, validation may be enough:
```bash
bun run docs:validate
```
## Code Style
- Functional React components only
README.md
+20 -15
View File
@@ -58,13 +58,16 @@
- Background notifications plus reliable cross-tab session activity tracking
- Built-in self-update + restart flow that keeps your server settings intact
### Desktop (macOS)
### Desktop (macOS + Windows)
- Native macOS menu integration with polished app actions and deep-link handling
- Multi-window support for parallel project/session workflows
- "Open In" shortcuts for Finder, Terminal, and your preferred editor
- Fast switching between local and remote instances
- Workspace-first startup flow with directory picker and steadier window restore behavior
- Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal
- Multiple native windows for separate projects or sessions
- Native notifications for task alerts while OpenChamber is hidden
- One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more
- Desktop host switcher for local and remote OpenChamber instances
- Convenient tunnel management without manual setup
- Deep-link connections for joining remote OpenChamber from a link
- SSH remote access with host import, connection management, and port forwarding
### VS Code Extension
@@ -86,7 +89,7 @@
> **Prerequisite:** [OpenCode CLI](https://opencode.ai) installed.
### **Desktop (macOS)**
### **Desktop (macOS + Windows)**
Download from [Releases](https://github.com/btriapitsyn/openchamber/releases).
### **VS Code**
@@ -350,14 +353,16 @@ chown -R 1000:1000 data/
</details>
<details>
<summary><strong>Desktop (macOS)</strong></summary>
<summary><strong>Desktop (macOS + Windows)</strong></summary>
- Connect to remote OpenChamber instances over SSH with dedicated lifecycle flows
- Project Actions: run dev servers, SSH port forwarding, open remote URLs locally
- Multi-window support for parallel project workflows
- "Open In" shortcuts for Finder, Terminal, and your preferred editor
- Fast switching between local and remote instances
- Native macOS menu, deep-link handling, and polished startup
- Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal
- Multiple native windows for separate projects or sessions
- Native notifications for task alerts while OpenChamber is hidden
- One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more
- Desktop host switcher for local and remote OpenChamber instances
- Convenient tunnel management without manual setup
- Deep-link connections for joining remote OpenChamber from a link
- SSH remote access with host import, connection management, and port forwarding
</details>
@@ -402,7 +407,7 @@ chown -R 1000:1000 data/
Active development. Here's what's being worked on or planned:
- Windows and Linux desktop apps
- Linux desktop app
- Mobile app with remote instance and laptop connectivity
- More built-in tunneling options
- Kanban board for multi-agent management - keeping the human in the loop and in control
packages/electron/README.md
+140
View File
@@ -0,0 +1,140 @@
# OpenChamber Desktop
Electron desktop runtime for OpenChamber on macOS and Windows.
This package owns the native shell: windows, menus, deep links, native notifications, auto-updates, host switching, SSH connections, tunnel helpers, and packaged desktop builds. The web UI and OpenChamber server logic still live in `packages/web` and shared React UI lives in `packages/ui`.
## How It Runs
Desktop starts the OpenChamber web server in the same Electron main process. There is no separate sidecar subprocess for the OpenChamber server.
`main.mjs` imports `@openchamber/web/server/index.js` and calls `startWebUiServer()`. The Electron window then loads the UI from the local server in development, or from packaged `resources/web-dist` assets in packaged builds.
The preload bridge exposes desktop-only APIs to the web UI through `window.__OPENCHAMBER_DESKTOP__`. Privileged commands are checked in `main.mjs`, not only in the UI.
## Main Files
| File | Purpose |
|------|---------|
| `main.mjs` | Electron main process, app lifecycle, windows, menus, deep links, native IPC handlers, updates, local server startup |
| `preload.mjs` | Safe bridge from the rendered UI to Electron IPC |
| `ssh-manager.mjs` | SSH host import, connection lifecycle, tunnel/port forwarding helpers |
| `scripts/electron-dev.mjs` | Desktop dev launcher with Vite HMR support |
| `scripts/build-web-assets.mjs` | Builds `packages/web` and stages UI assets into `resources/web-dist` |
| `scripts/bundle-main.mjs` | Bundles Electron main code into `dist-bundle/main.mjs` for packaging |
| `scripts/rebuild-native.mjs` | Rebuilds native modules against the Electron runtime |
| `scripts/package.mjs` | Runs `electron-builder`, with unsigned Windows builds when signing env is missing |
| `resources/` | Packaged web assets, icons, and macOS entitlements |
## Development
From the repo root:
```bash
bun install
bun run electron:dev
```
`bun run electron:dev` starts the web dev server with HMR, then launches Electron against `packages/electron/main.mjs`.
Useful variants:
```bash
bun run electron:dev:bundled
bun run type-check:electron
bun run lint:electron
```
`electron:dev:bundled` builds and uses packaged web assets instead of the HMR server. Use it when testing behavior closer to a packaged app.
## Packaging
From the repo root:
```bash
bun run electron:build
```
That runs, in order:
1. `build:web-assets` to build the web UI and copy it into `packages/electron/resources/web-dist`.
2. `bundle:main` to create `packages/electron/dist-bundle/main.mjs`.
3. `rebuild:native` to rebuild native modules for Electron.
4. `package.mjs` to run `electron-builder`.
Build output goes to `packages/electron/dist`.
macOS builds produce `dmg` and `zip` artifacts. Windows builds produce an NSIS installer.
## Platform Notes
macOS packaging needs Xcode/build tools for notarized builds and icon asset compilation.
Windows packaging needs NSIS support through `electron-builder`. If no Windows signing env is set, `package.mjs` disables code signing and builds an unsigned installer.
The package supports macOS and Windows desktop features. Some native discovery helpers are platform-specific. For example, app icon fetching and app filtering currently only work on macOS, while opening files in installed apps works on macOS and Windows.
## Common Env Vars
| Variable | Use |
|----------|-----|
| `OPENCHAMBER_ELECTRON_DEV=1` | Marks the runtime as desktop development mode |
| `OPENCHAMBER_ELECTRON_USE_BUNDLED_UI=1` | Uses staged web assets instead of the HMR dev server |
| `OPENCHAMBER_HMR_UI_PORT` | Preferred Vite UI port for desktop dev, default `5173` |
| `OPENCHAMBER_HMR_API_PORT` | Preferred API port for desktop dev, default `3901` |
| `OPENCHAMBER_RUNTIME=desktop` | Set by Electron before starting the web server |
| `OPENCHAMBER_DESKTOP_NOTIFY=true` | Enables desktop notification flow in the web server |
| `OPENCHAMBER_SKIP_API_COMPRESSION=true` | Defaulted by Desktop to reduce local CPU overhead |
| `OPENCODE_HOST` / `OPENCODE_PORT` / `OPENCODE_SKIP_START` | Connect Desktop to an external OpenCode server instead of starting one locally |
## Native Features Owned Here
- Floating Mini Chat windows.
- Multiple native windows.
- Native notifications.
- One-click open/reveal/open-in-app actions.
- Desktop host switcher and deep-link imports.
- Local and remote instance handling.
- SSH host import, connections, logs, and port forwarding.
- Tunnel lifecycle integration through the web server runtime.
- Auto-update checks, downloads, and restart/apply flow.
## IPC Pattern
Renderer code should call the desktop bridge exposed by `preload.mjs`. Do not import Electron from shared UI code.
Add new native capabilities in this order:
1. Add or update the `preload.mjs` bridge only if a new renderer-facing shape is needed.
2. Add the real command handling in `main.mjs` under `openchamber:invoke`.
3. Gate privileged commands in main process logic so remote pages cannot access local filesystem or shell capabilities.
4. Keep shared UI runtime contracts in `packages/ui` and server/runtime APIs in `packages/web` when the behavior is not inherently native.
## Logs And Data
Electron uses `electron-log`. In development, console logs are also visible in the terminal. In packaged apps, logs are written through the platform log path for the `OpenChamber` app name.
Development builds use a separate user data directory named `OpenChamber Dev`, so dev state does not overwrite normal packaged app state.
## Things To Be Careful With
- Keep desktop-specific code in this package. Do not move OpenCode feature backend logic into Electron.
- Use hidden Windows process launches for background helpers. Avoid visible console flashes.
- Keep `@openchamber/web`, `bun-pty`, `node-pty`, and native modules external in `bundle-main.mjs`; bundling them can break Electron startup.
- Rebuild native modules after dependency or Electron version changes.
- Test both HMR dev mode and bundled UI mode when changing startup, preload, routing, or packaged asset behavior.
## Quick Checks
```bash
bun run type-check:electron
bun run lint:electron
bun run electron:dev:bundled
```
For full repo validation before shipping:
```bash
bun run type-check
bun run lint
```