microsoft/PilotSwarm

Latest recorded source activity: November 4, 2026 at 05:45

SkillsMP catalog refreshed: November 5, 2026 at 19:57

skills collected: 50

GitHub stars: 14
GitHub forks: 7

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/microsoft/PilotSwarm.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# PilotSwarm > **Experimental** — This project is under active development and not yet ready for production use. APIs may change without notice. An open-source durable execution runtime for [GitHub Copilot SDK](https://github.com/github/copilot-sdk) agents. Crash recovery, durable timers, session dehydration, and multi-node scaling — powered by [duroxide](https://github.com/microsoft/duroxide). Just add a connection string. See [CHANGELOG.md](CHANGELOG.md) for release notes. ## Builder Agents If you are building layered apps on top of PilotSwarm, this repo now ships distributable builder-agent templates you can copy into your own repository: - [Builder Agent Templates](./docs/developer/building/builder-agents.md) - [DevOps Command Center Sample](examples/devops-command-center/README.md) - [Horizon Harvester Sample](examples/horizon-harvester/README.md) — optional enhanced facts + knowledge graph These are not active agents in this repo. They are templates intended to be copied into a user repo under `.github/agents/` and `.github/skills/`. <img width="630" height="239" alt="image" src="https://github.com/user-attachments/assets/807cdf40-b228-41c1-bfe2-8100230544c9" /> ## Quick Start ### Run from source Use Node.js 24.22.1 LTS (or a newer patched 24.x / Node 26.12.1+) and a PostgreSQL instance you can access. Build the repository, copy the example configuration, then set `DATABASE_URL` and a model provider credential such as `GITHUB_TOKEN` in `.env`: ```bash git clone https://github.com/microsoft/PilotSwarm.git cd PilotSwarm npm ci npm run build cp .env.example .env cp .model_providers.example.json .model_providers.json # Edit .env and .model_providers.json for your PostgreSQL and model provider. ./run.sh local --db ``` The local command starts the TUI with embedded workers and uses the PostgreSQL connection configured in `.env`. See [Configuration](./docs/developer/reference/configuration.md) for the available settings. ### Package tarballs PilotSwarm distributes its three npm-format packages as `.tgz` assets on [GitHub Releases](https://github.com/microsoft/PilotSwarm/releases): `pilotswarm-sdk`, `pilotswarm-horizon-store`, and `pilotswarm`. After a release is selected, download and verify the matching tarballs using the [package installation guide](docs/quickstart/packages.md). Public downloads do not require repository membership. With GitHub CLI: ```bash gh release download vX.Y.Z --repo microsoft/PilotSwarm --pattern '*.tgz' --pattern SHA256SUMS --dir dist-tarballs (cd dist-tarballs && shasum -a 256 -c SHA256SUMS) npm install -g ./dist-tarballs/pilotswarm-sdk-X.Y.Z.tgz \ ./dist-tarballs/pilotswarm-horizon-store-X.Y.Z.tgz \ ./dist-tarballs/pilotswarm-X.Y.Z.tgz ``` The tarballs provide the three PilotSwarm packages; npm still resolves their other dependencies through your configured registry. Keep the release's `LICENSE` copyright and permission notice with redistributed copies. ### Use as a library in your own app Install the SDK tarball from a GitHub Release or use a checkout, then: ```typescript import { PilotSwarmClient, PilotSwarmWorker, defineTool } from "pilotswarm-sdk"; const getWeather = defineTool("get_weather", { description: "Get weather for a city", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"], }, handler: async ({ city }) => { const res = await fetch(`https://wttr.in/${city}?format=j1`); return await res.json(); }, }); // Worker runs LLM turns + tools. In production it lives in its own // long-running process (see "Durability" below); here we co-locate for demo. const worker = new PilotSwarmWorker({ store: process.env.DATABASE_URL }); worker.registerTools([getWeather]); await worker.start(); // Direct { store } client only because this single-process demo co-locates // worker and client. Apps talking to a real deployment use web mode // ({ apiUrl }) — see "Connect to a shared deployment" below. const client = new PilotSwarmClient({ store: process.env.DATABASE_URL }); await client.start(); const session = await client.createSession({ toolNames: ["get_weather"], systemMessage: "You are a weather assistant.", }); const response = await session.sendAndWait("What's the weather in NYC?"); console.log(response); await client.stop(); await worker.stop(); ``` A worker-registered tool can keep durable state per session without touching SDK internals. Its handler receives `invocation.facts`, bound to the calling session; the model never sees it, and nothing under the `tools/` key prefix is readable, writable, or searchable by any agent through the fact tools: ```typescript const proxy = defineTool("call_service", { description: "Call the external service for this session", parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] }, handler: async ({ query }, ctx) => { // Exact read, this session only. `{ scope: "root" }` binds to the spawn // tree's root session; `{ scope: "shared" }` is cluster-wide. let binding = await ctx.facts?.read("tools/my-service/binding"); if (!binding) { binding = await openExternalSession(ctx.durableSessionId); await ctx.facts?.store("tools/my-service/binding", binding); binding = await ctx.facts?.read("tools/my-service/binding"); // adopt the winner if two replicas raced } return callService(binding, query); }, }); ``` Reserve more prefixes for tools with `new PilotSwarmWorker({ reservedFactPrefixes: ["bindings/"] })`. Design: `docs/proposals/tool-context-facts-accessor.md`. PilotSwarm's own framework prompt and management plugins ship embedded inside `pilotswarm-sdk`. Apps layer their own `plugin/` directories on top; they do not need to copy the framework's built-in plugin text into their own repos. ### Connect to a shared deployment Already have a PilotSwarm deployment (see [Deploying to AKS](./docs/developer/deploy/aks.md))? The portal hosts a versioned Web API (HTTP `/api/v1` + WebSocket `/api/v1/ws`), so clients need the portal URL. From a built checkout, attach the TUI with: ```bash node packages/app/tui/bin/tui.js remote --api-url https://portal.example.com ``` Logs stream over the API. If the deployment uses Entra authentication, the TUI opens a browser for interactive sign-in. The `auth login|status|logout` subcommands on the same entry point manage that sign-in; use `--device-code` for headless hosts. Or connect from your own app with the SDK's web mode: ```typescript const client = new PilotSwarmClient({ apiUrl: "https://portal.example.com" }); await client.start(); // Session handles work exactly as in the demo above: send, sendAndWait, on, ... ``` `PilotSwarmManagementClient({ apiUrl })` works the same way. The zero-dependency [`pilotswarm-sdk/api`](packages/sdk/api/README.md) subpath speaks the same contract — see the [Web API Reference](docs/api/reference.md). Direct `{ store }` client construction remains available for worker/portal embedding and internal testing only; workers always use `{ store }`. ### Durability — recurring and long-waiting agents The single-process demo above doesn't show the durability story because the process exits as soon as the response lands. To run an agent that pauses for hours or runs a recurring schedule, the worker has to be a long-running process — typically: - one or more `PilotSwarmWorker`s in their own service (locally with `npm run worker`, in production on Kubernetes), and - clients (CLI, TUI, browser portal, or your app) connecting through the portal's [Web API](docs/api/reference.md) The agent then calls `wait(...)` for one-shot delays, or `cron(...)` for recurring schedules. Long waits dehydrate the session to blob storage; any worker rehydrates it when the timer fires. See [Architecture](./docs/architecture/system.md) and [Building SDK Apps](./docs/developer/building/sdk-apps.md) for the full pattern. ## What You Get | Feature | Copilot SDK | PilotSwarm | |---------|-------------|---------------------| | Tool calling | ✅ | ✅ Same `defineTool()` API | | Wait/pause | ❌ Blocks process | ✅ Durable timer — process shuts down, resumes later | | Crash recovery | ❌ Session lost | ✅ Automatic resume from last state | | Multi-node | ❌ Single process | ✅ Sessions migrate between worker pods | | Session persistence | ❌ In-memory | ✅ PostgreSQL + Azure Blob Storage | | Event streaming | ❌ Local only | ✅ Cross-process event subscriptions | ## How It Works The runtime automatically injects `wait` and `cron` tools into every session. When the LLM needs to pause or schedule recurring work: 1. **Short waits** (< 30s) — sleep in-process 2. **Long waits** (≥ 30s) — dehydrate session to blob storage → durable timer → any worker hydrates and continues 3. **Recurring schedules** — use `cron(...)` so the orchestration re-arms itself automatically after each cycle ``` Client PostgreSQL Worker Pods │ │ │ │── send("monitor hourly") ──→ │ │ │ │── orchestration queued ────→ │ │ │ │── runTurn (LLM) │ │ │── wait(3600) │ │ │── dehydrate → blob │ │── durable timer (1 hour) ──→ │ │ │ │── hydrate ← blob │ │ │── runTurn (LLM) │ │ │── response │←── result ──────────────────│ │ ``` ## Examples | Example | Description | Command | |---------|-------------|---------| | [Chat](packages/sdk/examples/chat.js) | Interactive console chat | `npm run chat` | | [TUI](packages/app/tui/bin/tui.js) | Multi-session terminal UI with logs | `npm run tui` | | [Worker](packages/sdk/examples/worker.js) | Headless worker for K8s | `npm run worker` | | [Tests](packages/sdk/test/sdk.test.js) | Automated test suite | `npm test` | ## Documentation Start with the documentation hub: - [Documentation Index](docs/README.md) Common entry points: - [User Guide](docs/user-guide/README.md) — scenario-based walkthroughs of the TUI and browser portal, simple to advanced - [Working On PilotSwarm](./docs/developer/contributing/working-on-pilotswarm.md) — contributors working on the SDK, TUI, providers, prompts, or orchestration - [Builder Agent Templates](./docs/developer/building/builder-agents.md) — copyable Copilot custom agents for users building apps on top of PilotSwarm - [Building Packages](./docs/building-agent-packages.md) — author uploadable skills, tools, MCP integrations, and agent workflows; zero-agent packages are valid; written to be handed straight to a coding assistant - [Building SDK Apps](./docs/developer/building/sdk-apps.md) — app developers using `PilotSwarmClient` and `PilotSwarmWorker` - [Building Agents For SDK Apps](./docs/developer/building/sdk-agents.md) — the clearest path for authoring `default.agent.md`, named agents, skills, and tools - [Building CLI Apps](./docs/developer/building/cli-apps.md) — plugin- and worker-module-driven apps on the shipped TUI - [Building Agents For CLI Apps](./docs/developer/building/cli-agents.md) — the CLI-focused agent-authoring guide - [Example Applications](./docs/developer/building/examples.md) — includes the DevOps Command Center sample for layered apps - [Web API Reference](docs/api/reference.md) — the versioned HTTP + WebSocket API (`/api/v1`) behind SDK web mode, `pilotswarm remote --api-url`, and the browser portal - [Configuration](./docs/developer/reference/configuration.md) — environment variables, blob storage, worker/client options - [Deploying to AKS](./docs/developer/deploy/aks.md) — Kubernetes deployment, scaling, and rolling updates - [Architecture](./docs/architecture/system.md) — internal design and runtime flow ## Requirements - Node.js 24.22.1+ within 24.x, or 26.12.1+ (CI and images pin 24.22.1 LTS) - PostgreSQL - GitHub Copilot access token (worker-side only) - Azure Blob Storage (optional, for session dehydration across nodes) ## License PilotSwarm is licensed under the [MIT license](LICENSE), retaining both Microsoft and original-contributor copyright notices. See the [source provenance record](docs/migration/README.md). ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com). When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. ## Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Loading the repository README…

