pi-swarm-supervisor

A Pi package for supervising multiple coding agents at once.

Features

• managed side agents running in isolated pi --mode json subprocesses
• live status, warnings, last tool, last output, cost/context stats
• stuck detection heuristics
• analyzer side agents that recommend interventions
• action picker for multiple suggestions before applying
• one-click suggestion application
• session snapshot persistence via pi.appendEntry()
• role preset metadata persisted alongside snapshots
• auto-analysis when a worker becomes stuck
• transcript tail in the dashboard for the selected agent

Install from GitHub

Use either the packaged repo or the project-local .pi/extensions/swarm copy, not both at the same time, otherwise Pi will report command/tool conflicts.

pi install git:github.com/gvkhosla/pi-swarm-supervisor

Or try it without installing:

pi -e git:github.com/gvkhosla/pi-swarm-supervisor

Install from npm

When an npm token is configured and a release tag is pushed:

pi install npm:pi-swarm-supervisor

Install from a local checkout

pi install ./pi-swarm-supervisor

Or run once without installing:

pi -e ./pi-swarm-supervisor

Commands

• /swarm
• /swarm-start name@model :: task
• /swarm-start-role role@model :: task
• /swarm-stop <id|name|all>
• /swarm-restart <id|name>
• /swarm-analyze <id|name>
• /swarm-apply <id|name> [index]
• /swarm-roles
• /swarm-clear

Preset roles

• scout
• planner
• reviewer
• debugger
• worker

List them in Pi with:

• /swarm-roles

Override or add roles with config files:

• global: ~/.pi/agent/swarm-roles.json
• project: .pi/swarm-roles.json

Project roles override global roles with the same name.

Example:

{
  "researcher": {
    "description": "Deep repo research role",
    "tools": ["read", "grep", "find", "ls", "bash"],
    "systemPrompt": "You are RESEARCHER. Trace the code deeply and produce an evidence-backed writeup.",
    "model": "anthropic/claude-sonnet-4-5"
  },
  "scout": {
    "model": "openai/gpt-5.4-mini"
  }
}

Tools

• swarm_spawn
• swarm_spawn_role
• swarm_list
• swarm_stop
• swarm_analyze
• swarm_apply_suggestion

Quick demo

1. /swarm-start scout :: inspect this repo and find likely hotspots
2. /swarm-start worker :: try to solve bug X
3. /swarm
4. /swarm-analyze worker
5. /swarm-apply worker

Publish to npm

This repo includes GitHub Actions workflows for packaging and publishing.

One-time setup

1. Add an NPM_TOKEN secret in GitHub repo settings.
2. Make sure the package name is available on npm.
3. Bump version in package.json.

Publish flow

Create and push a tag:

git tag v0.2.0
git push origin v0.2.0

That triggers .github/workflows/publish.yml, which runs npm publish --access public --provenance.

Validate locally

npm pack

Suggested repo layout

Push the contents of this directory as the root of a GitHub repo:

pi-swarm-supervisor/
  package.json
  README.md
  extensions/
    swarm/
      index.ts
      dashboard.ts
      heuristics.ts
      prompts.ts
      runner.ts
      state.ts
      types.ts