pi-minions

pi-minions is a lightweight pi extension for foreground subagent delegation. It lets a parent agent spawn isolated minion sessions, stream progress, inspect live activity, and halt running minions when needed.

Features

• Foreground spawn tool for single minion delegation
• Batch foreground spawn via a tasks array for parallel independent work
• Named agent discovery from pi/agents and minions directories
• Ephemeral built-in minions when no agent is specified
• halt for aborting running foreground minions
• list_minions and show_minion for current session visibility
• /minions and /minions show <id|name> for live activity viewing
• learn_minions, /minions learn, and /minions skill for built-in usage guidance

Background minions, live detaching, and user steering commands are not part of the public surface.

Quick start

/spawn Summarize the test failures in this repository
/spawn Inspect src/tools and report risks --model claude-haiku
/minions
/minions show kevin
/minions learn
/halt kevin

For LLM-callable tools, use:

spawn({ task: "Audit the auth module" })
spawn({ tasks: [{ task: "Read src" }, { task: "Read test" }] })
list_agents({})
list_minions({})
show_minion({ target: "kevin" })
halt({ id: "all" })
learn_minions({})

Configuration

{
  "pi-minions": {
    "minionNames": ["kevin", "stuart", "bob"],
    "allowEphemeral": true,
    "display": {
      "outputPreviewLines": 20,
      "observabilityLines": 6,
      "showStatusHints": true,
      "spinnerFrames": ["[oo]", "[o-]", "[--]", "[-o]"]
    },
    "toolSync": {
      "enabled": true,
      "maxWait": 5
    }
  }
}

Documentation

• Getting started
• Patterns
• Agents
• Reference
• Architecture
• Configuration
• E2E testing
• Contributing

The npm package ships source plus standard npm always-included files. The docs/ directory and changelog file are intentionally not included in the published tarball.