Skills in this repository

classification pending

skill

occupation

description

updated

horizondb-idiosyncrasies

unclassified

Work with Azure HorizonDB (preview) — its AI/embedding features, extension allow-listing, AGE/pgvector/pg_durable quirks, and the connection/TLS gotchas discovered while bringing up the horizon-facts incubator. Use when connecting to a HorizonDB cluster,…

2026-11-04

portal-ux-testing

unclassified

Test a browser portal UX change in every layout mode it can meet - reading column on and off, live and after a reload, desktop and phone, Chromium and WebKit, with and without a canvas. Load before you call a portal layout, chat, session-list or canvas change…

2026-11-04

pilotswarm-tui

unclassified

Modify or extend the PilotSwarm terminal UI. Covers the shared-first architecture across ui-core, ui-react, and packages/app/tui, the current layout and visual conventions, prompt/question behavior, and the requirement to keep maintainer docs updated as the…

2026-10-17

pilotswarm-cli-builder

unclassified

Use when creating or updating a plugin-driven CLI/TUI app on top of PilotSwarm. Covers plugin.json branding, agent/skill layout, worker modules, keybinding/help sync, and the DevOps sample structure.

2026-10-17

pilotswarm-sdk-builder

unclassified

Use when creating or updating an SDK-first app on top of PilotSwarm. Covers the client/worker split, plugin layering, tool registration, tests, and the DevOps sample structure.

