pi-subagents

A pi extension providing a focused, in-process sub-agent core — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on.

Features

• In-process & native — agents share the same pi runtime: same tool names, calling conventions, and UI patterns
• Parallel background agents — spawn multiple agents with automatic queuing (configurable concurrency, default 4)
• Live widget UI — persistent widget showing animated spinners, live tool activity, token counts, and colored status icons
• Custom agent types — define agents in .pi/agents/<name>.md with YAML frontmatter: system prompts, model, thinking, tools
• Mid-run steering — inject messages into running agents to redirect work without restarting
• Session resume — pick up where an agent left off, preserving full conversation context
• Graceful turn limits — agents get a "wrap up" warning before hard abort
• Case-insensitive types — "explore", "Explore", "EXPLORE" all work
• Fuzzy model selection — specify models by name ("haiku", "sonnet") instead of full IDs
• Context inheritance — optionally fork the parent conversation into a sub-agent
• Styled notifications — background results render as themed notification boxes
• Event bus — lifecycle events (subagents:created, started, completed, failed, steered, compacted) via pi.events

Install

pi install npm:@yandy0725/pi-subagents

Quick Start

The parent agent spawns sub-agents using the subagent tool:

subagent({
  subagent_type: "Explore",
  prompt: "Find all files that handle authentication",
  description: "Find auth files",
  run_in_background: true,
})

Foreground agents block until complete. Background agents return an ID immediately and notify on completion.

Default Agent Types

Custom Agents

Define custom agent types by creating .md files in .pi/agents/<name>.md:

---
description: Security Code Reviewer
tools: read, grep, find, bash
model: anthropic/claude-opus-4-6
thinking: high
max_turns: 30
---

You are a security auditor. Review code for vulnerabilities...

Agents are discovered from .pi/agents/<name>.md (project) and ~/.pi/agent/agents/<name>.md (global). Project-level overrides global.

Tools

subagent

Launch a sub-agent.

get_subagent_result

Check status and retrieve results from a background agent.

steer_subagent

Send a steering message to a running agent.

Commands

The session viewer renders the transcript read-only with Pi's own per-entry components and follows the running agent live. Tool results appear in Pi's collapsed form (summaries and previews), so a read call is represented by its call line only. The viewer has no expand key, so the "… to expand" hints some tools print do not apply here.

Concurrency

Background agents are subject to a configurable concurrency limit (default: 4). Excess agents queue automatically. Foreground agents bypass the queue.

Persistent Settings

Settings set via /subagents:settings persist in <cwd>/.pi/subagents.json (project) and can be overridden globally in ~/.pi/agent/subagents.json.

Events

Lifecycle events emitted via pi.events for other extensions to consume:

Development

npm run typecheck        # tsc --noEmit
npm run lint             # biome lint
npm test                 # vitest run

Acknowledgments

This project is a friendly fork of @gotgenes/pi-subagents by Chris Lasher, which began as a fork of tintinweb/pi-subagents. Thank you to all original authors for their work that made this package possible.

License

MIT