---
slug: "pi-minions"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kalindudc/pi-minions@main/README.md"
repo: "https://github.com/kalindudc/pi-minions"
source_file: "README.md"
branch: "main"
---
# 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

```text
/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:

```ts
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

```json
{
  "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](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/getting-started.md)
- [Patterns](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/patterns.md)
- [Agents](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/agents.md)
- [Reference](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/reference.md)
- [Architecture](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/architecture.md)
- [Configuration](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/configuration.md)
- [E2E testing](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/e2e-testing.md)
- [Contributing](https://github.com/kalindudc/pi-minions/blob/HEAD/docs/contributing.md)

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.