2026-10-15

azure-ps-test-runner-vm

unclassified

Create a throwaway Azure VM next to the HorizonDB server and run the full `./scripts/run-tests.sh --all-providers` suite on it, with credentials copied for one run only. Use when HorizonDB tests time out from a laptop far from the server, when GitHub runners…

2026-10-02

cost-latency-analysis

unclassified

How to compute model latency and estimated $ cost from PilotSwarm data. Read this before calling a model "slow" or "expensive": most slowness is orchestration overhead, and a cost is a guess unless it cites a published price card.

2026-09-30

graph-debug

unclassified

How to inspect and render the shared knowledge GRAPH (size, health, Mermaid, orphans, duplicates) and see what graph search a session ran. Read this before answering about the graph. Applies only when the graph tools are present.

2026-09-30

orchestration-session-lifecycle

unclassified

How a PilotSwarm session maps to a duroxide orchestration. Read this before concluding that an "idle" session's orchestration is broken, stopped or stuck: most idle sessions are healthy, dehydrated and waiting for their next stimulus.

2026-09-30

canvas-apps

unclassified

Interactive and SHARED canvas apps — page actions, the canvas_kv store, requests the page queues, the session's files and declared commands (canvas-ws), saving apps. Load before any canvas that takes input, uses files, or is shared.

