Development and architecture

Source setup, application layers, build targets, tests, and packaging.

The application repository contains the desktop app, renderer, backend, examples, and tests. This page describes that repository, not the marketing website.

Prerequisites and installation#

Use Node 24 or newer as required by the repository and the pnpm version pinned in package.json.

git clone https://github.com/soverius-ai/pi-kit.git
cd pi-kit
corepack enable
pnpm install --frozen-lockfile

The application uses pnpm with a hoisted node_modules layout. Do not add a package-lock.json to that repository. Git is required for checkout/worktree operations; platform packaging has additional requirements.

Run#

# Renderer, backend, and Electron
pnpm run dev

# Renderer and backend without Electron
pnpm run dev:web

Web development normally serves the renderer at http://localhost:4200 and the backend at 127.0.0.1:4300. Desktop mode starts its backend and manages the connection/authentication.

Use desktop mode for native Artifacts features. The web renderer does not include the Electron project browser.

Repository structure#

Layer	Responsibility
Angular renderer	Chat, composer, panels, Settings, and UI state.
CopilotKit / AG-UI	Agent event streaming, tool UI, and interaction contracts.
NestJS backend	Sessions, models, persistence, trust, worktrees, and host services.
pi runtime	Model calls, tools, extensions, resources, and session files.
Electron	Desktop window, native integration, and project browser views.

Apps live in apps/{desktop,renderer,backend,secret-cli}. Domain libraries are under libs/<domain>/. Shared schemas and a generated typed API connect the renderer and backend.

See structure.md for library boundaries and the ADRs for architectural decisions.

Checks and tests#

pnpm run check
pnpm run e2e
CHECK_E2E=1 pnpm run check

The check command runs stylesheet sync verification, builds, lint, and unit tests. E2E tests use scratch pi folders and projects. Some require a local inference server; E2E_MODEL_URL changes its address.

For native browser tests, build the required application targets, then run:

node --test e2e/browser.desktop.e2e.mjs

Run the relevant Nx project targets during development. Native screenshots need pixel-level verification in Electron; renderer-only screenshots can omit a child browser view.

Screenshot harness#

node scripts/screenshots.mjs --list
node scripts/screenshots.mjs --serve --set phase-11b --out tmp/screenshots/phase-11b

Install Playwright's test browser using the repository instructions. Scenes can depend on preceding states in a set. Older scenes may need selector updates after interface changes.

This harness runs dev:web. Native Artifacts capture requires Electron-specific tooling.

Extensions and host integration#

Use the examples for pi tools, A2UI, and MCP Apps. The plugin contract documents host events for transcripts, outcomes, attendant calls, and learning.

Normal pi extensions use pi's API. Host-dependent packages require pi-kit event handlers and may not provide the same functionality in a standalone CLI session.

Release builds#

pnpm run release
pnpm run release --only mac

Output is written to dist/release/. Follow the repository's smoke-test instructions for the generated package. Signing/notarization uses platform credentials supplied outside source control. Package generation, launch testing, and native-feature testing are separate checks.