How ayuayue/pideck works
Purpose and runtime model
PiDeck is a local Electron desktop workbench for managing multiple pi coding-agent sessions across project directories. It is not an agent implementation: each Agent tab owns an isolated pi --mode rpc subprocess and project cwd. Electron main owns privileged operations; React renders the workspace; preload exposes a constrained IPC surface.
Entry points: src/main/index.ts, src/preload/index.ts, src/renderer/src/main.tsx, and src/renderer/src/App.tsx.
Process, RPC, and agent lifecycle
The main process locates the externally installed pi CLI, starts/stops RPC subprocesses, translates RPC events into application state, gates streaming, and preserves per-agent lifecycle state. This is the core boundary between PiDeck and the external pi runtime.
Grounding: src/main/pi/AgentManager.ts, src/main/pi/PiProcess.ts, src/main/pi/PiRpcClient.ts.
Desktop IPC boundary
Renderer code does not directly access Node, filesystem, subprocesses, or Electron APIs. Shared IPC channel names/types define the contract; preload publishes the desktop API; main handlers route calls to domain services. The renderer has a browser-preview fallback when this API is absent, but real agent/project behavior requires Electron.
Grounding: src/shared/ipc.ts, src/shared/types.ts, src/preload/index.ts.
Workspace, sessions, and local resources
Projects are persisted independently from active agents. Main-process services manage project records, scan/import native pi and external Codex/Claude/OpenCode sessions, and operate on project files, Git worktrees/branches, prompts, skills, and extensions. These services are the persistence and local-machine boundary.
Grounding: src/main/projects/ProjectStore.ts, src/main/sessions/SessionScanner.ts, src/main/fs/FileSystemService.ts.
Interactive desktop workspace
The React shell coordinates project/agent selection, streamed chat timeline, composer behavior, files/history/configuration drawers, Git and browser panels, and session-specific terminal docking. It consumes the preload API and shared data contracts rather than spawning agents itself.
Grounding: src/renderer/src/App.tsx, src/renderer/src/components/app/AppParts.tsx, src/renderer/src/components/app/RichInput.tsx.
Native integrations and optional surfaces
Electron main manages pty-backed terminals, native editor detection, desktop proxy settings, WSL path/environment handling, local LAN web serving, tray/window behavior, and pet overlay windows. Git is accessed locally; pi is an external executable; optional Feishu integration bridges remote card interactions to agent/session operations.
Grounding: src/main/terminal/TerminalSessionManager.ts, src/main/wsl/WslEnvironment.ts, src/main/feishu/FeishuBridge.ts.
Configuration, extensibility, and external services
Configuration management reads/writes pi configuration and supports provider/model testing. Skills and extensions are managed at global/project scope, including bundled extensions. The application can query GitHub Releases for updates, sends opt-out anonymous heartbeat telemetry, and supports prompt/skill store discovery; model/provider credentials remain configured through pi-facing settings.
Grounding: src/main/config/ConfigManager.ts, src/main/extensions/ExtensionManager.ts, src/main/telemetry/TelemetryService.ts.
Main entry points: index.ts Main entry · App.tsx Workspace shell · PiProcess.ts Pi process · AgentManager.ts Agent manager
Components 23
Renderer workspace
- React entry
src/renderer/src/main.tsx - Workspace shell · Coordinates selected projects, agents, panels, and streamed chat.
src/renderer/src/App.tsx - Workspace UI · Provides app panels and rich composer behavior.
src/renderer/src/components/app/AppParts.tsx - Rich composer
src/renderer/src/components/app/RichInput.tsx
Desktop IPC
- IPC contract · Defines typed renderer-to-main operations and events.
src/shared/ipc.ts - Shared data types
src/shared/types.ts - Preload API · Exposes the constrained desktop API to the renderer.
src/preload/index.ts
Electron main
- Main entry · Owns privileged IPC handlers and desktop lifecycle.
src/main/index.ts - Agent manager · Maintains isolated agent state and gates streamed RPC events.
src/main/pi/AgentManager.ts - Pi process · Locates and starts or stops pi CLI processes per project cwd.
src/main/pi/PiProcess.ts - Pi RPC client · Translates pi RPC traffic into application events.
src/main/pi/PiRpcClient.ts - Project store · Persists projects independently of active agents.
src/main/projects/ProjectStore.ts - Session scanner · Scans native pi and external coding-agent sessions.
src/main/sessions/SessionScanner.ts - Local resource service · Operates on project files, worktrees, branches, prompts, skills, and extensions.
src/main/fs/FileSystemService.ts - Terminal manager · Hosts session-specific terminal docks.
src/main/terminal/TerminalSessionManager.ts - Pi configuration · Reads pi settings and tests providers and models.
src/main/config/ConfigManager.ts - Extensions and skills · Manages global, project, and bundled extensions.
src/main/extensions/ExtensionManager.ts - WSL environment · Adapts paths and environment for WSL.
src/main/wsl/WslEnvironment.ts - Feishu bridge · Maps remote card actions to agent and session operations.
src/main/feishu/FeishuBridge.ts - Telemetry service · Sends opt-out anonymous heartbeat telemetry.
src/main/telemetry/TelemetryService.ts
Local and remote integrations
- pi CLI · Externally installed RPC coding-agent executable.
- Projects and Git · Project directories, native sessions, Git repositories, and credentials remain local.
- Remote services · GitHub releases, stores, telemetry endpoint, and Feishu.
Connections 27
- React entry → Workspace shell: mounts
- Workspace shell → Workspace UI: composes
- Workspace UI → Rich composer: includes
- Workspace shell → Preload API: uses desktop API
- Preload API → IPC contract: implements
- Preload API → Main entry: invokes and receives events
- Shared data types → Workspace shell: models UI state
- Shared data types → Main entry: models IPC payloads
- Main entry → Agent manager: routes agent operations
- Main entry → Project store: routes project operations
- Main entry → Session scanner: routes session imports
- Main entry → Local resource service: routes local resource operations
- Main entry → Terminal manager: routes terminal operations
- Main entry → Pi configuration: routes settings operations
- Main entry → Extensions and skills: routes extensibility operations
- Agent manager → Pi process: starts and stops
- Pi process → pi CLI: launches per-agent RPC process
- Pi process → Pi RPC client: connects RPC transport
- Pi RPC client → Agent manager: streams RPC events
- Project store → Projects and Git: persists project records
- Session scanner → Projects and Git: scans sessions
- Local resource service → Projects and Git: manages files and Git
- WSL environment → Pi process: adapts WSL execution
- Feishu bridge → Agent manager: forwards card actions
- Pi configuration → pi CLI: configures providers
- Telemetry service → Remote services: sends opt-out heartbeat
- Main entry → Remote services: checks updates and discovery