Repository navigation
Building from Source
How to build plxd and the app, run them in development, and run the same checks CI runs. For how the pieces fit together, see Architecture.
| Tool | Version | Notes |
|---|---|---|
| Rust | 1.98.1, pinned in rust-toolchain.toml
|
Install rustup, then run rustup toolchain install in the repo to get the pinned toolchain with rustfmt and clippy. |
| C compiler | Any | The bundled SQLite and ring need one. On Linux, Debian's build-essential or similar. On Windows, the Visual Studio C++ build tools, plus clang on Windows arm64. |
| Node | 24, pinned in apps/desktop/.node-version
|
Used by the app, the relay, the mobile app, and the packages |
| pnpm | 11.10.0, pinned in each package.json
|
Run corepack enable once. Run pnpm inside a package folder, such as apps/desktop, where corepack finds the pinned version. |
To run agents, the host also needs Node 22.16 or newer with npm, since plxd installs the Claude Agent SDK and Cursor SDK sidecars with npm ci. Linux workers need bwrap and socat (see daemon/README.md).
From the repo root:
cargo build -p plxdA dev checkout of the app runs target/debug/plxd, so build the debug binary for pnpm dev. For a release binary, use cargo build --release -p plxd.
plxd has two Cargo features:
-
fake-backend: a scripted agent for tests, which the e2e tests and the load harness use. Release builds refuse it. -
sandbox-tools: embeds staticbwrapandsocaton Linux, built byscripts/ci/build-sandbox-tools.
cargo build -p plxd
cd apps/desktop
pnpm install
pnpm devpnpm dev serves the renderer with hot reload, rebuilds the main process and preload on change, and restarts Electron when they change. Quitting the app or pressing Ctrl-C stops everything. Extra arguments go to Electron, such as pnpm dev --remote-debugging-port=9222.
The app finds plxd in this order: PLXD_PATH, then target/debug/plxd, then PATH. Set PLXD_DATA_DIR to give plxd a data folder other than ~/.parallax.
The preview serves the real renderer in a plain browser, with no Electron and no plxd. From apps/desktop:
pnpm exec vp dev -c preview/vite.config.tsIt runs at http://localhost:5199/. preview/mockBridge.ts answers every plxd method the renderer calls from the fixtures in preview/fixtures.ts, and writes change in-memory state until the page reloads. A URL hash opens a view, such as #thread=Rework the updater or #onboarding. Keep the fixtures in step with what plxd reports. Details are in apps/desktop/preview/README.md.
| Component | Folder | Commands |
|---|---|---|
Rust (plxd and crates) |
repo root | scripts/ci/check-rust |
| Desktop app | apps/desktop |
pnpm check (format, lint, type-check), pnpm test (Vitest), pnpm build. pnpm fmt fixes formatting. |
| App end to end | repo root | scripts/ci/e2e-app |
| Relay | relay |
pnpm install --frozen-lockfile, pnpm check, pnpm test (Miniflare) |
Relay with plxd
|
relay |
node scripts/e2e.mjs runs plxd's relay test against the Worker under wrangler dev
|
| Mobile | apps/mobile |
scripts/ci/check-mobile, or pnpm check and pnpm test
|
| plx-connect | packages/plx-connect |
npm ci, npm run check, npm test
|
| clerk-verify | packages/clerk-verify |
npm ci, npm run check, npm test
|
| Claude sidecar | sidecar/claude |
npm ci, then npm test. It runs against target/debug/plxd. |
| Cursor sidecar | sidecar/cursor |
npm test |
Every script in scripts/ci/ finds the repo root itself, so it runs from any folder. scripts/ci/README.md describes each one.
scripts/ci/check-rust runs, with --locked:
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --lockedThe tests include two protocol checks. Every sample in crates/parallax-protocol/samples/v1/ must still decode, so a change that isn't additive fails. The committed TypeScript types must match the Rust types. After changing a protocol type, regenerate them and commit the result:
cargo run -p parallax-protocol --bin generate-typescriptSome tests skip unless their dependency is set up:
- The Claude Code sandbox tests need
PLX_SANDBOX_CLAUDEset to a Claude Code binary, and on Linux,bubblewrapandsocat. -
plxd attachover a realssh localhostruns throughscripts/ci/ssh-localhostandscripts/ci/check-ssh-attach. daemon/README.md has the steps to run it by hand.
scripts/ci/e2e-app builds plxd with --features fake-backend (unless PLXD_PATH names one), builds the app, and runs Playwright from apps/desktop/e2e. The tests launch the built app against that plxd in a temporary data folder, with PLXD_FAKE_BACKEND naming the script the fake agent plays. On Linux with no display it runs under xvfb-run.
apps/mobile is an Expo app. pnpm start runs Expo's dev server for a development build, and pnpm ios builds and runs the app, which needs Xcode. CI runs only the type check, the unit tests, and expo export --platform ios, which fails on an import the phone can't resolve.
scripts/bench/load.py streams fake-backend threads through plxd at once and measures delivery latency, bytes and events per subscription, and plxd's CPU and memory:
cargo build --profile bench -p plxd --features fake-backend
scripts/bench/load.py target/release/plxd --threads 30 --out load.json
scripts/ci/check-load load.json unfiltered--filtered and --orchestration change how the harness subscribes. Check each result against the budget set of the same name in scripts/bench/budgets.json (unfiltered, filtered, or orchestration). check-load fails on any value outside its budget, any missing metric, or any resync.
scripts/bench/threads.py times real thread starts against a signed-in claude CLI. CI doesn't run it.
.github/workflows/ci.yml runs on every pull request, and only on pull requests.
| Job | Runs on | What it does |
|---|---|---|
changes |
Linux | Decides whether the PR touches Rust or its inputs |
rust |
macOS arm64, Linux x64 and arm64, Windows x64 and arm64 |
scripts/ci/check-rust, then plxd attach over ssh. On Linux, the Claude sidecar test. On Linux x64, plxd through the relay under wrangler dev. Skipped when no Rust changed. |
plxd |
macOS, Linux, Windows | Builds plxd with fake-backend for the e2e and load jobs |
relay |
Linux | Type-checks the Worker and runs its tests in Miniflare |
app |
macOS, Linux, Windows |
scripts/ci/check-app (the app, plx-connect, and clerk-verify), then scripts/ci/launch-app
|
mobile |
Linux | scripts/ci/check-mobile |
e2e |
macOS, Linux, Windows |
scripts/ci/e2e-app against that OS's plxd build |
load |
Linux |
load.py with 30 threads in all three modes, each checked against its budget |
actionlint |
Linux | Lints the workflows, tests the release plan, and checks that ci needs every other job |
ci |
Linux | Passes when every other job succeeded or was skipped. It is the only required check. |
rust-cache.yml saves the Rust caches on each push to develop, since a PR can't read another PR's caches. Releases are built by release.yml (see Release Channels and Updates).
Read CONTRIBUTING.md before you open a pull request. In short:
- A new feature or a change in behavior needs an agreed Ideas discussion first. A small, obvious bug fix can skip the issue.
- One problem per PR, against
develop, using the PR template. - The title is a Conventional Commit, since PRs are squash-merged.
- Show evidence that it works. UI changes need before and after screenshots.
- CI runs on an outside PR only after a maintainer approves it.
Security issues go through SECURITY.md, not public issues.
Start
Using Parallax
Your computers
Maintenance
Contributing