# microsoft/pilotswarm architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/pilotswarm
- Repository: https://github.com/microsoft/pilotswarm

## Overview

PilotSwarm is a durable execution runtime for GitHub Copilot SDK agents, with a portal, CLI/TUI, and SDK for clients and workers. The documented workflow is: a client creates a session and submits a turn; a worker runs the agent and tools, persisting session state so timers, crashes, and worker changes can be recovered. The graph also includes the Web API, management, agent-package, facts, and knowledge-graph surfaces. Some subsystem links are documented in the README; unsampled implementation details are not inferred.

Main entry points: [`packages/app/web/api/router.js`](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/api/router.js) (Portal Web API), [`packages/sdk/src/session-manager.ts`](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-manager.ts) (Worker process), [`packages/sdk/src/managed-session.ts`](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/managed-session.ts) (Managed sessions), [`packages/sdk/src/storage-providers.ts`](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/storage-providers.ts) (Storage providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client surfaces"]
  node_tui["TUI client<br/>[app.js]"]
  node_webui["Browser portal<br/>[App.jsx]"]
  node_sdkclient["SDK client<br/>[session-manager.ts]"]
  node_webclient["Web SDK client"]
  node_mcp["MCP server<br/>[server.ts]"]
end

subgraph group_runtime["Execution runtime"]
  node_worker["Worker process<br/>[session-manager.ts]"]
  node_session["Managed sessions<br/>[managed-session.ts]"]
  node_orchestration["Durable orchestration<br/>[runtime.ts]"]
  node_models["Model providers<br/>[model-providers.ts]"]
  node_tools["Agent tools"]
  node_agentpackages["Agent packages"]
end

subgraph group_data["Persistence and knowledge"]
  node_catalog[("Session catalog<br/>[cms.ts]")]
  node_sessionstore[("Session state store<br/>[session-store.ts]")]
  node_storage["Storage providers"]
  node_facts[("Facts store<br/>[facts-store.ts]")]
  node_graph[("Knowledge graph<br/>[graph-store.ts]")]
  node_horizon[("Horizon store<br/>[horizon-store.ts]")]
end

subgraph group_portal["Portal and integrations"]
  node_api["Portal Web API<br/>[router.js]"]
  node_server["Portal server<br/>[server.js]"]
  node_auth["Authentication<br/>[engine.js]"]
  node_runtime["Portal runtime<br/>[runtime.js]"]
end

node_user(("User or app"))

node_user -->|"uses"| node_tui
node_user -->|"uses"| node_webui
node_user -->|"calls"| node_sdkclient
node_tui -->|"connects to"| node_api
node_webui -.->|"uses"| node_api
node_webclient -->|"calls"| node_api
node_mcp -->|"connects to"| node_api
node_server -->|"mounts"| node_api
node_server -->|"uses"| node_runtime
node_server -->|"authorizes with"| node_auth
node_sdkclient -->|"co-locates with"| node_worker
node_worker -->|"runs turns"| node_session
node_session -->|"calls"| node_models
node_session -->|"uses"| node_tools
node_worker -->|"runs durable work"| node_orchestration
node_orchestration -->|"persists state"| node_sessionstore
node_orchestration -->|"tracks lifecycle"| node_catalog
node_storage -->|"creates"| node_catalog
node_storage -->|"creates"| node_facts
node_storage -->|"creates"| node_graph
node_session -->|"manages packages"| node_agentpackages
node_facts -->|"queries graph"| node_graph
node_horizon -.->|"enhances facts"| node_facts
node_worker -->|"dehydrates sessions"| node_sessionstore

click node_tui "https://github.com/microsoft/pilotswarm/blob/main/packages/app/tui/src/app.js"
click node_webui "https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/src/App.jsx"
click node_sdkclient "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-manager.ts"
click node_webclient "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/web/web-management-client.ts"
click node_mcp "https://github.com/microsoft/pilotswarm/blob/main/packages/app/mcp/src/server.ts"
click node_api "https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/api/router.js"
click node_server "https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/server.js"
click node_auth "https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/auth/authz/engine.js"
click node_runtime "https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/runtime.js"
click node_worker "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-manager.ts"
click node_session "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/managed-session.ts"
click node_orchestration "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/orchestration/runtime.ts"
click node_models "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/model-providers.ts"
click node_tools "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/capability-runtime.ts"
click node_agentpackages "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/agent-manager-tools.ts"
click node_catalog "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/cms.ts"
click node_sessionstore "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-store.ts"
click node_storage "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/storage-providers.ts"
click node_facts "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/facts-store.ts"
click node_graph "https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/graph-store.ts"
click node_horizon "https://github.com/microsoft/pilotswarm/blob/main/packages/horizon-store/src/horizon-store.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_tui,node_webui,node_sdkclient,node_webclient,node_mcp,node_user toneBlue
class node_worker,node_session,node_orchestration,node_models,node_tools,node_agentpackages toneAmber
class node_catalog,node_sessionstore,node_storage,node_facts,node_graph,node_horizon toneMint
class node_api,node_server,node_auth,node_runtime toneRose
```

## Components

### Client surfaces

- [TUI client](https://github.com/microsoft/pilotswarm/blob/main/packages/app/tui/src/app.js): `packages/app/tui/src/app.js`
- [Browser portal](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/src/App.jsx): `packages/app/web/src/App.jsx`
- [SDK client](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-manager.ts): `packages/sdk/src/session-manager.ts`
- [Web SDK client](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/web/web-management-client.ts): `packages/sdk/src/web/web-management-client.ts`
- [MCP server](https://github.com/microsoft/pilotswarm/blob/main/packages/app/mcp/src/server.ts): `packages/app/mcp/src/server.ts`

### Execution runtime

- [Worker process](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-manager.ts): `packages/sdk/src/session-manager.ts`
- [Managed sessions](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/managed-session.ts): `packages/sdk/src/managed-session.ts`
- [Durable orchestration](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/orchestration/runtime.ts): `packages/sdk/src/orchestration/runtime.ts`
- [Model providers](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/model-providers.ts): `packages/sdk/src/model-providers.ts`
- [Agent tools](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/capability-runtime.ts): `packages/sdk/src/capability-runtime.ts`
- [Agent packages](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/agent-manager-tools.ts): `packages/sdk/src/agent-manager-tools.ts`

### Persistence and knowledge

- [Session catalog](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/cms.ts): `packages/sdk/src/cms.ts`
- [Session state store](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/session-store.ts): `packages/sdk/src/session-store.ts`
- [Storage providers](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/storage-providers.ts): `packages/sdk/src/storage-providers.ts`
- [Facts store](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/facts-store.ts): `packages/sdk/src/facts-store.ts`
- [Knowledge graph](https://github.com/microsoft/pilotswarm/blob/main/packages/sdk/src/graph-store.ts): `packages/sdk/src/graph-store.ts`
- [Horizon store](https://github.com/microsoft/pilotswarm/blob/main/packages/horizon-store/src/horizon-store.ts): `packages/horizon-store/src/horizon-store.ts`

### Portal and integrations

- [Portal Web API](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/api/router.js): `packages/app/web/api/router.js`
- [Portal server](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/server.js): `packages/app/web/server.js`
- [Authentication](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/auth/authz/engine.js): `packages/app/web/auth/authz/engine.js`
- [Portal runtime](https://github.com/microsoft/pilotswarm/blob/main/packages/app/web/runtime.js): `packages/app/web/runtime.js`

### Other components

- **User or app**

## Connections

- User or app → TUI client: uses (evidence: `README.md`)
- User or app → Browser portal: uses (evidence: `README.md`)
- User or app → SDK client: calls (evidence: `README.md`)
- TUI client → Portal Web API: connects to (evidence: `README.md`)
- Browser portal → Portal Web API: uses
- Web SDK client → Portal Web API: calls (evidence: `README.md`)
- MCP server → Portal Web API: connects to
- Portal server → Portal Web API: mounts (evidence: `packages/app/web/server.js`)
- Portal server → Portal runtime: uses (evidence: `packages/app/web/server.js`)
- Portal server → Authentication: authorizes with (evidence: `packages/app/web/server.js`)
- SDK client → Worker process: co-locates with (evidence: `README.md`)
- Worker process → Managed sessions: runs turns (evidence: `README.md`)
- Managed sessions → Model providers: calls (evidence: `packages/sdk/src/session-manager.ts`)
- Managed sessions → Agent tools: uses (evidence: `packages/sdk/src/session-manager.ts`)
- Worker process → Durable orchestration: runs durable work (evidence: `README.md`)
- Durable orchestration → Session state store: persists state (evidence: `README.md`)
- Durable orchestration → Session catalog: tracks lifecycle (evidence: `packages/sdk/src/cms.ts`)
- Storage providers → Session catalog: creates (evidence: `packages/sdk/src/storage-providers.ts`)
- Storage providers → Facts store: creates (evidence: `packages/sdk/src/storage-providers.ts`)
- Storage providers → Knowledge graph: creates (evidence: `packages/sdk/src/storage-providers.ts`)
- Managed sessions → Agent packages: manages packages
- Facts store → Knowledge graph: queries graph (evidence: `packages/sdk/src/facts-store.ts`)
- Horizon store → Facts store: enhances facts
- Worker process → Session state store: dehydrates sessions (evidence: `README.md`)
