# myliuyx/pi-workbench architecture

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

- Interactive diagram: https://gitdiagram.com/myliuyx/pi-workbench
- Repository: https://github.com/myliuyx/pi-workbench

## Overview

Pi Workbench presents Pi coding-agent capabilities through a shared browser UI, backed by a local HTTP/SSE core; Electron embeds that core for desktop use. The principal workflow is user prompt → UI transport → core session/agent → streamed events and persisted session → rendered conversation. Separate branches cover model/provider settings, approvals and trust, skills/resources, and filesystem browsing. The README documents these capabilities; links between components are included only where it or the supplied source excerpts/index support them.

Main entry points: [`packages/core/src/session.ts`](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/session.ts) (Agent session), [`packages/core/src/server.ts`](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/server.ts) (HTTP and SSE), [`packages/ui/src/App.tsx`](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/App.tsx) (Workbench screens), [`packages/ui/src/services/live-transport.ts`](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/services/live-transport.ts) (Live transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workbench UI"]
  node_workbench["Workbench screens<br/>[App.tsx]"]
  node_chat["Chat state<br/>[chat-store.ts]"]
  node_transport["Live transport<br/>[live-transport.ts]"]
  node_settings["Settings screens<br/>[SettingsDialog.tsx]"]
end

subgraph group_core["Core service"]
  node_server["HTTP and SSE<br/>[server.ts]"]
  node_runtime["Core runtime<br/>[main.ts]"]
  node_contract["UI-core contract<br/>[contract.ts]"]
end

subgraph group_domain["Agent capabilities"]
  node_sessions[("Session persistence<br/>[sessions.ts]")]
  node_agent["Agent session<br/>[session.ts]"]
  node_models["Models and providers<br/>[providers.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
  node_trust["Trust and approvals<br/>[trust.ts]"]
  node_skills["Skills and resources<br/>[skills.ts]"]
  node_filesystem["Filesystem access<br/>[fs-list.ts]"]
end

subgraph group_desktop["Desktop shell"]
  node_desktop["Electron shell<br/>[main.ts]"]
end

node_user(("User"))
node_pi{{"Pi agent package"}}
node_machine[("Local machine")]

node_user -->|"uses"| node_workbench
node_workbench -->|"presents chat"| node_chat
node_chat -->|"sends prompts"| node_transport
node_transport -->|"calls core"| node_server
node_server -->|"serves runtime"| node_runtime
node_runtime -->|"starts server"| node_server
node_server -->|"dispatches requests"| node_agent
node_agent -->|"creates session"| node_pi
node_agent -->|"loads sessions"| node_sessions
node_server -->|"serves browsing"| node_filesystem
node_server -->|"uses payloads"| node_contract
node_agent -->|"uses providers"| node_models
node_agent -->|"checks trust"| node_trust
node_agent -->|"loads skills"| node_skills
node_agent -->|"uses tools"| node_tools
node_settings -->|"configures agent"| node_transport
node_server -->|"reads files"| node_machine
node_agent -->|"persists sessions"| node_machine
node_desktop -->|"spawns core"| node_runtime
node_desktop -->|"loads interface"| node_workbench

click node_workbench "https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/App.tsx"
click node_chat "https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/store/chat-store.ts"
click node_transport "https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/services/live-transport.ts"
click node_settings "https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/screens/SettingsDialog.tsx"
click node_server "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/server.ts"
click node_runtime "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/main.ts"
click node_contract "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/contract.ts"
click node_sessions "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/sessions.ts"
click node_agent "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/session.ts"
click node_models "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/providers.ts"
click node_tools "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/tools.ts"
click node_trust "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/trust.ts"
click node_skills "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/skills.ts"
click node_filesystem "https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/fs-list.ts"
click node_desktop "https://github.com/myliuyx/pi-workbench/blob/main/packages/desktop/src/main.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_workbench,node_chat,node_transport,node_settings,node_user toneBlue
class node_server,node_runtime,node_contract,node_machine toneAmber
class node_sessions,node_agent,node_models,node_tools,node_trust,node_skills,node_filesystem toneMint
class node_desktop toneRose
class node_pi toneIndigo
```

## Components

### Workbench UI

- [Workbench screens](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/App.tsx): `packages/ui/src/App.tsx`
- [Chat state](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/store/chat-store.ts): `packages/ui/src/store/chat-store.ts`
- [Live transport](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/services/live-transport.ts): `packages/ui/src/services/live-transport.ts`
- [Settings screens](https://github.com/myliuyx/pi-workbench/blob/main/packages/ui/src/screens/SettingsDialog.tsx): `packages/ui/src/screens/SettingsDialog.tsx`

### Core service

- [HTTP and SSE](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/server.ts): `packages/core/src/server.ts`
- [Core runtime](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/main.ts): `packages/core/src/main.ts`
- [UI-core contract](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/contract.ts): `packages/core/src/contract.ts`

### Agent capabilities

- [Session persistence](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/sessions.ts): `packages/core/src/sessions.ts`
- [Agent session](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/session.ts): `packages/core/src/session.ts`
- [Models and providers](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/providers.ts): `packages/core/src/providers.ts`
- [Agent tools](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/tools.ts): `packages/core/src/tools.ts`
- [Trust and approvals](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/trust.ts): `packages/core/src/trust.ts`
- [Skills and resources](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/skills.ts): `packages/core/src/skills.ts`
- [Filesystem access](https://github.com/myliuyx/pi-workbench/blob/main/packages/core/src/fs-list.ts): `packages/core/src/fs-list.ts`

### Desktop shell

- [Electron shell](https://github.com/myliuyx/pi-workbench/blob/main/packages/desktop/src/main.ts): `packages/desktop/src/main.ts`

### Other components

- **User**
- **Pi agent package**
- **Local machine**

## Connections

- User → Workbench screens: uses (evidence: `README.md`)
- Workbench screens → Chat state: presents chat (evidence: `README.md`)
- Chat state → Live transport: sends prompts (evidence: `README.md`)
- Live transport → HTTP and SSE: calls core (evidence: `README.md`)
- HTTP and SSE → Core runtime: serves runtime (evidence: `packages/core/src/main.ts`)
- Core runtime → HTTP and SSE: starts server (evidence: `packages/core/src/main.ts`)
- HTTP and SSE → Agent session: dispatches requests (evidence: `packages/core/src/server.ts`)
- Agent session → Pi agent package: creates session (evidence: `packages/core/src/session.ts`)
- Agent session → Session persistence: loads sessions (evidence: `packages/core/src/session.ts`)
- HTTP and SSE → Filesystem access: serves browsing (evidence: `packages/core/src/server.ts`)
- HTTP and SSE → UI-core contract: uses payloads (evidence: `packages/core/src/server.ts`)
- Agent session → Models and providers: uses providers (evidence: `packages/core/src/session.ts`)
- Agent session → Trust and approvals: checks trust (evidence: `packages/core/src/session.ts`)
- Agent session → Skills and resources: loads skills (evidence: `packages/core/src/session.ts`)
- Agent session → Agent tools: uses tools (evidence: `packages/core/src/session.ts`)
- Settings screens → Live transport: configures agent (evidence: `README.md`)
- HTTP and SSE → Local machine: reads files (evidence: `packages/core/src/server.ts`)
- Agent session → Local machine: persists sessions (evidence: `README.md`)
- Electron shell → Core runtime: spawns core (evidence: `packages/desktop/src/main.ts`)
- Electron shell → Workbench screens: loads interface (evidence: `packages/desktop/src/main.ts`)
