# wangmiaozero/pi-harness architecture

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

- Interactive diagram: https://gitdiagram.com/wangmiaozero/pi-harness
- Repository: https://github.com/wangmiaozero/pi-harness

## Overview

Pi-Harness is an Electron desktop control plane built around the native Pi coding agent. The main workflow is a user working in a project or chat, invoking Pi through the desktop, then inspecting or managing the resulting session and work through workspace and Harness tools. Documented branches include Git and files, providers and capabilities, run recovery and evaluation, agent orchestration, imported conversation history, and local project architecture analysis. The graph uses README-documented relationships and the shown preload bridge; unsampled implementation details are not inferred.

Main entry points: [`src/main/agent`](https://github.com/wangmiaozero/pi-harness/tree/main/src/main/agent) (Pi agent runtime), [`src/renderer/src/App.vue`](https://github.com/wangmiaozero/pi-harness/blob/main/src/renderer/src/App.vue) (Application UI), [`src/preload/index.ts`](https://github.com/wangmiaozero/pi-harness/blob/main/src/preload/index.ts) (Typed IPC bridge), [`src/main/harness/orchestrator/orchestrator-service.ts`](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/orchestrator/orchestrator-service.ts) (Agent orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_renderer["Application UI<br/>[App.vue]"]
  node_preload["Typed IPC bridge<br/>[index.ts]"]
  node_ipc["Main IPC handlers"]
  node_persistence[("Application persistence<br/>[storage.ts]")]
end

subgraph group_agent["Pi and capabilities"]
  node_piagent["Pi agent runtime"]
  node_sessions[("Session management<br/>[session-service.ts]")]
  node_providers["Providers and models"]
  node_capabilities["Skills and packages"]
  node_environment["Runtime environment<br/>[runtime-manager.ts]"]
end

subgraph group_harness["Harness control plane"]
  node_runs[("Runs and traces<br/>[run-registry.ts]")]
  node_harnesscontrol["Run control and recovery<br/>[harness-runtime.ts]"]
  node_policy["Policy and budgets<br/>[policy-engine.ts]"]
  node_evaluation["Evaluation and diagnostics"]
  node_orchestrator["Agent orchestration"]
  node_orchestrationstore[("Orchestration state")]
end

subgraph group_workspace["Workspace tools"]
  node_workspace["Projects and files"]
  node_fileaccess["File access"]
  node_git["Git and worktrees<br/>[git-service.ts]"]
  node_history["Universal conversation history<br/>[service.ts]"]
end

subgraph group_analysis["Local analysis"]
  node_architecture["Project architecture maps<br/>[service.ts]"]
  node_archrender["Architecture map rendering"]
  node_archshared["Layout and diagnostics"]
end

node_user(("Desktop user"))

node_user -->|"uses"| node_renderer
node_renderer -->|"requests capabilities"| node_preload
node_preload -->|"invokes handlers"| node_ipc
node_user -->|"runs Pi"| node_piagent
node_piagent -->|"maintains sessions"| node_sessions
node_user -->|"configures models"| node_providers
node_user -->|"manages capabilities"| node_capabilities
node_environment -.->|"supplies runtime"| node_piagent
node_user -->|"inspects runs"| node_runs
node_user -->|"controls recovery"| node_harnesscontrol
node_user -->|"sets policies"| node_policy
node_user -->|"evaluates results"| node_evaluation
node_user -->|"coordinates agents"| node_orchestrator
node_orchestrator -->|"stores orchestration state"| node_orchestrationstore
node_user -->|"opens projects"| node_workspace
node_workspace -.->|"browses files"| node_fileaccess
node_user -->|"manages Git"| node_git
node_user -->|"browses conversations"| node_history
node_user -->|"explores architecture"| node_architecture
node_architecture -.->|"renders maps"| node_archrender
node_archrender -->|"uses layout helpers"| node_archshared
node_user -.->|"stores app data"| node_persistence

click node_renderer "https://github.com/wangmiaozero/pi-harness/blob/main/src/renderer/src/App.vue"
click node_preload "https://github.com/wangmiaozero/pi-harness/blob/main/src/preload/index.ts"
click node_ipc "https://github.com/wangmiaozero/pi-harness/tree/main/src/main/ipc"
click node_piagent "https://github.com/wangmiaozero/pi-harness/tree/main/src/main/agent"
click node_sessions "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/sessions/session-service.ts"
click node_providers "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/services/provider-service.ts"
click node_capabilities "https://github.com/wangmiaozero/pi-harness/tree/main/src/main/capabilities"
click node_environment "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/runtime/runtime-manager.ts"
click node_runs "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/runs/run-registry.ts"
click node_harnesscontrol "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/harness-runtime.ts"
click node_policy "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/policy/policy-engine.ts"
click node_evaluation "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/evaluation/evaluation-service.ts"
click node_orchestrator "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/orchestrator/orchestrator-service.ts"
click node_orchestrationstore "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/orchestrator/orchestration-store.ts"
click node_workspace "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/workspace/workspace-service.ts"
click node_fileaccess "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/files/file-access-service.ts"
click node_git "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/git/git-service.ts"
click node_history "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/universal/service.ts"
click node_architecture "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/intelligence/service.ts"
click node_archrender "https://github.com/wangmiaozero/pi-harness/tree/main/resources/archify/renderers/architecture"
click node_archshared "https://github.com/wangmiaozero/pi-harness/tree/main/resources/archify/renderers/shared"
click node_persistence "https://github.com/wangmiaozero/pi-harness/blob/main/src/main/services/storage.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_preload,node_ipc,node_persistence,node_user toneBlue
class node_piagent,node_sessions,node_providers,node_capabilities,node_environment toneAmber
class node_runs,node_harnesscontrol,node_policy,node_evaluation,node_orchestrator,node_orchestrationstore toneMint
class node_workspace,node_fileaccess,node_git,node_history toneRose
class node_architecture,node_archrender,node_archshared toneIndigo
```

## Components

### Desktop experience

- [Application UI](https://github.com/wangmiaozero/pi-harness/blob/main/src/renderer/src/App.vue): `src/renderer/src/App.vue`
- [Typed IPC bridge](https://github.com/wangmiaozero/pi-harness/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Main IPC handlers](https://github.com/wangmiaozero/pi-harness/tree/main/src/main/ipc): `src/main/ipc`
- [Application persistence](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/services/storage.ts): `src/main/services/storage.ts`

### Pi and capabilities

- [Pi agent runtime](https://github.com/wangmiaozero/pi-harness/tree/main/src/main/agent): `src/main/agent`
- [Session management](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/sessions/session-service.ts): `src/main/sessions/session-service.ts`
- [Providers and models](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/services/provider-service.ts): `src/main/services/provider-service.ts`
- [Skills and packages](https://github.com/wangmiaozero/pi-harness/tree/main/src/main/capabilities): `src/main/capabilities`
- [Runtime environment](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/runtime/runtime-manager.ts): `src/main/runtime/runtime-manager.ts`

### Harness control plane

- [Runs and traces](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/runs/run-registry.ts): `src/main/harness/runs/run-registry.ts`
- [Run control and recovery](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/harness-runtime.ts): `src/main/harness/harness-runtime.ts`
- [Policy and budgets](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/policy/policy-engine.ts): `src/main/harness/policy/policy-engine.ts`
- [Evaluation and diagnostics](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/evaluation/evaluation-service.ts): `src/main/harness/evaluation/evaluation-service.ts`
- [Agent orchestration](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/orchestrator/orchestrator-service.ts): `src/main/harness/orchestrator/orchestrator-service.ts`
- [Orchestration state](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/harness/orchestrator/orchestration-store.ts): `src/main/harness/orchestrator/orchestration-store.ts`

### Workspace tools

- [Projects and files](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/workspace/workspace-service.ts): `src/main/workspace/workspace-service.ts`
- [File access](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/files/file-access-service.ts): `src/main/files/file-access-service.ts`
- [Git and worktrees](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/git/git-service.ts): `src/main/git/git-service.ts`
- [Universal conversation history](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/universal/service.ts): `src/main/universal/service.ts`

### Local analysis

- [Project architecture maps](https://github.com/wangmiaozero/pi-harness/blob/main/src/main/intelligence/service.ts): `src/main/intelligence/service.ts`
- [Architecture map rendering](https://github.com/wangmiaozero/pi-harness/tree/main/resources/archify/renderers/architecture): `resources/archify/renderers/architecture`
- [Layout and diagnostics](https://github.com/wangmiaozero/pi-harness/tree/main/resources/archify/renderers/shared): `resources/archify/renderers/shared`

### Other components

- **Desktop user**

## Connections

- Desktop user → Application UI: uses (evidence: `README.md`)
- Application UI → Typed IPC bridge: requests capabilities (evidence: `src/preload/index.ts`)
- Typed IPC bridge → Main IPC handlers: invokes handlers (evidence: `src/preload/index.ts`)
- Desktop user → Pi agent runtime: runs Pi (evidence: `README.md`)
- Pi agent runtime → Session management: maintains sessions (evidence: `README.md`)
- Desktop user → Providers and models: configures models (evidence: `README.md`)
- Desktop user → Skills and packages: manages capabilities (evidence: `README.md`)
- Runtime environment → Pi agent runtime: supplies runtime
- Desktop user → Runs and traces: inspects runs (evidence: `README.md`)
- Desktop user → Run control and recovery: controls recovery (evidence: `README.md`)
- Desktop user → Policy and budgets: sets policies (evidence: `README.md`)
- Desktop user → Evaluation and diagnostics: evaluates results (evidence: `README.md`)
- Desktop user → Agent orchestration: coordinates agents (evidence: `README.md`)
- Agent orchestration → Orchestration state: stores orchestration state (evidence: `src/main/harness/orchestrator/orchestrator-service.ts`)
- Desktop user → Projects and files: opens projects (evidence: `README.md`)
- Projects and files → File access: browses files
- Desktop user → Git and worktrees: manages Git (evidence: `README.md`)
- Desktop user → Universal conversation history: browses conversations (evidence: `README.md`)
- Desktop user → Project architecture maps: explores architecture (evidence: `README.md`)
- Project architecture maps → Architecture map rendering: renders maps
- Architecture map rendering → Layout and diagnostics: uses layout helpers (evidence: `resources/archify/renderers/architecture/routing.mjs`)
- Desktop user → Application persistence: stores app data