# tintinweb/pi-subagents architecture

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

- Interactive diagram: https://gitdiagram.com/tintinweb/pi-subagents
- Repository: https://github.com/tintinweb/pi-subagents

## Overview

@tintinweb/pi-subagents is a pi extension for autonomous subagents and deterministic workflow orchestration. The main workflow starts in the extension’s pi-facing entry point: users or the orchestrator invoke agent tools, agent types and invocation settings are resolved, and the manager coordinates isolated agent sessions through the runner. Results, usage, and lifecycle state feed the UI and notifications. Separate capabilities include mentions, schedules, nested delegation, memory, and worktree isolation. Workflow scripts have their own host/runtime and progress interface. Edges reflect README statements or source-index references; some integrations are documented but their implementation details were not sampled.

Main entry points: [`src/index.ts`](https://github.com/tintinweb/pi-subagents/blob/master/src/index.ts) (Extension entry), [`src/agent-manager.ts`](https://github.com/tintinweb/pi-subagents/blob/master/src/agent-manager.ts) (Agent manager), [`src/nested-tools.ts`](https://github.com/tintinweb/pi-subagents/blob/master/src/nested-tools.ts) (Nested tools), [`src/workflow/runtime.ts`](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/runtime.ts) (Workflow runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Extension and agents"]
  node_entry["Extension entry<br/>[index.ts]"]
  node_types["Agent registry<br/>[agent-types.ts]"]
  node_custom["Custom agents<br/>[custom-agents.ts]"]
  node_invocation["Invocation config"]
end

subgraph group_agent_runtime["Agent runtime"]
  node_manager["Agent manager<br/>[agent-manager.ts]"]
  node_runner["Session runner<br/>[agent-runner.ts]"]
  node_nested["Nested tools<br/>[nested-tools.ts]"]
  node_model["Model resolution<br/>[model-resolver.ts]"]
  node_usage["Usage accounting<br/>[usage.ts]"]
end

subgraph group_surfaces["User surfaces"]
  node_mentions["Agent mentions<br/>[mention.ts]"]
  node_mention_ui["Mention UI<br/>[agent-mention.ts]"]
  node_widget["Agent widget<br/>[agent-widget.ts]"]
  node_fleet["Fleet view<br/>[fleet-list.ts]"]
  node_viewer["Conversation viewer"]
end

subgraph group_workflows["Workflow orchestration"]
  node_workflow_tool["Workflow tool<br/>[host.ts]"]
  node_workflow_runtime["Workflow runtime<br/>[runtime.ts]"]
  node_workflow_meta["Workflow metadata<br/>[meta.ts]"]
  node_workflow_progress["Workflow progress<br/>[progress.ts]"]
  node_workflow_task["Workflow task<br/>[task.ts]"]
  node_workflow_ui["Workflow UI<br/>[workflow-menu.ts]"]
end

subgraph group_integrations["Persistence and integrations"]
  node_scheduler["Scheduler<br/>[schedule.ts]"]
  node_memory[("Agent memory<br/>[memory.ts]")]
  node_worktree["Worktree isolation<br/>[worktree.ts]"]
  node_rpc["Extension RPC"]
end

node_user(("Pi user"))
node_pi["Pi host"]

node_user -->|"invokes"| node_entry
node_pi -->|"loads extension"| node_entry
node_entry -->|"registers agents"| node_manager
node_entry -->|"uses registry"| node_types
node_entry -->|"registers schedules"| node_scheduler
node_entry -->|"registers workflow"| node_workflow_tool
node_entry -->|"integrates mentions"| node_mentions
node_entry -->|"registers RPC"| node_rpc
node_custom -->|"provides definitions"| node_types
node_manager -->|"starts or resumes"| node_runner
node_manager -->|"creates and cleans"| node_worktree
node_manager -->|"records usage"| node_usage
node_runner -->|"gets agent config"| node_types
node_runner -->|"loads memory"| node_memory
node_nested -->|"resolves child types"| node_types
node_nested -->|"delegates child runs"| node_manager
node_nested -->|"resolves options"| node_invocation
node_nested -->|"resolves model"| node_model
node_entry -->|"enables delegation"| node_nested
node_entry -->|"registers widget"| node_widget
node_entry -->|"registers fleet view"| node_fleet
node_entry -->|"registers mention UI"| node_mention_ui
node_fleet -->|"opens conversation"| node_viewer
node_viewer -->|"reuses rendering"| node_widget
node_scheduler -->|"starts scheduled agents"| node_manager
node_scheduler -->|"runs agent"| node_runner
node_workflow_tool -->|"dispatches agents"| node_manager
node_workflow_tool -->|"runs scripts"| node_workflow_runtime
node_workflow_runtime -->|"extracts metadata"| node_workflow_meta
node_workflow_runtime -->|"records progress"| node_workflow_progress
node_workflow_runtime -.->|"updates task"| node_workflow_task
node_workflow_ui -->|"inspects runs"| node_workflow_task
node_workflow_ui -->|"opens agent view"| node_viewer
node_entry -->|"registers workflow UI"| node_workflow_ui
node_mentions -->|"resolves agent actions"| node_manager
node_mention_ui -->|"uses agent state"| node_manager
node_invocation -->|"configures spawning"| node_manager

click node_entry "https://github.com/tintinweb/pi-subagents/blob/master/src/index.ts"
click node_types "https://github.com/tintinweb/pi-subagents/blob/master/src/agent-types.ts"
click node_custom "https://github.com/tintinweb/pi-subagents/blob/master/src/custom-agents.ts"
click node_invocation "https://github.com/tintinweb/pi-subagents/blob/master/src/invocation-config.ts"
click node_manager "https://github.com/tintinweb/pi-subagents/blob/master/src/agent-manager.ts"
click node_runner "https://github.com/tintinweb/pi-subagents/blob/master/src/agent-runner.ts"
click node_nested "https://github.com/tintinweb/pi-subagents/blob/master/src/nested-tools.ts"
click node_model "https://github.com/tintinweb/pi-subagents/blob/master/src/model-resolver.ts"
click node_mentions "https://github.com/tintinweb/pi-subagents/blob/master/src/mention.ts"
click node_mention_ui "https://github.com/tintinweb/pi-subagents/blob/master/src/ui/agent-mention.ts"
click node_widget "https://github.com/tintinweb/pi-subagents/blob/master/src/ui/agent-widget.ts"
click node_fleet "https://github.com/tintinweb/pi-subagents/blob/master/src/ui/fleet-list.ts"
click node_viewer "https://github.com/tintinweb/pi-subagents/blob/master/src/ui/conversation-viewer.ts"
click node_scheduler "https://github.com/tintinweb/pi-subagents/blob/master/src/schedule.ts"
click node_memory "https://github.com/tintinweb/pi-subagents/blob/master/src/memory.ts"
click node_worktree "https://github.com/tintinweb/pi-subagents/blob/master/src/worktree.ts"
click node_rpc "https://github.com/tintinweb/pi-subagents/blob/master/src/cross-extension-rpc.ts"
click node_workflow_tool "https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/host.ts"
click node_workflow_runtime "https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/runtime.ts"
click node_workflow_meta "https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/meta.ts"
click node_workflow_progress "https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/progress.ts"
click node_workflow_task "https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/task.ts"
click node_workflow_ui "https://github.com/tintinweb/pi-subagents/blob/master/src/ui/workflow-menu.ts"
click node_usage "https://github.com/tintinweb/pi-subagents/blob/master/src/usage.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_entry,node_types,node_custom,node_invocation,node_user toneBlue
class node_manager,node_runner,node_nested,node_model,node_usage toneAmber
class node_mentions,node_mention_ui,node_widget,node_fleet,node_viewer toneMint
class node_workflow_tool,node_workflow_runtime,node_workflow_meta,node_workflow_progress,node_workflow_task,node_workflow_ui toneRose
class node_scheduler,node_memory,node_worktree,node_rpc,node_pi toneIndigo
```

## Components

### Extension and agents

- [Extension entry](https://github.com/tintinweb/pi-subagents/blob/master/src/index.ts): `src/index.ts`
- [Agent registry](https://github.com/tintinweb/pi-subagents/blob/master/src/agent-types.ts): `src/agent-types.ts`
- [Custom agents](https://github.com/tintinweb/pi-subagents/blob/master/src/custom-agents.ts): `src/custom-agents.ts`
- [Invocation config](https://github.com/tintinweb/pi-subagents/blob/master/src/invocation-config.ts): `src/invocation-config.ts`

### Agent runtime

- [Agent manager](https://github.com/tintinweb/pi-subagents/blob/master/src/agent-manager.ts): `src/agent-manager.ts`
- [Session runner](https://github.com/tintinweb/pi-subagents/blob/master/src/agent-runner.ts): `src/agent-runner.ts`
- [Nested tools](https://github.com/tintinweb/pi-subagents/blob/master/src/nested-tools.ts): `src/nested-tools.ts`
- [Model resolution](https://github.com/tintinweb/pi-subagents/blob/master/src/model-resolver.ts): `src/model-resolver.ts`
- [Usage accounting](https://github.com/tintinweb/pi-subagents/blob/master/src/usage.ts): `src/usage.ts`

### User surfaces

- [Agent mentions](https://github.com/tintinweb/pi-subagents/blob/master/src/mention.ts): `src/mention.ts`
- [Mention UI](https://github.com/tintinweb/pi-subagents/blob/master/src/ui/agent-mention.ts): `src/ui/agent-mention.ts`
- [Agent widget](https://github.com/tintinweb/pi-subagents/blob/master/src/ui/agent-widget.ts): `src/ui/agent-widget.ts`
- [Fleet view](https://github.com/tintinweb/pi-subagents/blob/master/src/ui/fleet-list.ts): `src/ui/fleet-list.ts`
- [Conversation viewer](https://github.com/tintinweb/pi-subagents/blob/master/src/ui/conversation-viewer.ts): `src/ui/conversation-viewer.ts`

### Workflow orchestration

- [Workflow tool](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/host.ts): `src/workflow/host.ts`
- [Workflow runtime](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/runtime.ts): `src/workflow/runtime.ts`
- [Workflow metadata](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/meta.ts): `src/workflow/meta.ts`
- [Workflow progress](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/progress.ts): `src/workflow/progress.ts`
- [Workflow task](https://github.com/tintinweb/pi-subagents/blob/master/src/workflow/task.ts): `src/workflow/task.ts`
- [Workflow UI](https://github.com/tintinweb/pi-subagents/blob/master/src/ui/workflow-menu.ts): `src/ui/workflow-menu.ts`

### Persistence and integrations

- [Scheduler](https://github.com/tintinweb/pi-subagents/blob/master/src/schedule.ts): `src/schedule.ts`
- [Agent memory](https://github.com/tintinweb/pi-subagents/blob/master/src/memory.ts): `src/memory.ts`
- [Worktree isolation](https://github.com/tintinweb/pi-subagents/blob/master/src/worktree.ts): `src/worktree.ts`
- [Extension RPC](https://github.com/tintinweb/pi-subagents/blob/master/src/cross-extension-rpc.ts): `src/cross-extension-rpc.ts`

### Other components

- **Pi user**
- **Pi host**

## Connections

- Pi user → Extension entry: invokes (evidence: `README.md`)
- Pi host → Extension entry: loads extension (evidence: `README.md`)
- Extension entry → Agent manager: registers agents (evidence: `src/index.ts`)
- Extension entry → Agent registry: uses registry (evidence: `src/index.ts`)
- Extension entry → Scheduler: registers schedules (evidence: `src/index.ts`)
- Extension entry → Workflow tool: registers workflow (evidence: `src/index.ts`)
- Extension entry → Agent mentions: integrates mentions (evidence: `src/index.ts`)
- Extension entry → Extension RPC: registers RPC (evidence: `src/index.ts`)
- Custom agents → Agent registry: provides definitions (evidence: `src/agent-types.ts`)
- Agent manager → Session runner: starts or resumes (evidence: `src/agent-manager.ts`)
- Agent manager → Worktree isolation: creates and cleans (evidence: `src/agent-manager.ts`)
- Agent manager → Usage accounting: records usage (evidence: `src/agent-manager.ts`)
- Session runner → Agent registry: gets agent config (evidence: `src/agent-runner.ts`)
- Session runner → Agent memory: loads memory (evidence: `src/agent-runner.ts`)
- Nested tools → Agent registry: resolves child types (evidence: `src/nested-tools.ts`)
- Nested tools → Agent manager: delegates child runs (evidence: `src/nested-tools.ts`)
- Nested tools → Invocation config: resolves options (evidence: `src/nested-tools.ts`)
- Nested tools → Model resolution: resolves model (evidence: `src/nested-tools.ts`)
- Extension entry → Nested tools: enables delegation (evidence: `src/index.ts`)
- Extension entry → Agent widget: registers widget (evidence: `src/index.ts`)
- Extension entry → Fleet view: registers fleet view (evidence: `src/index.ts`)
- Extension entry → Mention UI: registers mention UI (evidence: `src/index.ts`)
- Fleet view → Conversation viewer: opens conversation (evidence: `src/ui/fleet-list.ts`)
- Conversation viewer → Agent widget: reuses rendering (evidence: `src/ui/conversation-viewer.ts`)
- Scheduler → Agent manager: starts scheduled agents (evidence: `src/schedule.ts`)
- Scheduler → Session runner: runs agent (evidence: `src/schedule.ts`)
- Workflow tool → Agent manager: dispatches agents (evidence: `src/workflow/host.ts`)
- Workflow tool → Workflow runtime: runs scripts (evidence: `src/workflow/host.ts`)
- Workflow runtime → Workflow metadata: extracts metadata (evidence: `src/workflow/runtime.ts`)
- Workflow runtime → Workflow progress: records progress (evidence: `src/workflow/runtime.ts`)
- Workflow runtime → Workflow task: updates task (evidence: `src/workflow/task.ts`)
- Workflow UI → Workflow task: inspects runs (evidence: `src/ui/workflow-menu.ts`)
- Workflow UI → Conversation viewer: opens agent view (evidence: `src/ui/workflow-menu.ts`)
- Extension entry → Workflow UI: registers workflow UI (evidence: `src/index.ts`)
- Agent mentions → Agent manager: resolves agent actions (evidence: `src/agent-manager.ts`)
- Mention UI → Agent manager: uses agent state (evidence: `src/ui/agent-mention.ts`)
- Invocation config → Agent manager: configures spawning (evidence: `src/index.ts`)