# chunkhound/pi-schematic architecture

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

- Interactive diagram: https://gitdiagram.com/chunkhound/pi-schematic
- Repository: https://github.com/chunkhound/pi-schematic

## Overview

pi-schematic is a Pi extension for repeatable, policy-aware agent workflows. Operators define procedures in saved prompts or skills, configure semantic model roles, and invoke tools to delegate focused work, preserve decisions in a notebook, or hand off to a fresh phase. The graph also shows model capability routing, readonly enforcement, and shared session state. Some relationships are documented in the README; source-level edges use the supplied excerpts or SOURCE INDEX. Unsampled subsystems are represented only where the README documents their role.

Main entry points: [`index.ts`](https://github.com/chunkhound/pi-schematic/blob/main/index.ts) (Extension Entry), [`spawn/index.ts`](https://github.com/chunkhound/pi-schematic/blob/main/spawn/index.ts) (Spawn Tool), [`notebook/tools.ts`](https://github.com/chunkhound/pi-schematic/blob/main/notebook/tools.ts) (Notebook Tools), [`handoff/tool.ts`](https://github.com/chunkhound/pi-schematic/blob/main/handoff/tool.ts) (Handoff Tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow Runtime"]
  node_extension["Extension Entry<br/>[index.ts]"]
  node_saved["Saved Workflows"]
  node_state["Session State<br/>[state.ts]"]
  node_spawn["Spawn Tool<br/>[index.ts]"]
  node_spawnui["Spawn Results<br/>[renderer.ts]"]
end

subgraph group_models["Model Groups"]
  node_groupstore[("Group Storage<br/>[store.ts]")]
  node_groupui["Group Editor<br/>[tui.ts]"]
  node_router["Model Routing<br/>[router.ts]"]
  node_availability["Model Availability<br/>[availability.ts]"]
  node_constraints["Capability Constraints<br/>[modalities.ts]"]
  node_constraintengine["Constraint Evaluation<br/>[engine.ts]"]
end

subgraph group_memory["Notebook Memory"]
  node_notebooktools["Notebook Tools<br/>[tools.ts]"]
  node_notebookstore[("Notebook Storage<br/>[store.ts]")]
  node_topic["Notebook Topic<br/>[topic.ts]"]
end

subgraph group_handoff["Context Handoff"]
  node_handofftool["Handoff Tool<br/>[tool.ts]"]
  node_boundary["Handoff Boundary<br/>[boundary.ts]"]
  node_handoffcopy["Handoff Eligibility<br/>[eligibility.ts]"]
end

subgraph group_policy["Safety and UI"]
  node_readonly["Readonly Bash Guard<br/>[readonly-bash.ts]"]
  node_sandbox["OS Sandbox<br/>[os-sandbox.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_tui["Status and Commands<br/>[tui.ts]"]
end

node_operator(("Operator"))
node_pi(("Pi Agent"))

node_operator -->|"configures workflows"| node_extension
node_pi -->|"loads extension"| node_extension
node_extension -->|"registers tool"| node_spawn
node_extension -->|"registers tools"| node_notebooktools
node_extension -->|"registers tool"| node_handofftool
node_saved -->|"steers delegation"| node_spawn
node_spawn -->|"resolves model route"| node_router
node_router -->|"filters models"| node_availability
node_router -->|"evaluates requirements"| node_constraintengine
node_constraintengine -->|"uses descriptors"| node_constraints
node_groupui -->|"edits groups"| node_groupstore
node_groupstore -->|"validates overrides"| node_constraintengine
node_spawn -->|"renders results"| node_spawnui
node_spawn -->|"guards child shell"| node_readonly
node_readonly -->|"applies sandbox"| node_sandbox
node_notebooktools -->|"persists pages"| node_notebookstore
node_notebooktools -->|"manages topic"| node_topic
node_handofftool -->|"checks eligibility"| node_handoffcopy
node_handofftool -->|"stages handoff"| node_boundary
node_boundary -->|"rewrites notebook"| node_notebookstore
node_boundary -->|"clears topic"| node_topic
node_extension -->|"shares session state"| node_state
node_tui -->|"shows status copy"| node_notifications
node_operator -->|"configures model roles"| node_groupui
node_operator -->|"records decisions"| node_notebooktools
node_operator -->|"starts next phase"| node_handofftool
node_operator -->|"uses commands"| node_tui

click node_extension "https://github.com/chunkhound/pi-schematic/blob/main/index.ts"
click node_saved "https://github.com/chunkhound/pi-schematic/blob/main/frontmatter-cache.ts"
click node_state "https://github.com/chunkhound/pi-schematic/blob/main/state.ts"
click node_spawn "https://github.com/chunkhound/pi-schematic/blob/main/spawn/index.ts"
click node_spawnui "https://github.com/chunkhound/pi-schematic/blob/main/spawn/renderer.ts"
click node_groupstore "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/store.ts"
click node_groupui "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/tui.ts"
click node_router "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/router.ts"
click node_availability "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/availability.ts"
click node_constraints "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/constraints/modalities.ts"
click node_constraintengine "https://github.com/chunkhound/pi-schematic/blob/main/model-groups/constraints/engine.ts"
click node_notebooktools "https://github.com/chunkhound/pi-schematic/blob/main/notebook/tools.ts"
click node_notebookstore "https://github.com/chunkhound/pi-schematic/blob/main/notebook/store.ts"
click node_topic "https://github.com/chunkhound/pi-schematic/blob/main/notebook/topic.ts"
click node_handofftool "https://github.com/chunkhound/pi-schematic/blob/main/handoff/tool.ts"
click node_boundary "https://github.com/chunkhound/pi-schematic/blob/main/handoff/boundary.ts"
click node_handoffcopy "https://github.com/chunkhound/pi-schematic/blob/main/handoff/eligibility.ts"
click node_readonly "https://github.com/chunkhound/pi-schematic/blob/main/readonly-bash.ts"
click node_sandbox "https://github.com/chunkhound/pi-schematic/blob/main/os-sandbox.ts"
click node_notifications "https://github.com/chunkhound/pi-schematic/blob/main/notifications.ts"
click node_tui "https://github.com/chunkhound/pi-schematic/blob/main/tui.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_saved,node_state,node_spawn,node_spawnui toneBlue
class node_groupstore,node_groupui,node_router,node_availability,node_constraints,node_constraintengine toneAmber
class node_notebooktools,node_notebookstore,node_topic toneMint
class node_handofftool,node_boundary,node_handoffcopy toneRose
class node_readonly,node_sandbox,node_notifications,node_tui,node_operator,node_pi toneIndigo
```

## Components

### Workflow Runtime

- [Extension Entry](https://github.com/chunkhound/pi-schematic/blob/main/index.ts): `index.ts`
- [Saved Workflows](https://github.com/chunkhound/pi-schematic/blob/main/frontmatter-cache.ts): `frontmatter-cache.ts`
- [Session State](https://github.com/chunkhound/pi-schematic/blob/main/state.ts): `state.ts`
- [Spawn Tool](https://github.com/chunkhound/pi-schematic/blob/main/spawn/index.ts): `spawn/index.ts`
- [Spawn Results](https://github.com/chunkhound/pi-schematic/blob/main/spawn/renderer.ts): `spawn/renderer.ts`

### Model Groups

- [Group Storage](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/store.ts): `model-groups/store.ts`
- [Group Editor](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/tui.ts): `model-groups/tui.ts`
- [Model Routing](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/router.ts): `model-groups/router.ts`
- [Model Availability](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/availability.ts): `model-groups/availability.ts`
- [Capability Constraints](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/constraints/modalities.ts): `model-groups/constraints/modalities.ts`
- [Constraint Evaluation](https://github.com/chunkhound/pi-schematic/blob/main/model-groups/constraints/engine.ts): `model-groups/constraints/engine.ts`

### Notebook Memory

- [Notebook Tools](https://github.com/chunkhound/pi-schematic/blob/main/notebook/tools.ts): `notebook/tools.ts`
- [Notebook Storage](https://github.com/chunkhound/pi-schematic/blob/main/notebook/store.ts): `notebook/store.ts`
- [Notebook Topic](https://github.com/chunkhound/pi-schematic/blob/main/notebook/topic.ts): `notebook/topic.ts`

### Context Handoff

- [Handoff Tool](https://github.com/chunkhound/pi-schematic/blob/main/handoff/tool.ts): `handoff/tool.ts`
- [Handoff Boundary](https://github.com/chunkhound/pi-schematic/blob/main/handoff/boundary.ts): `handoff/boundary.ts`
- [Handoff Eligibility](https://github.com/chunkhound/pi-schematic/blob/main/handoff/eligibility.ts): `handoff/eligibility.ts`

### Safety and UI

- [Readonly Bash Guard](https://github.com/chunkhound/pi-schematic/blob/main/readonly-bash.ts): `readonly-bash.ts`
- [OS Sandbox](https://github.com/chunkhound/pi-schematic/blob/main/os-sandbox.ts): `os-sandbox.ts`
- [Notifications](https://github.com/chunkhound/pi-schematic/blob/main/notifications.ts): `notifications.ts`
- [Status and Commands](https://github.com/chunkhound/pi-schematic/blob/main/tui.ts): `tui.ts`

### Other components

- **Operator**
- **Pi Agent**

## Connections

- Operator → Extension Entry: configures workflows (evidence: `README.md`)
- Pi Agent → Extension Entry: loads extension (evidence: `README.md`)
- Extension Entry → Spawn Tool: registers tool (evidence: `index.ts`)
- Extension Entry → Notebook Tools: registers tools (evidence: `index.ts`)
- Extension Entry → Handoff Tool: registers tool (evidence: `index.ts`)
- Saved Workflows → Spawn Tool: steers delegation (evidence: `README.md`)
- Spawn Tool → Model Routing: resolves model route (evidence: `spawn/index.ts`)
- Model Routing → Model Availability: filters models (evidence: `model-groups/router.ts`)
- Model Routing → Constraint Evaluation: evaluates requirements (evidence: `model-groups/router.ts`)
- Constraint Evaluation → Capability Constraints: uses descriptors (evidence: `model-groups/constraints/engine.ts`)
- Group Editor → Group Storage: edits groups (evidence: `model-groups/tui.ts`)
- Group Storage → Constraint Evaluation: validates overrides (evidence: `model-groups/store.ts`)
- Spawn Tool → Spawn Results: renders results (evidence: `spawn/index.ts`)
- Spawn Tool → Readonly Bash Guard: guards child shell (evidence: `spawn/index.ts`)
- Readonly Bash Guard → OS Sandbox: applies sandbox (evidence: `readonly-bash.ts`)
- Notebook Tools → Notebook Storage: persists pages (evidence: `notebook/tools.ts`)
- Notebook Tools → Notebook Topic: manages topic (evidence: `notebook/tools.ts`)
- Handoff Tool → Handoff Eligibility: checks eligibility (evidence: `handoff/tool.ts`)
- Handoff Tool → Handoff Boundary: stages handoff (evidence: `README.md`)
- Handoff Boundary → Notebook Storage: rewrites notebook (evidence: `handoff/boundary.ts`)
- Handoff Boundary → Notebook Topic: clears topic (evidence: `handoff/boundary.ts`)
- Extension Entry → Session State: shares session state (evidence: `index.ts`)
- Status and Commands → Notifications: shows status copy (evidence: `tui.ts`)
- Operator → Group Editor: configures model roles (evidence: `README.md`)
- Operator → Notebook Tools: records decisions (evidence: `README.md`)
- Operator → Handoff Tool: starts next phase (evidence: `README.md`)
- Operator → Status and Commands: uses commands (evidence: `README.md`)