# dlyzzt/pi-desktop architecture

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

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

## Overview

Pi Agent Desktop is a local-first Electron and React workbench for the Pi Coding Agent. The main workflow runs from chat and session controls in the renderer, through desktop IPC and the supervised Agent Host, into Pi session execution and model services; streamed responses and execution history return to the workspace. Separate branches provide project files, browser automation, MCP and messaging integrations, and development-tool/process management. Edges use README statements or the sampled source index/excerpts; many feature internals were not sampled, so undocumented links are omitted.

Main entry points: [`src/agent-host/rpc-manager.ts`](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/rpc-manager.ts) (Agent Host RPC), [`src/renderer/App.tsx`](https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/App.tsx) (Chat workspace), [`src/renderer/hooks/useAgentSession.ts`](https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/hooks/useAgentSession.ts) (Session controls), [`src/main/ipc.ts`](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/ipc.ts) (Desktop IPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_renderer["Chat workspace<br/>[App.tsx]"]
  node_session_ui["Session controls<br/>[useAgentSession.ts]"]
  node_desktop_ipc["Desktop IPC<br/>[ipc.ts]"]
  node_host_supervisor["Host supervisor<br/>[host-manager.ts]"]
end

subgraph group_agent["Agent sessions"]
  node_agent_host["Agent Host RPC<br/>[rpc-manager.ts]"]
  node_session_runtime["Session services"]
  node_session_history[("Session history<br/>[session-reader.ts]")]
  node_model_config["Models and routing<br/>[azure-upgrade.ts]"]
end

subgraph group_integrations["Agent integrations"]
  node_mcp["MCP services<br/>[service.ts]"]
  node_channels["Message channels<br/>[channel-manager.ts]"]
  node_herdr["Herdr runtime<br/>[runtime-manager.ts]"]
  node_skills_plugins["Skills and plugins<br/>[skills-service.ts]"]
end

subgraph group_workspace["Workspace capabilities"]
  node_browser_ui["Browser interface<br/>[BrowserDock.tsx]"]
  node_browser_runtime["Browser automation"]
  node_project_files["Project files<br/>[files.ts]"]
end

subgraph group_operations["Runtime operations"]
  node_toolchains["Toolchain manager<br/>[manager.ts]"]
  node_managed_process["Managed processes<br/>[service.ts]"]
  node_updates["Desktop updates<br/>[update-manager.ts]"]
end

node_user(("User"))
node_update_service["Update service"]

node_user -->|"uses"| node_renderer
node_renderer -->|"controls sessions"| node_session_ui
node_session_ui -->|"sends commands"| node_desktop_ipc
node_desktop_ipc -->|"routes IPC"| node_host_supervisor
node_host_supervisor -->|"supervises"| node_agent_host
node_agent_host -->|"creates services"| node_session_runtime
node_agent_host -->|"reads sessions"| node_session_history
node_session_runtime -->|"configures models"| node_model_config
node_agent_host -->|"provides MCP tools"| node_mcp
node_agent_host -->|"handles channel turns"| node_channels
node_user -->|"controls browser"| node_browser_ui
node_browser_ui -->|"requests actions"| node_browser_runtime
node_agent_host -->|"invokes browser tools"| node_browser_runtime
node_user -->|"works with files"| node_project_files
node_agent_host -->|"resolves tools"| node_toolchains
node_agent_host -->|"manages processes"| node_managed_process
node_user -->|"controls fleet"| node_herdr
node_agent_host -->|"connects runtime"| node_herdr
node_agent_host -->|"loads extensions"| node_skills_plugins
node_user -->|"requests updates"| node_updates
node_updates -->|"checks releases"| node_update_service

click node_renderer "https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/App.tsx"
click node_session_ui "https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/hooks/useAgentSession.ts"
click node_desktop_ipc "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/ipc.ts"
click node_host_supervisor "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/host-manager.ts"
click node_agent_host "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/rpc-manager.ts"
click node_session_runtime "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/desktop-session-services.ts"
click node_session_history "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/session-reader.ts"
click node_model_config "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/azure-upgrade.ts"
click node_mcp "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/mcp/service.ts"
click node_channels "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/channels/channel-manager.ts"
click node_browser_ui "https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/components/browser/BrowserDock.tsx"
click node_browser_runtime "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/browser/browser-tab-manager.ts"
click node_project_files "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/handlers/files.ts"
click node_toolchains "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/toolchains/manager.ts"
click node_managed_process "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/managed-process/service.ts"
click node_herdr "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/herdr/runtime-manager.ts"
click node_skills_plugins "https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/skills-service.ts"
click node_updates "https://github.com/dlyzzt/pi-desktop/blob/main/src/main/update-manager.ts"

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_renderer,node_session_ui,node_desktop_ipc,node_host_supervisor,node_user toneBlue
class node_agent_host,node_session_runtime,node_session_history,node_model_config toneAmber
class node_mcp,node_channels,node_herdr,node_skills_plugins toneMint
class node_browser_ui,node_browser_runtime,node_project_files toneRose
class node_toolchains,node_managed_process,node_updates,node_update_service toneIndigo
```

## Components

### Desktop shell

- [Chat workspace](https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Session controls](https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/hooks/useAgentSession.ts): `src/renderer/hooks/useAgentSession.ts`
- [Desktop IPC](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/ipc.ts): `src/main/ipc.ts`
- [Host supervisor](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/host-manager.ts): `src/main/host-manager.ts`

### Agent sessions

- [Agent Host RPC](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/rpc-manager.ts): `src/agent-host/rpc-manager.ts`
- [Session services](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/desktop-session-services.ts): `src/agent-host/desktop-session-services.ts`
- [Session history](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/session-reader.ts): `src/agent-host/session-reader.ts`
- [Models and routing](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/azure-upgrade.ts): `src/agent-host/azure-upgrade.ts`

### Agent integrations

- [MCP services](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/mcp/service.ts): `src/agent-host/mcp/service.ts`
- [Message channels](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/channels/channel-manager.ts): `src/agent-host/channels/channel-manager.ts`
- [Herdr runtime](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/herdr/runtime-manager.ts): `src/main/herdr/runtime-manager.ts`
- [Skills and plugins](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/skills-service.ts): `src/agent-host/skills-service.ts`

### Workspace capabilities

- [Browser interface](https://github.com/dlyzzt/pi-desktop/blob/main/src/renderer/components/browser/BrowserDock.tsx): `src/renderer/components/browser/BrowserDock.tsx`
- [Browser automation](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/browser/browser-tab-manager.ts): `src/main/browser/browser-tab-manager.ts`
- [Project files](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/handlers/files.ts): `src/agent-host/handlers/files.ts`

### Runtime operations

- [Toolchain manager](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/toolchains/manager.ts): `src/main/toolchains/manager.ts`
- [Managed processes](https://github.com/dlyzzt/pi-desktop/blob/main/src/agent-host/managed-process/service.ts): `src/agent-host/managed-process/service.ts`
- [Desktop updates](https://github.com/dlyzzt/pi-desktop/blob/main/src/main/update-manager.ts): `src/main/update-manager.ts`

### Other components

- **User**
- **Update service**

## Connections

- User → Chat workspace: uses (evidence: `README.md`)
- Chat workspace → Session controls: controls sessions (evidence: `src/renderer/hooks/useAgentSession.ts`)
- Session controls → Desktop IPC: sends commands (evidence: `README.md`)
- Desktop IPC → Host supervisor: routes IPC (evidence: `src/smoke/main.ts`)
- Host supervisor → Agent Host RPC: supervises (evidence: `src/main/host-manager.ts`)
- Agent Host RPC → Session services: creates services (evidence: `src/agent-host/desktop-session-services.ts`)
- Agent Host RPC → Session history: reads sessions (evidence: `src/agent-host/session-reader.ts`)
- Session services → Models and routing: configures models (evidence: `src/agent-host/desktop-session-services.ts`)
- Agent Host RPC → MCP services: provides MCP tools (evidence: `src/agent-host/rpc-manager.ts`)
- Agent Host RPC → Message channels: handles channel turns (evidence: `src/agent-host/channels/channel-manager.ts`)
- User → Browser interface: controls browser (evidence: `README.md`)
- Browser interface → Browser automation: requests actions (evidence: `README.md`)
- Agent Host RPC → Browser automation: invokes browser tools (evidence: `src/agent-host/rpc-manager.ts`)
- User → Project files: works with files (evidence: `README.md`)
- Agent Host RPC → Toolchain manager: resolves tools (evidence: `src/main/toolchains/manager.ts`)
- Agent Host RPC → Managed processes: manages processes (evidence: `src/agent-host/managed-process/service.ts`)
- User → Herdr runtime: controls fleet (evidence: `README.md`)
- Agent Host RPC → Herdr runtime: connects runtime
- Agent Host RPC → Skills and plugins: loads extensions (evidence: `README.md`)
- User → Desktop updates: requests updates (evidence: `README.md`)
- Desktop updates → Update service: checks releases (evidence: `src/main/update-manager.ts`)