Zeno

Zeno is a desktop shell for the pi coding agent: a Codex-style UI that keeps configuration, packages, sessions, and tools on the native pi side (~/.pi/agent).

Zeno desktop shell — sidebar, session workspace, and composer:

Animated demo:

• Node.js 22.19 or newer
• pnpm 11.15.1

pnpm install
pnpm electron:install

electron:install downloads the Electron 43 runtime for your platform.

Apps have independent dev / build entry points at the repo root:

pnpm dev           # hot reload: Vite HMR for renderer + auto-restart for main process
pnpm run dev:once  # one-shot build + launch (no watch)
pnpm build:desktop # compile only (no Electron launch)

pnpm dev starts a Vite dev server on http://localhost:5173 for the renderer (React HMR — component changes appear instantly without restart) and runs build watchers for main / preload / agent-host. When backend source code changes, Electron restarts automatically.

Use dev:once for CI or when you need a single cold launch without file watching.

Product launch uses your real HOME and the same agent dir as the CLI (~/.pi/agent / PI_CODING_AGENT_DIR). Models, API keys, settings, packages, and tools match interactive pi. The last workspace is restored from desktop prefs; no temp workspace is created on every start.

Optional isolated launch (temp home + fixture workspace + fake model):

ZENO_ISOLATED=1 pnpm dev

Browser-only chat timeline preview (no Electron), for iterating on session content rendering:

pnpm demo:session-content
# → http://127.0.0.1:4177/session-content-demo.html

Re-run after renderer changes. Do not open the built HTML via file://.

pnpm dev:landing      # http://localhost:5174
pnpm build:landing    # static site → apps/landing/dist
pnpm preview:landing  # serve the production build

pnpm check        # lint + types + format (same as Ubuntu CI)
pnpm check:types  # lint + types only
pnpm fmt          # auto-fix formatting
pnpm test
pnpm build        # all workspace packages (desktop + landing + libs)

pnpm package   # platform installers + electron-updater feeds for this OS

Output: apps/desktop/release/app/ (unsigned in CI — no code-signing certs yet).

Each tagged release publishes only what installers and electron-updater need:

CI fails if any required feed or mac zip is missing (scripts/release-assets.mjs). Blockmaps are kept when present so updates can download only changed ranges.

The product version is derived from the git tag at build time — the Release workflow strips the v prefix from the tag and writes it into apps/desktop/package.json before packaging, so the tag and installer version can never drift. The checked-in apps/desktop/package.json version is only a local-dev fallback; do not bump it manually for a release. Root and packages/* stay at 0.0.0 (private workspace packages).

pnpm version:set 0.1.0   # optional: only for local dev, never for release

git tag v0.1.0
git push origin v0.1.0

Tag must be v + semver (e.g. v0.1.2). CI reads the version from the tag, builds unsigned installers plus the three electron-updater feeds (latest.yml / latest-mac.yml / latest-linux.yml) and mac zip archives, then attaches them to the GitHub Release. Packaged apps check GitHub Releases once on launch (sidebar shows download / restart when an update is ready). Manual workflow_dispatch only uploads Actions artifacts (no Release). Daily CI is Ubuntu-only for lint/types/tests/build; multi-OS packaging stays on Release. Packaging sets CSC_IDENTITY_AUTO_DISCOVERY=false (unsigned).

macOS note: first open of an unsigned download may need xattr -cr /Applications/Zeno.app (Gatekeeper quarantine). Auto-update does not require an Apple Developer ID — Zeno verifies the release zip (sha512 via electron-updater) and replaces the .app itself (same model as Tauri updater + minisign). Optional CSC_LINK / CSC_KEY_PASSWORD still improve Gatekeeper UX and notifications when present.

Contributions are welcome — bug fixes, docs, and small features are the easiest to get in. No CLA required.

The full guide lives in CONTRIBUTING.md. In short: open an issue first, fork and branch off main, keep pnpm check and pnpm test green, and scope each PR to one concern. Use the issue and PR templates when submitting.

React Renderer → Preload → Electron Main → utilityProcess Agent Host → pi SDK

• Renderer has no Node.js access.
• Main supervises the Agent Host but does not execute pi tools or extensions.
• Agent Host uses the public @earendil-works/pi-coding-agent SDK.
• Electron userData is only for desktop chrome prefs — never a second agent config layer.
• A fresh pi home receives no Zeno packages, resources, or custom settings.
• utilityProcess provides crash isolation, not a security sandbox.
• Extension portable UI (select/confirm/status/widgets/…) and TUI-only degraded surface: see packages/agent-runtime/EXTENSION_UI.md.

See LICENSE.

LinuxDo