# vladik9/pi-desktop architecture

> Architecture diagram of the GitHub repository vladik9/pi-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vladik9/pi-desktop
- Repository: https://github.com/vladik9/pi-desktop

## Overview

PI-Desktop is a local-first desktop workspace for projects, AI-agent sessions, and extensible workflows. The main workflow is to submit a task in the workspace, have an agent execute it with permission controls, then inspect its transcript and work products. The architecture also supports model/provider configuration, plugins, delegation, remote hosts, voice, and configuration sync. The README documents these product capabilities; sampled source confirms selected runtime internals, but does not expose every UI-to-host dispatch, so undocumented connections are omitted.

Main entry points: [`crates/host-core/src/main.rs`](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/main.rs) (Host core), [`packages/host-runtime/src/runtime-service.ts`](https://github.com/vladik9/pi-desktop/blob/main/packages/host-runtime/src/runtime-service.ts) (Agent runtime), [`packages/agent-host/src/agent-host.ts`](https://github.com/vladik9/pi-desktop/blob/main/packages/agent-host/src/agent-host.ts) (Agent host), [`apps/desktop/src/features/app/AppShell.tsx`](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/app/AppShell.tsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop workspace"]
  node_workspace_ui["Workspace UI<br/>[AppShell.tsx]"]
  node_chat["Chat and composer<br/>[ChatSurface.tsx]"]
  node_transcript["Transcript and review<br/>[ChatTranscript.tsx]"]
  node_desktop_api["Desktop API<br/>[api.ts]"]
  node_ipc["Main IPC<br/>[register.ts]"]
end

subgraph group_agent["Agent execution"]
  node_host_core["Host core<br/>[main.rs]"]
  node_runtime["Agent runtime<br/>[runtime-service.ts]"]
  node_agent_host["Agent host<br/>[agent-host.ts]"]
  node_pi_host["PI host app<br/>[app.ts]"]
  node_plans["Plans and approvals<br/>[repository.rs]"]
  node_sessions["Worker sessions"]
end

subgraph group_extensions["Extensions and integrations"]
  node_plugins["Plugin runtime<br/>[plugin-runtime.ts]"]
  node_plugin_ui["Plugin workspace UI"]
end

subgraph group_platform["Platform services"]
  node_providers["Model providers<br/>[repository.rs]"]
  node_voice["Voice runtime"]
  node_remote["Remote hosts"]
  node_config_sync["Configuration sync<br/>[engine.rs]"]
  node_schedule["Scheduled runs"]
  node_local_state[("Local workspace state<br/>[state.rs]")]
end

node_user(("User"))

node_user -->|"uses"| node_workspace_ui
node_workspace_ui -->|"opens chat"| node_chat
node_chat -.->|"submits task"| node_desktop_api
node_desktop_api -.->|"invokes IPC"| node_ipc
node_ipc -.->|"dispatches request"| node_host_core
node_host_core -.->|"coordinates agent"| node_runtime
node_runtime -->|"emits events"| node_agent_host
node_agent_host -->|"ingests events"| node_pi_host
node_host_core -->|"opens state"| node_local_state
node_runtime -.->|"returns results"| node_transcript
node_host_core -->|"supports planning"| node_plans
node_host_core -->|"coordinates workers"| node_sessions
node_user -->|"browses plugins"| node_plugin_ui
node_plugin_ui -.->|"installs extensions"| node_plugins
node_plugins -->|"extends agent"| node_agent_host
node_user -->|"configures models"| node_providers
node_user -->|"speaks to agent"| node_voice
node_user -->|"connects host"| node_remote
node_user -->|"syncs settings"| node_config_sync
node_user -->|"schedules work"| node_schedule

click node_workspace_ui "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/app/AppShell.tsx"
click node_chat "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/components/ChatSurface.tsx"
click node_transcript "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/chat/transcript/ChatTranscript.tsx"
click node_desktop_api "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/lib/api.ts"
click node_ipc "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/ipc/register.ts"
click node_host_core "https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/main.rs"
click node_runtime "https://github.com/vladik9/pi-desktop/blob/main/packages/host-runtime/src/runtime-service.ts"
click node_agent_host "https://github.com/vladik9/pi-desktop/blob/main/packages/agent-host/src/agent-host.ts"
click node_pi_host "https://github.com/vladik9/pi-desktop/blob/main/apps/pi-host/src/app.ts"
click node_plans "https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/plans/repository.rs"
click node_sessions "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/services/session-collaboration.ts"
click node_plugins "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/plugin-runtime.ts"
click node_plugin_ui "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/plugins/MarketplacePanel.tsx"
click node_providers "https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/providers/repository.rs"
click node_voice "https://github.com/vladik9/pi-desktop/blob/main/packages/voice-runtime/src/voice-controller.ts"
click node_remote "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/remote/remote-host-connection.ts"
click node_config_sync "https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/config_sync/engine.rs"
click node_schedule "https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/runtime/scheduled-runner.ts"
click node_local_state "https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/state.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace_ui,node_chat,node_transcript,node_desktop_api,node_ipc,node_user toneBlue
class node_host_core,node_runtime,node_agent_host,node_pi_host,node_plans,node_sessions toneAmber
class node_plugins,node_plugin_ui toneMint
class node_providers,node_voice,node_remote,node_config_sync,node_schedule,node_local_state toneRose
```

## Components

### Desktop workspace

- [Workspace UI](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/app/AppShell.tsx): `apps/desktop/src/features/app/AppShell.tsx`
- [Chat and composer](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/components/ChatSurface.tsx): `apps/desktop/src/components/ChatSurface.tsx`
- [Transcript and review](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/chat/transcript/ChatTranscript.tsx): `apps/desktop/src/features/chat/transcript/ChatTranscript.tsx`
- [Desktop API](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/lib/api.ts): `apps/desktop/src/lib/api.ts`
- [Main IPC](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/ipc/register.ts): `apps/desktop/electron/main/ipc/register.ts`

### Agent execution

- [Host core](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/main.rs): `crates/host-core/src/main.rs`
- [Agent runtime](https://github.com/vladik9/pi-desktop/blob/main/packages/host-runtime/src/runtime-service.ts): `packages/host-runtime/src/runtime-service.ts`
- [Agent host](https://github.com/vladik9/pi-desktop/blob/main/packages/agent-host/src/agent-host.ts): `packages/agent-host/src/agent-host.ts`
- [PI host app](https://github.com/vladik9/pi-desktop/blob/main/apps/pi-host/src/app.ts): `apps/pi-host/src/app.ts`
- [Plans and approvals](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/plans/repository.rs): `crates/host-core/src/plans/repository.rs`
- [Worker sessions](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/services/session-collaboration.ts): `apps/desktop/electron/main/services/session-collaboration.ts`

### Extensions and integrations

- [Plugin runtime](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/plugin-runtime.ts): `apps/desktop/electron/main/plugin-runtime.ts`
- [Plugin workspace UI](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/src/features/plugins/MarketplacePanel.tsx): `apps/desktop/src/features/plugins/MarketplacePanel.tsx`

### Platform services

- [Model providers](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/providers/repository.rs): `crates/host-core/src/providers/repository.rs`
- [Voice runtime](https://github.com/vladik9/pi-desktop/blob/main/packages/voice-runtime/src/voice-controller.ts): `packages/voice-runtime/src/voice-controller.ts`
- [Remote hosts](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/remote/remote-host-connection.ts): `apps/desktop/electron/main/remote/remote-host-connection.ts`
- [Configuration sync](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/config_sync/engine.rs): `crates/host-core/src/config_sync/engine.rs`
- [Scheduled runs](https://github.com/vladik9/pi-desktop/blob/main/apps/desktop/electron/main/runtime/scheduled-runner.ts): `apps/desktop/electron/main/runtime/scheduled-runner.ts`
- [Local workspace state](https://github.com/vladik9/pi-desktop/blob/main/crates/host-core/src/state.rs): `crates/host-core/src/state.rs`

### Other components

- **User**

## Connections

- User → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → Chat and composer: opens chat (evidence: `README.md`)
- Chat and composer → Desktop API: submits task
- Desktop API → Main IPC: invokes IPC
- Main IPC → Host core: dispatches request
- Host core → Agent runtime: coordinates agent
- Agent runtime → Agent host: emits events
- Agent host → PI host app: ingests events (evidence: `apps/pi-host/src/app.ts`)
- Host core → Local workspace state: opens state (evidence: `crates/host-core/src/main.rs`)
- Agent runtime → Transcript and review: returns results
- Host core → Plans and approvals: supports planning (evidence: `README.md`)
- Host core → Worker sessions: coordinates workers (evidence: `README.md`)
- User → Plugin workspace UI: browses plugins (evidence: `README.md`)
- Plugin workspace UI → Plugin runtime: installs extensions
- Plugin runtime → Agent host: extends agent (evidence: `README.md`)
- User → Model providers: configures models (evidence: `README.md`)
- User → Voice runtime: speaks to agent (evidence: `README.md`)
- User → Remote hosts: connects host (evidence: `README.md`)
- User → Configuration sync: syncs settings (evidence: `README.md`)
- User → Scheduled runs: schedules work (evidence: `README.md`)