2026-09-30

html-visuals

unclassified

How to build a self-contained HTML visual for the session canvas or the portal viewer — the sandbox contract, responsive rules, and the chart/dashboard idioms that survive it.

2026-09-30

notes

unclassified

Keep dated notes in your own folder, so later sessions can pick up where earlier ones stopped.

2026-09-29

share-a-file

unclassified

Share a file with other people through the shared folder, and find what others shared.

2026-09-29

pilotswarm-release

unclassified

Prepare and cut Microsoft PilotSwarm releases through GitHub Actions, with all-provider testing, package tarballs and automatic test deployment.

2026-09-21

add-test

unclassified

Add a new integration test to PilotSwarm test suite. Tests verify end-to-end flows through PilotSwarmClient, duroxide orchestration, and the Copilot SDK.

2026-09-18

debug-test

unclassified

Diagnose and fix a failing integration test in PilotSwarm. Covers the full call chain from PilotSwarmSession.sendAndWait through duroxide orchestration to CopilotSession, common failure patterns, and how to inspect orchestration and CMS state.

2026-09-18

pilotswarm-aks-deploy

unclassified

Deploy or inspect PilotSwarm on AKS; route managed Azure updates through Actions and explicit legacy targets through their operator recipes.

2026-09-18

pilotswarm-aks-reset

unclassified

Reset remote PilotSwarm state for AKS safely. Use when wiping the PilotSwarm database/blob state, clearing stale orchestration history, or recovering from namespace drift and replay/nondeterminism issues.

2026-09-18

pilotswarm-new-env-deploy

unclassified

Scaffold a PilotSwarm Azure environment or update an existing Bicep/GitOps stamp; route managed deployments through Actions.

2026-09-18

pilotswarm-portal-app-reg

unclassified

