Skip to content

Self-improving AI Employees for everyone

docs: cover the desktop app across the user and contributor docs

trohitgd3a67227d3c3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5a1da52f..94a610ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -57,6 +57,7 @@ Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [nati
| `server/config/` | llm_defaults.json, pricing.json, model_registry.json, email_providers.json, google_apis.json, credential_providers.json, ai_cli_providers.json, node_allowlist.json | [pricing_service.md](docs-internal/pricing_service.md), [node_allowlist.md](docs-internal/node_allowlist.md) |
| `server/tests/` | Contract-test invariants + per-category node tests + `NodeTestHarness` | [tests/nodes/_harness.py](server/tests/nodes/_harness.py), [tests/credentials/README.md](server/tests/credentials/README.md) |
| `client/src/` (styling + themes) | Tailwind tokens, shadcn primitives, the 12-theme contract | [frontend_architecture.md](docs-internal/frontend_architecture.md), [theme_system.md](docs-internal/theme_system.md) |
+| `desktop/` | Electron desktop shell — a standalone bun package (not a root workspace member) that bundles uv + Python + Node, provisions the backend venv on first launch and hosts the backend-served SPA in a native window | [desktop_app.md](docs-internal/desktop_app.md), [desktop_host_contract.md](docs-internal/desktop_host_contract.md) |
| `docs-internal/` | In-repo architecture deep dives (50+ files) | Index below |
## How to Contribute Features
@@ -122,6 +123,7 @@ The diagram above shows the full lifecycle of a workflow node: one self-containe
- **Import sanity:** `uv run pytest --collect-only` (from `server/`) is the live plugin-count invariant — it fails if any plugin errors at import.
- **Credential tests** follow the numbered-invariant style documented in [server/tests/credentials/README.md](server/tests/credentials/README.md).
- Run everything: `uv run pytest` from `server/`, `bun run --filter react-flow-client test` from the repo root, `uv run pytest cli/tests` from the repo root.
+- **Desktop shell:** from `desktop/`, `bun run typecheck && bun run test && bun run test:invariants` (the last needs `bun run stage` first), and `bun run build && bun run test:e2e` for the Playwright Electron smoke. In an editor-hosted terminal unset `ELECTRON_RUN_AS_NODE` before launching Electron by hand.
## Local Dev Quick Reference
@@ -137,6 +139,10 @@ bun run --filter react-flow-client typecheck:tsc # second opinion under tsc 5.9
uv run pytest # run backend tests (from server/, uv-managed venv)
```
+The desktop shell has its own package: `cd desktop && bun install && bun run stage && bun run dev` (see [desktop/README.md](desktop/README.md)). It is not a root workspace member, so root `bun install` does not touch it.
+
+`server/uv.lock` is committed. After changing `server/pyproject.toml`, run `uv lock` in `server/` and commit the lock too; CI fails with `uv lock --check` otherwise, and the desktop app installs from the lock with `--frozen`.
+
**Known differences from pnpm** (the workspace migrated from pnpm@9 to [email protected]):
- **No strict-peer-dependencies equivalent.** bun never errors on peer conflicts, so the check that kept client `typescript` inside typescript-eslint's peer range is gone from install time — the CLI test locking client `typescript` to `^5` (`cli/tests/test_release_pipeline_config.py`) is now the only guard.
@@ -177,6 +183,8 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [pricing_service.md](docs-internal/pricing_service.md) | LLM and API cost tracking |
| [proxy_service.md](docs-internal/proxy_service.md) | Residential proxy provider management |
| [ci_cd.md](docs-internal/ci_cd.md) | GitHub Actions workflows |
+| [desktop_app.md](docs-internal/desktop_app.md) | Electron desktop shell: bundled runtimes, first-run provisioning, packaging, updates, CI |
+| [desktop_host_contract.md](docs-internal/desktop_host_contract.md) | The backend's side of being owned by a GUI shell: relocatable app root, readiness, watchdogs, shutdown route |
| [node_creation.md](docs-internal/node_creation.md) | How to create new nodes |
| [memory_lifecycle.md](docs-internal/ARCHIVE/memory_lifecycle.md) | *Archived* pre-RFC-0002 markdown memory model; see agent_context_flow.md and memory_compaction.md |
| [tool_building_pipeline.md](docs-internal/tool_building_pipeline.md) | Canonical home for `_build_tool_from_node`, tool discovery, per-type Temporal dispatch |
diff --git a/README.md b/README.md
index 8e65063f..ee359588 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ company start
Open http://localhost:5678 (default `PYTHON_BACKEND_PORT`) and click the key icon (**API Credentials**) in the toolbar to connect your first AI provider.
+**Prefer a desktop app?** Installers for Windows (`.exe`), macOS (`.dmg`, Apple Silicon and Intel) and Linux (`.AppImage` / `.deb`) are attached to every [GitHub Release](https://github.com/zeenie-ai/OpenCompany/releases). They need no Python or Node on the machine: the app bundles them, sets up the backend on first launch (one-time download, a minute or two), and shares its data with a CLI install in `~/.opencompany`. The first releases are unsigned, so macOS asks you to allow the app under System Settings > Privacy & Security and Windows SmartScreen needs "More info > Run anyway". Details in [docs-internal/desktop_app.md](docs-internal/desktop_app.md).
+
<details>
<summary><b>Run from source (for contributors)</b></summary>
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index b8b8b809..1683b374 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -36,6 +36,21 @@ deprecation warning; kept for upgrade compatibility).
There is no `help` verb: `company` with no arguments, `company --help`, and
`company <verb> --help` print Typer's help (`no_args_is_help=True` in `cli/cli.py`).
+### Desktop shell scripts (`desktop/package.json`, run from `desktop/`)
+
+The Electron shell is its own bun package with its own lockfile; root `bun run` does not reach it.
+
+| Command | Description |
+|---------|-------------|
+| `bun run stage` | Assemble `stage/`: the backend sibling layout from `npm pack --dry-run` (CLI, install scripts, client sources and backend tests dropped; `server/uv.lock` force-included; Node sidecar re-bundled with express inlined) plus the pinned runtimes for this host. `--target mac-arm64,mac-x64` stages other targets; `--skip-runtimes` stages app-root only |
+| `bun run fetch-runtimes` | Just the runtimes: download uv / python-build-standalone / Node pinned in `runtimes.json`, verify against the upstream checksum manifests, cache in `vendor/`, extract into `stage/runtime/<os>-<arch>/` |
+| `bun run dev` | electron-vite dev against `stage/` (`OPENCOMPANY_DESKTOP_APP_ROOT=..` and `OPENCOMPANY_DESKTOP_VENV_PYTHON=../server/.venv/...` run against the checkout without staging or provisioning) |
+| `bun run build` | electron-vite build of main / preload / setup renderer into `out/` |
+| `bun run typecheck` / `bun run test` / `bun run test:invariants` / `bun run test:e2e` | TS7 gate; vitest unit tests; staged-tree invariants (after `stage`); Playwright Electron smoke (after `build`) |
+| `bun run gen-icons` | Render `build/icon.svg` to `build/icon.png` (electron-builder derives icns / ico / Linux PNGs) |
+| `bun run sync-version` | Copy the root `package.json` version into `desktop/package.json` (CI runs it before `dist`) |
+| `bun run pack` / `bun run dist` | electron-builder unpacked dir / installers into `release/` |
+
### Dependency checks
`build` checks that Node.js and npm/bun are present (no version floor), verifies
diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.md
index c28637fb..086f90af 100644
--- a/docs-internal/SETUP.md
+++ b/docs-internal/SETUP.md
@@ -72,6 +72,30 @@ Services (production `company start`; every port is declared once in `.env.templ
`company dev` serves the same app URL from the Vite HMR server, which proxies /api /ws /webhook /health /mcp to the backend; `.env.dev` moves the backend one port up (`PYTHON_BACKEND_PORT` override) so the app URL stays put.
+### Desktop app (Electron shell)
+
+End users can skip Python and Node entirely: the installers attached to each
+GitHub Release bundle `uv`, a standalone CPython 3.12 and Node 22, provision
+the backend's virtual environment into the app's data directory on first
+launch (one-time download of the Python wheels, plus the Temporal binary the
+CLI also downloads), and host the same backend-served UI in a native window.
+Data lives in `~/.opencompany` exactly as for a CLI install, so both can be
+used on one machine; the shell even attaches to a `company serve` that is
+already running on the app port instead of starting a second backend.
+
+Developing the shell (from a built checkout — `client/dist` and the sidecar
+bundle must exist):
+
+```bash
+cd desktop
+bun install
+bun run stage # app-root + pinned runtimes for this machine
+bun run dev # or: OPENCOMPANY_DESKTOP_APP_ROOT=.. OPENCOMPANY_DESKTOP_VENV_PYTHON=../server/.venv/bin/python bun run dev
+```
+
+Full reference: [desktop_app.md](./desktop_app.md); the backend's side of
+the arrangement is [desktop_host_contract.md](./desktop_host_contract.md).
+
## Services Overview
### Frontend (React — always at the app port; Vite dev server proxying the backend, or the production build served by uvicorn)
@@ -177,7 +201,7 @@ PYTHON_BACKEND_PORT=6678
```
### Python dependencies fail
-The server is uv-managed — prefer `uv sync` from `server/` (creates `server/.venv` against `uv.lock`). The pip fallback works too:
+The server is uv-managed — prefer `uv sync` from `server/` (creates `server/.venv` against the committed `uv.lock`; after editing `pyproject.toml` run `uv lock` and commit the result, CI checks it with `uv lock --check`). The pip fallback works too:
```bash
cd server
python -m venv venv
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index 5a774363..b48aecac 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -39,6 +39,8 @@ The repo currently ships **three workflows** plus one composite action. A number
| CI | `.github/workflows/ci.yml` | push/PR → main | Delegates to predeploy.yml |
| Predeploy | `.github/workflows/predeploy.yml` | `workflow_call` | build/lint + backend tests + CLI tests + cross-OS build/start smoke |
| Release | `.github/workflows/release.yml` | `v*.*.*` tag, `workflow_dispatch` | predeploy gate → publish (npm + GitHub Packages) |
+| Desktop CI | `.github/workflows/desktop-ci.yml` | PR touching `desktop/**` or the backend host-contract files; push to main touching `desktop/**` | typecheck + unit + staged-tree invariants + `electron-vite build` + Playwright Electron smoke on ubuntu-22.04 (xvfb) and windows-latest |
+| Desktop release | `.github/workflows/desktop-release.yml` | `v*.*.*` tag, `workflow_dispatch` | 3-runner matrix (windows-latest x64, macos-14 arm64+x64, ubuntu-22.04 x64) builds installers with electron-builder into one **draft** GitHub Release; `finalize` undrafts once every leg is green. Artifacts-only on dispatch unless `publish` is ticked |
| Setup | `.github/actions/setup/action.yml` | (composite) | bun 1.4 + Node 22 + Python 3.12 + uv v8 + editable CLI install |
### Toolchain pin
@@ -50,7 +52,9 @@ The repo currently ships **three workflows** plus one composite action. A number
| Secret | Used by | Description |
|--------|---------|-------------|
| `NPM_TOKEN` | release.yml | npmjs publish access to the public `@zeenie-ai` scope (`publish-npm`) |
-| `GITHUB_TOKEN` | release.yml | GitHub Packages publish (auto-provided) |
+| `GITHUB_TOKEN` | release.yml, desktop-release.yml | GitHub Packages publish; desktop installer upload to the draft release and the `finalize` undraft (auto-provided; the desktop workflow needs `contents: write`) |
+
+Desktop code signing is deliberately absent for the first releases: `CSC_IDENTITY_AUTO_DISCOVERY=false` is set so electron-builder never looks for a certificate. Adding it later is secrets-only (`CSC_LINK` + `CSC_KEY_PASSWORD` for Windows; a Developer ID cert plus `APPLE_ID` / `APPLE_APP_SPECIFIC_PASSWORD` / `APPLE_TEAM_ID` for macOS) plus the three mac flags in `desktop/electron-builder.yml` — see [desktop_app.md](./desktop_app.md#signing-and-updates).
---
@@ -85,7 +89,7 @@ After tool install the composite installs the supervisor CLI editably (`uv pip i
Reusable `workflow_call` workflow with four independent jobs (no plan/change-detection gate, no aggregator — every job runs on every call):
- `build-and-lint` — `bun install --frozen-lockfile` + `bun run build`, then client lint (`bun run --filter react-flow-client lint`), TypeScript check (`... typecheck`), and frontend tests (`... test`, vitest). Runs on `ubuntu-latest`.
-- `backend-tests` — `uv sync` + `uv run pytest tests/ -v` in `server/`. Whole suite, unsharded. Runs on `ubuntu-latest`.
+- `backend-tests` — `uv lock --check` (the committed `server/uv.lock` must match `pyproject.toml`; the desktop app installs from it with `--frozen`), then `uv sync` + `uv run pytest tests/ -v` in `server/`. Whole suite, unsharded. Runs on `ubuntu-latest`.
- `cli-tests` — `uv pip install --system pytest pytest-asyncio pyyaml` + `python -m pytest cli/tests/ -v`. Runs on `ubuntu-latest`.
- `test-build-start` — cross-OS matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`, `fail-fast: false`). Runs `bun run build`, then `bun run tsc --version` (proves the per-platform TypeScript 7 Go binary delivered via `optionalDependencies` resolves on every OS — the type-check gate itself runs on ubuntu only; `bun run`, never `bunx`, so it resolves strictly from the root `node_modules/.bin`), then a start smoke test. On Unix it backgrounds `bun run start`, reads `PYTHON_BACKEND_PORT` out of `.env.template` and polls `http://localhost:${APP_PORT}/health` for up to ~30 s, then `bun run stop`. On Windows it starts the supervisor as a background job, waits 15 s, and fails if the job already exited.
@@ -151,6 +155,8 @@ folder — both the folder and the workflow are gone.
| `.github/workflows/ci.yml` | CI entry point (delegates to predeploy.yml) |
| `.github/workflows/predeploy.yml` | Reusable validation (build/lint + backend tests + CLI tests + OS matrix build/start) |
| `.github/workflows/release.yml` | Tag / manual release: predeploy gate → publish npm + GitHub Packages |
+| `.github/workflows/desktop-ci.yml` | Desktop shell checks on PRs: typecheck, unit, invariants, build, Playwright smoke |
+| `.github/workflows/desktop-release.yml` | Tag-triggered desktop installers (NSIS / DMG+zip / AppImage+deb) into a draft release, then undraft. Separate from `release.yml` so npm publish is never blocked |
| `.github/actions/setup/action.yml` | Composite: bun + Node + Python + uv + editable CLI install |
| `.github/dependabot.yml` | **Security updates only** — version-update PRs disabled; see below |
| `.python-version` | Toolchain pin (`3.12`) — single source of truth |
diff --git a/docs-internal/errors.md b/docs-internal/errors.md
index 920ad97a..87f06949 100644
--- a/docs-internal/errors.md
+++ b/docs-internal/errors.md
@@ -472,3 +472,30 @@ uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the
**Root cause**: The sidecar bundle is built with `--packages=external`, so Express stays a runtime dependency, but it was declared only in `server/nodejs/package.json`. The npm package excludes every `node_modules`, and `nodes/code/_runtime.py` only checks that `dist/index.js` exists, so nothing ever installed Express on an npm-installed copy. Source checkouts never saw it because `bun install` provisions the workspace.
**Fix**: `express` is declared in the root `package.json` `dependencies`, so npm installs it beside the package and Node resolves it from `server/nodejs/dist` by walking up to the package root. Nothing else changed; the sidecar still runs under whichever `node` is on `PATH` (18+ verified on Ubuntu 24.04's distro package).
+
+## 20. Graceful backend shutdown hangs, then the supervisor tree-kills it (Temporal / node / edgymeow orphaned)
+
+**Symptom**: `company stop`, Ctrl+C, or the desktop app's quit takes the full grace window and ends in a tree-kill. With the lifespan markers (`Lifespan shutdown: ...` in stdout) the log stops after `proxy stopped`, or never prints `Lifespan shutdown begin` at all.
+
+**Root causes** (two, found while building the desktop shell; the CLI's 5 s grace + tree-kill had masked both):
+
+1. `nodes/browser/_service.py::shutdown_browser_service` called `get_browser_service()`, which lazily runs `npm install agent-browser@latest` on first call — so a process that never used the browser ran a network install *at teardown*, synchronously on the event loop, and every graceful exit wedged there.
+2. uvicorn's `timeout_graceful_shutdown` defaults to `None`: it waits forever for open connections and in-flight handler tasks before sending the lifespan shutdown. A browser WebSocket that disappears with a TCP reset (the tab or window closing) can leave its handler task lingering, and the lifespan teardown — the part that reaps the child daemons — is never reached.
+
+**Fix**: the browser hook reads its module singleton and closes only a service that was actually created; every plugin shutdown hook now runs under `HOOK_TIMEOUT_SECONDS` (10 s, `services/plugin/shutdown_hooks.py`) and names the offender at WARNING; `company serve` / `company start` and the desktop shell pass `--timeout-graceful-shutdown 5` (`cli/_common.py::UVICORN_GRACEFUL_SHUTDOWN_SECONDS`). Note that the hook timeout cannot interrupt a hook that blocks the loop synchronously — keep hooks async.
+
+## 21. Electron boots as plain Node: `Cannot read properties of undefined (reading 'isPackaged')` / Playwright `Process failed to launch!`
+
+**Symptom**: Launching the desktop shell (or its Playwright smoke) from a terminal inside VS Code, Claude Code or another Electron-hosted editor crashes immediately with `electron.app` undefined; Playwright only reports `Process failed to launch!`.
+
+**Root cause**: Editor-hosted terminals export `ELECTRON_RUN_AS_NODE=1`. Electron honours it and starts as a bare Node runtime, so `require("electron")` returns the binary path string instead of the API.
+
+**Fix**: `unset ELECTRON_RUN_AS_NODE` before launching Electron by hand; `desktop/tests/e2e/smoke.spec.ts` strips it from the environment it passes to `electron.launch`, and `desktop/src/main/env.ts` strips it from the backend's environment too.
+
+## 22. Desktop runtime extraction fails on Windows: `tar: This does not look like a tar archive` / `Cannot connect to D: resolve failed`
+
+**Symptom**: `bun run stage` / `bun run fetch-runtimes` fails while extracting the uv zip or a Node archive.
+
+**Root cause**: The `tar` first on PATH in a Git Bash shell is Git for Windows' GNU tar, which cannot read `.zip` and parses `D:\...` as `host:path`. The system bsdtar at `%SystemRoot%\System32\tar.exe` handles zip, tar.gz and tar.xz.
+
+**Fix**: `desktop/scripts/_lib.ts::tarBinary()` prefers the System32 tar on Windows and always passes the archive as a path relative to the extraction directory so no argument carries a drive colon.
diff --git a/docs-internal/performance.md b/docs-internal/performance.md
index f793db77..e2b482c8 100644
--- a/docs-internal/performance.md
+++ b/docs-internal/performance.md
@@ -298,6 +298,8 @@ These were observed and fixed; the lessons are durable.
- **`if (event.code !== 1000)` magic numbers** scattered through the WS lifecycle. Replaced with `WS_CLOSE.NORMAL_CLOSURE` from [connectionConfig.ts](../client/src/lib/connectionConfig.ts) per RFC 6455 §7.4.1.
- **Inline `chunkSizeWarningLimit: 1500`** silently masking bundle bloat. Lowered to 850 KB so future regressions surface at `vite build` time.
+- **Setting `PYTHONPYCACHEPREFIX` without pre-warming it.** With a prefix set, CPython ignores every in-tree `__pycache__` — site-packages included — so the first boot recompiles ~20k files (measured 32 s vs 2.9 s warm). The desktop shell needs the prefix because its bundle is read-only, and pays the cost once during provisioning with `python -m compileall -q -j 0 <venv> <server>` under the same prefix (`desktop/src/main/provision.ts`). The CLI path does not set a prefix and keeps uv's `compile-bytecode = true` output in-tree.
+
## Open follow-ups
Tracked but explicitly **not** in any active plan.
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 5d4fbe82..1f3804ed 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -160,6 +160,7 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis
### 6. Tarball verification
- `npm pack --dry-run` after the change. Confirm `server/nodejs/dist/index.js` is included (existing `server/` glob already covers it). Confirm no `__pycache__/` leakage.
+- `server/uv.lock` is committed (since the desktop app) and ships in the tarball; `.npmignore` only hides `package-lock.json`. The desktop stage script also reads the `npm pack --dry-run --json` file list as its layout source of truth, so a change to the root `files` allowlist reaches the desktop bundle automatically.
## Critical files
@@ -185,9 +186,13 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis
6. `npm pack --dry-run` → `server/nodejs/dist/index.js` included; no `__pycache__/`; tarball size ≤ v0.0.76.
7. Smoke: `company start` → load the app URL (`http://localhost:${PYTHON_BACKEND_PORT}`) → run "AI Assistant" example → agent responds.
+## Desktop installers
+
+The Electron shell has its own pipeline (`.github/workflows/desktop-release.yml`) that consumes this one's outputs (`client/dist`, the sidecar bundle) and adds the bundled runtimes; it is documented in [desktop_app.md](./desktop_app.md). Nuitka / PyOxidizer freezing was evaluated and rejected there: `temporalio`'s PyO3 bridge, `dependency-injector` wiring by string, `pkgutil.walk_packages` plugin discovery and `uv tool install browser-harness` at runtime all need a real interpreter on disk.
+
## Out of scope (future work)
-- Nuitka / PyOxidizer standalone binaries (separate release channel, ~1-2 weeks CI matrix).
+- Nuitka / PyOxidizer standalone binaries — rejected for the desktop app (see above); a separate release channel for the CLI would face the same constraints.
- Plugin walker lazy-loading (~11s).
- Service-status refresh parallelisation (~20s post-startup-complete).
- mypyc / Cython for hot paths (low ROI — pydantic V2 already Rust, httpx/aiohttp already C).