Repository navigation
Architecture
Parallax is two programs: the desktop app, and plxd, a Rust daemon that runs on each computer that does work. The app, the web client, the iOS app, and plxd tui are all clients of plxd. Everything durable lives in plxd's SQLite database on that computer.
flowchart LR
App["Desktop app<br/>(Electron)"] -- "plxd attach, ssh, plxd dial" --> P["plxd"]
TUI["plxd tui"] --> P
Web["Web client"] -- "HTTPS + WebSocket" --> P
Phone["iOS app"] -- "WebSocket or Connect TCP" --> P
P -- "WebSocket, opened by plxd" --> Relay["Parallax Relay<br/>(Cloudflare Worker)"]
P --> Agents["Agent CLIs and SDK sidecars<br/>in worktrees"]
P --> DB[("plxd.sqlite3")]
| Path | What it holds |
|---|---|
apps/desktop/ |
The Electron app: main process, preload, React renderer, Playwright e2e tests, and the browser preview |
apps/mobile/ |
The iOS app, built with Expo and React Native |
daemon/ |
plxd, the host daemon |
crates/parallax-protocol/ |
The protocol's Rust types, wire samples, and the TypeScript generator |
crates/parallax-store/ |
The SQLite store and its migrations |
sidecar/ |
Node programs plxd runs: the Claude Agent SDK, the Cursor SDK, and the device hub |
relay/ |
Parallax Relay, a Cloudflare Worker with Durable Objects |
packages/plx-connect/ |
npx plx-connect, which installs Parallax on your computers and turns on Parallax Connect |
packages/clerk-verify/ |
Checks a Parallax account token against Clerk's JWKS, used by the relay |
scripts/ci/ |
The scripts CI runs, which also run locally (scripts/ci/README.md) |
scripts/bench/ |
The load harness and its budgets |
scripts/ (top level) |
The install scripts the README's commands fetch |
packaging/aur/ |
The PKGBUILD for the AUR's parallax-nightly-bin
|
design/ |
The app icon's sources |
docs/ |
PLAN.md, the decision records, and README images |
pr-media/, pr-visuals/
|
Images embedded in past pull requests |
.github/ |
Workflows, the PR template, issue forms, and Dependabot |
.cargo/ |
Cargo settings, including which SQLite extensions the bundled build leaves out |
apps/desktop/ is Electron, React, and TypeScript, built with Vite+ (vp) and pnpm (0022).
| Part | Path | Role |
|---|---|---|
| Main | src/main/ |
Owns the connections to hosts. connection.ts runs one plxd attach (or ssh, or plxd dial) child per host and speaks JSON-RPC over its stdio, with heartbeats and reconnects. hosts.ts keeps the list of hosts. plxd.ts finds the local plxd. |
| Preload | src/preload/ |
Exposes window.parallax to the renderer. bridge.ts is the typed contract and imports nothing from Node or Electron. |
| Renderer | src/renderer/ |
The React UI. It runs sandboxed with context isolation and reaches plxd only through window.parallax. |
| Protocol types | src/protocol/generated/protocol.ts |
Generated from parallax-protocol and committed. |
The renderer also builds as the web client. web.html loads the same UI with webBridge.ts in place of the preload, which talks to plxd over a WebSocket.
The local plxd is found in this order: PLXD_PATH, then the binary bundled in a packaged app or target/debug/plxd in a dev checkout, then PATH.
plxd serve is one process per user per computer. It listens on plxd.sock in the data folder (~/.parallax by default), or a per-user named pipe on Windows. The subcommands are in daemon/README.md.
Modules in daemon/src/ worth knowing:
| Module | What it does |
|---|---|
server/ |
Accepts connections on the socket or pipe, the Connect listener, and the HTTPS listener. connection.rs reads requests and delivers events. |
attach.rs, transport.rs
|
plxd attach: reaches the socket or pipe, starting serve if needed, and copies stdio to it byte for byte |
methods/ |
The JSON-RPC method handlers, one file per area |
orchestrator.rs |
Commands and their effects (see below) |
store.rs |
The single SQLite writer thread and the read-only reader thread |
event_log.rs |
The event log, its in-memory replay window, and pruning |
graph.rs |
The thread graph: runs, attempts, execution nodes, and runtime requests, folded from events |
agents/ |
The run actor, which starts a thread's CLI, streams its output, queues messages, and commits. Also the coordinator, wake-ups, and placement. |
backend/ |
One adapter per agent: claude, codex, cursor_sdk, opencode, acp, and fake for tests |
checkpoints.rs |
Per-turn checkpoints, diffs, and revert |
worktree/ |
The git worktrees threads run in |
providers.rs |
Provider instances, stored in providers.json
|
mcp/, mcp.rs
|
plxd mcp, each thread's Parallax tools as an MCP server on stdio |
schedules.rs, pr_watch.rs, delegation.rs
|
Triggers and delegated tasks |
terminals.rs |
Terminals plxd owns, so they outlive the app |
remote.rs, tailnet.rs, relay.rs, peer.rs
|
Remote access: LAN pairing, Parallax Connect, the relay, and plxd's own client of another plxd
|
tui.rs, tui/
|
plxd tui, the terminal client |
windows.rs |
Every Win32 call, and the only module allowed unsafe
|
-
parallax-protocolis the single source of truth for the protocol: newline-delimited JSON-RPC 2.0, at most 8 MiB per line, with every method and event typed. Changes must be additive. The samples insamples/v1/must keep decoding, andcargo testfails if the committed TypeScript inapps/desktop/src/protocol/generated/is stale. Regenerate it withcargo run -p parallax-protocol --bin generate-typescript. -
parallax-storeowns the SQLite connection and its versioned migrations. It stores projects, threads, runs, the event log, receipts, effects, the thread graph, accounts, inboxes, schedules, and pull request watches. API keys live in the OS keystore, never in this database.
Every client speaks the same JSON-RPC protocol (0007). Only the pipe under it differs.
| Route | Clients | How |
|---|---|---|
| Local | Desktop app |
plxd attach bridges stdio to the socket or named pipe (0010) |
| SSH | Desktop app |
ssh <host> plxd attach, with your own ssh config and keys |
| Parallax Connect | Desktop app (plxd dial <ip>), iOS app |
Newline-delimited JSON over TCP port 7340 on the host's Tailscale IPv4. plxd admits only untagged nodes of the same Tailscale user (0056) |
| LAN | Web client, iOS app, desktop app (plxd dial --remote) |
HTTPS on port 7341 with a self-signed certificate the client pins at pairing. GET /ws is a WebSocket with one JSON-RPC message per frame (0065) |
| Relay | Desktop app, over a relay:<hostId> route |
plxd keeps a WebSocket open to the relay. The client's TLS runs through it to plxd's HTTPS listener, so the relay sees only ciphertext (0068) |
Remote listeners run only while their host setting is on. See Hosts and Remote Access.
One thread in store.rs owns the only write connection. Each job is one BEGIN IMMEDIATE transaction. Inside it, Tx::stage gives each event the next daemon-wide seq, inserts its row, and folds thread events into the thread graph. Events are published to subscribers only after the transaction commits, so a row and its event are stored together or not at all (0052).
The orchestrator handles thread changes as commands (0059):
- A command has an id (the request's
commandId, or a new one) and runs in its thread's lane, so one thread's commands run in order while other threads run alongside. - One transaction reads the thread's rows, decides with no I/O, applies the decision, stages events, writes a receipt, and enqueues effects.
- A repeated command id returns the stored outcome without applying twice.
- The effect worker runs effects after their command commits: one at a time per thread, at most 4 at once, retrying with backoff up to 5 attempts. After a crash, replay-safe effects go back to pending and the rest are cancelled.
Receipts and settled effects are kept for seven days. Clients subscribe with orchestration/subscribeShell (every project's and the host's events) and orchestration/subscribeThread (one thread). Each answers with a snapshot at a seq and then streams the events after it. A resume with afterSeq replays the gap when it is at most 128 events and 1 MiB and still in the window, and sends a fresh snapshot otherwise.
A thread's CLI or SDK session stays open after its turn, so a follow-up goes to the live process (0060). It is released after 30 minutes idle, deferred up to 4 hours while tool calls, background commands, or subagents are open. It is released at once on archive, settle, Accept, or a failed turn, and the least recently used goes first once more than 5 sessions on the host sit idle. Every Codex thread on one login shares one codex app-server.
Claude runs through the Claude Agent SDK and Cursor through the Cursor SDK, each in a Node sidecar plxd starts (0061, 0053). plxd embeds the sidecar files and installs the pinned SDK into <data>/tools/ with npm ci on first use. The device hub sidecar streams simulators and emulators to the app's Device panel. See Providers.
Each finished turn (completed, interrupted, or cancelled) is captured as the git ref refs/parallax/checkpoints/<thread>/<ordinal>, where ordinal 0 is the thread's start (0062). Capture runs as a checkpoint.capture effect enqueued in the transaction that ends the run. Diffs between checkpoints ignore whitespace by default and stop at 10 MiB. A revert rewinds the provider's conversation, restores the files, and deletes refs above the target. A coordinator writes nothing and gets no checkpoints.
The event log lives in plxd.sqlite3 with the store (0016).
- A run's events stay as long as its run row does. A finished turn's output batches are rewritten as one row once they leave the in-memory window.
- Host and project events with no thread are pruned to the newest 10,000.
- The in-memory replay window holds the newest 10,000 events or 64 MiB, whichever is smaller. A subscriber that falls behind it gets
events/resync. - Subscribers have no queues of their own. Each subscription is a cursor over the log, so a slow subscriber never blocks a writer.
-
relay/routes requests insrc/index.ts, keeps one Durable Object per host (src/host.ts) and per user (src/user.ts), and checks Clerk tokens withpackages/clerk-verify. It also gives webhooks a public URL and keeps each user's push devices. The APNs send insrc/push.tsis still a stub, and no workflow deploys the relay. -
packages/plx-connect/installs Parallax orplxdalone on a computer, over SSH or locally, and turns Connect on. The app bundles it for Add computer. -
apps/mobile/shares the desktop renderer's client code: the generated protocol types andWebHost. Itsmodules/pinned-tlsnative module provides the pinned HTTPS and WebSocket connections and Connect's TCP. See Mobile.
Start
Using Parallax
Your computers
Maintenance
Contributing