Use when bringing up a PilotSwarm portal stamp with `PORTAL_AUTH_PROVIDER=entra` and no existing `PORTAL_AUTH_ENTRA_CLIENT_ID`. Drives the Entra app-registration step (create app, configure redirect URIs, optionally define app roles + require assignment,…

2026-09-18

pilotswarm-portal-auth-assignments

unclassified

Use when adding or removing users / groups from the 'admin' or 'user' app roles on a PilotSwarm portal Entra app. Wraps deploy/scripts/auth/Set-PortalAuthAssignments.ps1 — idempotent, re-runnable, resolves UPNs / object ids / group display names. Required…

2026-09-18

pilotswarm-vpn-client-profile

unclassified

Use after deploying a PilotSwarm stamp with VPN_GATEWAY_ENABLED=true when an operator needs the Azure VPN client profile (azurevpnconfig.xml). Wraps deploy/scripts/auth/Get-VpnClientProfile.ps1 — downloads the gateway-issued profile zip via 'az network…

2026-09-18

pilotswarm-azure-deployer

unclassified

Use when packaging and deploying a PilotSwarm-based app to Azure or AKS. Covers remote worker parity, environment/config wiring, manifests, and rollout constraints.

2026-09-18

pilotswarm-hybrid-datastore

unclassified

Use when a PilotSwarm app needs stock PostgreSQL for runtime storage plus HorizonDB for enhanced facts, semantic/lexical search, and the knowledge graph. Covers env topology, horizonConfigFromEnv wiring, harvester agents, Azure secret/resource guidance, and…

2026-09-17

pilotswarm-knowledge-harvester

unclassified

Use when an SDK or CLI app needs to ingest external sources into durable, searchable knowledge and an open knowledge graph. Covers enabling the EnhancedFactStore + GraphStore providers, authoring a crawler:true agent, the crawl→graph→reader flow, ACL/scopeKey…

2026-09-17

pilotswarm-portal-builder

unclassified

Use when creating or updating a browser portal on top of PilotSwarm. Covers portal branding, plugin.json.portal, named-agent exposure, auth add-ons, and remote deployment wiring.

2026-09-17

pilotswarm-three-tier

unclassified

Reference for adding a Tier 3 worker AKS cluster to a PilotSwarm deployment. Covers provisioning, identity, Dockerfile changes, entrypoint, manifests, and verification.

2026-09-17

agent-repair-loop

unclassified

The order of operations for changing a live package safely — diagnose, patch, publish, converge, verify, roll back. Use whenever you are about to modify an agent package that something is already running on.

2026-09-15

agent-versioning

unclassified

Use when creating or editing PilotSwarm .agent.md files, prompt-layer manifests, or builder templates that generate agents. Covers schemaVersion/version frontmatter, SemVer bump guidance, and session.prompt_layers expectations.

2026-09-13

pilotswarm-agent-versioning

unclassified

Use when creating or editing PilotSwarm app agents in agents/*.agent.md. Covers schemaVersion/version frontmatter, version bump guidance, and prompt layer version visibility.

2026-09-13

debug-orchestration

unclassified

Diagnose and fix nondeterminism errors in the duroxide orchestration. Covers the replay model, common violations, and how to audit orchestration code for determinism.

2026-09-07

editorial-standards

unclassified

The editing pass order, the measure-don't-assert rule, and which surface answers which question.

2026-08-02

finance-research-standards

unclassified

Evidence, timestamp, numerical, and communication standards for stock and finance research.

2026-08-02

valuation-methods

unclassified

Compact valuation discipline for DCF, multiples, and scenario analysis.

2026-08-02

pilotswarm-architecture

unclassified

The shape of PilotSwarm — the pieces, how a turn flows through them, and the rules that constrain each layer.

2026-08-02

pilotswarm-azure-lessons

unclassified

Workarounds for common Azure issues: RBAC with Conditional Access, PostgreSQL region restrictions, Key Vault + CSI Driver setup.

2026-07-03

sweeper

unclassified

System maintenance agent that monitors and cleans up completed/zombie sessions.

2026-06-28

horizon-facts-eval-sweep

unclassified

Run and analyze the horizon-facts cross-model evaluation sweep (graph-grounded vs parametric+web closed-QA), sweeping harvester × query × judge models into a 3×3×3 score tensor with an LLM-generated bias-aware report. Use when collecting fresh sweep results,…

2026-06-24

resourcemgr

unclassified

Infrastructure and resource monitoring agent. Tracks compute, storage, database, and runtime footprint.

2026-05-20

schema-migration

unclassified

Add or modify a PostgreSQL schema migration for the CMS or Facts store. Covers creating migration functions, stored procedure changes, diff file generation, and TypeScript caller updates.

2026-04-17

Showing 40 of 50 collected skills.