[oo] pi-minions

Parallel subagent orchestration for pi. Your agents, your way.

Why pi-minions?

LLM coding agents hit a wall when tasks get complex: context windows fill up, work can't be parallelized, and one wrong turn wastes the entire session.

pi-minions solves this by letting your agent spawn minions — isolated sub-sessions that inherit the parent's configuration while keeping their own context window clean.

• Context hygiene — each minion gets a fresh context. Research, analysis, and exploration don't pollute the parent session.
• Parallelism — spawn multiple background or foreground minions for independent tasks. Wall-clock time equals the slowest task, not the sum.
• Safety — step limits, timeouts, graceful termination, and abort controls prevent runaway agents.
• Tool inheritance — minions automatically inherit authenticated extension tools from the parent session.
• Configurable — customize minion names, delegation hints, tool sync, spinner animations, and display via pi settings

Install

pi install npm:pi-minions

Quick start

Delegate a blocking task — the parent waits for the result:

/spawn Analyze error logs and identify root cause

// or just a prompt
Analyze errors logs and identify root cause using minions

Run tasks in parallel — fire-and-forget, results delivered automatically:

/spawn --bg Research React 19 server components
/spawn --bg Research Next.js 15 migration guide
/spawn --bg Research Vercel deployment best practices

// or just a prompt
Research React 19 server components with background agents

Use a named agent — reusable config with model, limits, and prompt:

/spawn --agent researcher What testing patterns does this project use?

// or a prompt
use our researcher agent to investigate testing patterns of this project

Manage running minions:

/minions                         # list running and pending
/minions show kevin              # detailed status + usage
/minions bg kevin                # detach slow foreground task
/minions steer kevin "Focus on src/ only"
/halt kevin                      # abort a minion

Configuration

// .pi/settings.json
{
  "pi-minions": {
    "minionNames": ["ares", "athena", "hermes", "hephaestus"],
    "delegation": {
      "enabled": true,
      "toolCallThreshold": 5,
      "hintIntervalMinutes": 15
    },
    "display": {
      "outputPreviewLines": 30,
      "observabilityLines": 8,
      "showStatusHints": false,
      "spinnerFrames": ["◐", "◓", "◑", "◒"]
    },
    "toolSync": {
      "enabled": true,
      "maxWait": 5
    },
    "interaction": {
      "timeout": 9000
    }
  }
}

For more details see Configuration

Documentation

| Doc | Description | |-----|-------------| | Getting started | Install → first spawn → background tasks → agents (~10 min) | | Patterns | "How do I...?" recipes for common workflows | | Agents | Creating, configuring, and discovering named agents | | Configuration | Customizing names, hints, display, and behavior | | Reference | Complete tool and command schemas, types | | Architecture | Module map, data flow diagrams, design decisions | | Contributing | Dev setup, project structure, testing, release process | | E2E testing | Writing and running agentic end-to-end tests | | Changelog | Version history |

| Concept | Description | |---------|-------------| | Minion | An isolated in-process pi session with its own context window | | Foreground | Blocks the parent until complete — use when you need the result to continue | | Background | Returns immediately, result auto-delivered on completion | | Agent | Named markdown config (frontmatter + system prompt) for reusable minion behavior | | Steering | Inject a message into a running minion's context to redirect focus | | Live detach | Move a foreground minion to background mid-execution without interruption |

License

MIT — see LICENSE.md