How microsoft/pilotswarm works
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: router.js Portal Web API · session-manager.ts Worker process · managed-session.ts Managed sessions · storage-providers.ts Storage providers
Components 22
Client surfaces
- TUI client
packages/app/tui/src/app.js - Browser portal
packages/app/web/src/App.jsx - SDK client
packages/sdk/src/session-manager.ts - Web SDK client
packages/sdk/src/web/web-management-client.ts - MCP server
packages/app/mcp/src/server.ts
Execution runtime
- Worker process
packages/sdk/src/session-manager.ts - Managed sessions
packages/sdk/src/managed-session.ts - Durable orchestration
packages/sdk/src/orchestration/runtime.ts - Model providers
packages/sdk/src/model-providers.ts - Agent tools
packages/sdk/src/capability-runtime.ts - Agent packages
packages/sdk/src/agent-manager-tools.ts
Persistence and knowledge
- Session catalog
packages/sdk/src/cms.ts - Session state store
packages/sdk/src/session-store.ts - Storage providers
packages/sdk/src/storage-providers.ts - Facts store
packages/sdk/src/facts-store.ts - Knowledge graph
packages/sdk/src/graph-store.ts - Horizon store
packages/horizon-store/src/horizon-store.ts
Portal and integrations
- Portal Web API
packages/app/web/api/router.js - Portal server
packages/app/web/server.js - Authentication
packages/app/web/auth/authz/engine.js - Portal runtime
packages/app/web/runtime.js
Other components
- User or app
Connections 24
- User or app → TUI client: uses
README.md - User or app → Browser portal: uses
README.md - User or app → SDK client: calls
README.md - TUI client → Portal Web API: connects to
README.md - Browser portal → Portal Web API: uses
- Web SDK client → Portal Web API: calls
README.md - MCP server → Portal Web API: connects to
- Portal server → Portal Web API: mounts
packages/app/web/server.js - Portal server → Portal runtime: uses
packages/app/web/server.js - Portal server → Authentication: authorizes with
packages/app/web/server.js - SDK client → Worker process: co-locates with
README.md - Worker process → Managed sessions: runs turns
README.md - Managed sessions → Model providers: calls
packages/sdk/src/session-manager.ts - Managed sessions → Agent tools: uses
packages/sdk/src/session-manager.ts - Worker process → Durable orchestration: runs durable work
README.md - Durable orchestration → Session state store: persists state
README.md - Durable orchestration → Session catalog: tracks lifecycle
packages/sdk/src/cms.ts - Storage providers → Session catalog: creates
packages/sdk/src/storage-providers.ts - Storage providers → Facts store: creates
packages/sdk/src/storage-providers.ts - Storage providers → Knowledge graph: creates
packages/sdk/src/storage-providers.ts - Managed sessions → Agent packages: manages packages
- Facts store → Knowledge graph: queries graph
packages/sdk/src/facts-store.ts - Horizon store → Facts store: enhances facts
- Worker process → Session state store: dehydrates sessions
README.md