# gcoder1991/pi-mesh architecture

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

- Interactive diagram: https://gitdiagram.com/gcoder1991/pi-mesh
- Repository: https://github.com/gcoder1991/pi-mesh

## Overview

pi-mesh is a Pi extension for running durable Mesh DAGs and direct child agents through a shared in-process agent runtime. The main path starts with Host tool or command input, routes work through the extension and agent managers, executes child sessions, then exposes results and live status. It also supports scheduled and YAML-defined workflows, consensus runs, mailbox control, recovery, and optional bridging. The graph uses documented capabilities and sampled imports; unsampled implementation details are represented only where the tree or README supports them.

Main entry points: [`src/extension.ts`](https://github.com/gcoder1991/pi-mesh/blob/master/src/extension.ts) (Native extension), [`src/manager.ts`](https://github.com/gcoder1991/pi-mesh/blob/master/src/manager.ts) (Mesh manager), [`src/session-agents.ts`](https://github.com/gcoder1991/pi-mesh/blob/master/src/session-agents.ts) (Direct agent manager), [`src/subagent-runtime.ts`](https://github.com/gcoder1991/pi-mesh/blob/master/src/subagent-runtime.ts) (Child session runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Host entry points"]
  node_extension["Native extension<br/>[extension.ts]"]
  node_compat["Direct tools"]
end

subgraph group_execution["Agent execution"]
  node_agents["Agent discovery<br/>[agents.ts]"]
  node_session_manager["Direct agent manager<br/>[session-agents.ts]"]
  node_runtime["Child session runtime"]
  node_model["Model resolution"]
  node_worktree["Worktree isolation<br/>[worktree.ts]"]
  node_memory[("Agent memory<br/>[memory.ts]")]
end

subgraph group_mesh["Mesh lifecycle"]
  node_manager["Mesh manager<br/>[manager.ts]"]
  node_workflow["Workflow loader<br/>[workflows.ts]"]
  node_consensus["Consensus template"]
  node_scheduler["Agent scheduler<br/>[scheduler.ts]"]
end

subgraph group_state["State and control"]
  node_settings["Mesh settings<br/>[settings.ts]"]
  node_store[("Durable run store<br/>[store.ts]")]
  node_recovery["Run recovery<br/>[recovery-state.ts]"]
  node_mailbox[("Mailbox and control<br/>[store.ts]")]
  node_bridge["Optional host bridge<br/>[host-bridge.ts]"]
end

subgraph group_experience["Results and inspection"]
  node_fleet_view["Agent fleet view<br/>[fleet-view.ts]"]
  node_mesh_tree["Mesh inspector<br/>[mesh-tree.ts]"]
  node_conversation["Conversation viewer"]
  node_notifications["Completion notifications<br/>[notifications.ts]"]
end

node_host(("Pi Host"))
node_pi_sessions["Pi AgentSessions"]

node_host -->|"invokes tools"| node_extension
node_host -->|"uses commands"| node_compat
node_extension -->|"dispatches Mesh"| node_manager
node_extension -->|"dispatches agents"| node_session_manager
node_extension -->|"loads settings"| node_settings
node_extension -->|"discovers agents"| node_agents
node_extension -->|"stores messages"| node_store
node_extension -->|"opens inspector"| node_mesh_tree
node_compat -->|"launches agents"| node_session_manager
node_compat -->|"schedules agents"| node_scheduler
node_compat -->|"resolves model"| node_model
node_manager -->|"checkpoints runs"| node_store
node_manager -->|"validates state"| node_recovery
node_manager -->|"executes children"| node_runtime
node_manager -.->|"isolates tasks"| node_worktree
node_workflow -->|"provides tasks"| node_manager
node_consensus -->|"defines graph"| node_manager
node_session_manager -->|"runs agents"| node_runtime
node_session_manager -->|"persists registry"| node_store
node_runtime -->|"creates sessions"| node_pi_sessions
node_runtime -->|"selects model"| node_model
node_runtime -.->|"uses isolation"| node_worktree
node_bridge -->|"checks access"| node_settings
node_bridge -->|"routes messages"| node_mailbox
node_extension -->|"sends control"| node_mailbox
node_fleet_view -->|"shows agents"| node_session_manager
node_fleet_view -->|"opens transcript"| node_conversation
node_mesh_tree -->|"reads runs"| node_manager
node_extension -->|"notifies completion"| node_notifications
node_session_manager -.->|"uses agent memory"| node_memory

click node_extension "https://github.com/gcoder1991/pi-mesh/blob/master/src/extension.ts"
click node_compat "https://github.com/gcoder1991/pi-mesh/blob/master/src/compat-extension.ts"
click node_agents "https://github.com/gcoder1991/pi-mesh/blob/master/src/agents.ts"
click node_session_manager "https://github.com/gcoder1991/pi-mesh/blob/master/src/session-agents.ts"
click node_runtime "https://github.com/gcoder1991/pi-mesh/blob/master/src/subagent-runtime.ts"
click node_model "https://github.com/gcoder1991/pi-mesh/blob/master/src/model-resolution.ts"
click node_manager "https://github.com/gcoder1991/pi-mesh/blob/master/src/manager.ts"
click node_workflow "https://github.com/gcoder1991/pi-mesh/blob/master/src/workflows.ts"
click node_consensus "https://github.com/gcoder1991/pi-mesh/blob/master/src/consensus-template.ts"
click node_scheduler "https://github.com/gcoder1991/pi-mesh/blob/master/src/scheduler.ts"
click node_settings "https://github.com/gcoder1991/pi-mesh/blob/master/src/settings.ts"
click node_store "https://github.com/gcoder1991/pi-mesh/blob/master/src/store.ts"
click node_recovery "https://github.com/gcoder1991/pi-mesh/blob/master/src/recovery-state.ts"
click node_mailbox "https://github.com/gcoder1991/pi-mesh/blob/master/src/store.ts"
click node_bridge "https://github.com/gcoder1991/pi-mesh/blob/master/src/host-bridge.ts"
click node_worktree "https://github.com/gcoder1991/pi-mesh/blob/master/src/worktree.ts"
click node_fleet_view "https://github.com/gcoder1991/pi-mesh/blob/master/src/fleet-view.ts"
click node_mesh_tree "https://github.com/gcoder1991/pi-mesh/blob/master/src/mesh-tree.ts"
click node_conversation "https://github.com/gcoder1991/pi-mesh/blob/master/src/conversation-viewer.ts"
click node_notifications "https://github.com/gcoder1991/pi-mesh/blob/master/src/notifications.ts"
click node_memory "https://github.com/gcoder1991/pi-mesh/blob/master/src/memory.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_extension,node_compat toneBlue
class node_agents,node_session_manager,node_runtime,node_model,node_worktree,node_memory toneAmber
class node_manager,node_workflow,node_consensus,node_scheduler toneMint
class node_settings,node_store,node_recovery,node_mailbox,node_bridge toneRose
class node_fleet_view,node_mesh_tree,node_conversation,node_notifications,node_host,node_pi_sessions toneIndigo
```

## Components

### Host entry points

- [Native extension](https://github.com/gcoder1991/pi-mesh/blob/master/src/extension.ts): `src/extension.ts`
- [Direct tools](https://github.com/gcoder1991/pi-mesh/blob/master/src/compat-extension.ts): `src/compat-extension.ts`

### Agent execution

- [Agent discovery](https://github.com/gcoder1991/pi-mesh/blob/master/src/agents.ts): `src/agents.ts`
- [Direct agent manager](https://github.com/gcoder1991/pi-mesh/blob/master/src/session-agents.ts): `src/session-agents.ts`
- [Child session runtime](https://github.com/gcoder1991/pi-mesh/blob/master/src/subagent-runtime.ts): `src/subagent-runtime.ts`
- [Model resolution](https://github.com/gcoder1991/pi-mesh/blob/master/src/model-resolution.ts): `src/model-resolution.ts`
- [Worktree isolation](https://github.com/gcoder1991/pi-mesh/blob/master/src/worktree.ts): `src/worktree.ts`
- [Agent memory](https://github.com/gcoder1991/pi-mesh/blob/master/src/memory.ts): `src/memory.ts`

### Mesh lifecycle

- [Mesh manager](https://github.com/gcoder1991/pi-mesh/blob/master/src/manager.ts): `src/manager.ts`
- [Workflow loader](https://github.com/gcoder1991/pi-mesh/blob/master/src/workflows.ts): `src/workflows.ts`
- [Consensus template](https://github.com/gcoder1991/pi-mesh/blob/master/src/consensus-template.ts): `src/consensus-template.ts`
- [Agent scheduler](https://github.com/gcoder1991/pi-mesh/blob/master/src/scheduler.ts): `src/scheduler.ts`

### State and control

- [Mesh settings](https://github.com/gcoder1991/pi-mesh/blob/master/src/settings.ts): `src/settings.ts`
- [Durable run store](https://github.com/gcoder1991/pi-mesh/blob/master/src/store.ts): `src/store.ts`
- [Run recovery](https://github.com/gcoder1991/pi-mesh/blob/master/src/recovery-state.ts): `src/recovery-state.ts`
- [Mailbox and control](https://github.com/gcoder1991/pi-mesh/blob/master/src/store.ts): `src/store.ts`
- [Optional host bridge](https://github.com/gcoder1991/pi-mesh/blob/master/src/host-bridge.ts): `src/host-bridge.ts`

### Results and inspection

- [Agent fleet view](https://github.com/gcoder1991/pi-mesh/blob/master/src/fleet-view.ts): `src/fleet-view.ts`
- [Mesh inspector](https://github.com/gcoder1991/pi-mesh/blob/master/src/mesh-tree.ts): `src/mesh-tree.ts`
- [Conversation viewer](https://github.com/gcoder1991/pi-mesh/blob/master/src/conversation-viewer.ts): `src/conversation-viewer.ts`
- [Completion notifications](https://github.com/gcoder1991/pi-mesh/blob/master/src/notifications.ts): `src/notifications.ts`

### Other components

- **Pi Host**
- **Pi AgentSessions**

## Connections

- Pi Host → Native extension: invokes tools
- Pi Host → Direct tools: uses commands
- Native extension → Mesh manager: dispatches Mesh
- Native extension → Direct agent manager: dispatches agents
- Native extension → Mesh settings: loads settings
- Native extension → Agent discovery: discovers agents
- Native extension → Durable run store: stores messages
- Native extension → Mesh inspector: opens inspector
- Direct tools → Direct agent manager: launches agents
- Direct tools → Agent scheduler: schedules agents
- Direct tools → Model resolution: resolves model
- Mesh manager → Durable run store: checkpoints runs
- Mesh manager → Run recovery: validates state
- Mesh manager → Child session runtime: executes children
- Mesh manager → Worktree isolation: isolates tasks
- Workflow loader → Mesh manager: provides tasks
- Consensus template → Mesh manager: defines graph
- Direct agent manager → Child session runtime: runs agents
- Direct agent manager → Durable run store: persists registry
- Child session runtime → Pi AgentSessions: creates sessions
- Child session runtime → Model resolution: selects model
- Child session runtime → Worktree isolation: uses isolation
- Optional host bridge → Mesh settings: checks access
- Optional host bridge → Mailbox and control: routes messages
- Native extension → Mailbox and control: sends control
- Agent fleet view → Direct agent manager: shows agents
- Agent fleet view → Conversation viewer: opens transcript
- Mesh inspector → Mesh manager: reads runs
- Native extension → Completion notifications: notifies completion
- Direct agent manager → Agent memory: uses agent memory