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
• Model tiers — map fast / standard / advanced to real models in config; the agent is guided to pick the configured model per task
• 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
timeout: 300
---

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.

max_turns and timeout (wall-clock seconds, 0 = unlimited) lock their limits for the agent type: a frontmatter value wins over the per-call parameter.

Prompt mode

prompt_mode decides how the agent body relates to the system prompt of the agent that invokes it:

replace is a clean room on purpose: nothing rendered for the caller reaches the agent — not its prompt, tool list or tool guidelines, not the project context files (AGENTS.md), not SYSTEM.md / APPEND_SYSTEM.md — because those describe a different toolset and role. It gets no tool list of its own either: the prompt carries no tool list and no tool guidelines, while the harness still passes the agent's tools to the model directly. That is why prompt mode never widens or narrows capabilities: only the tools allowlist does that. Anything the agent needs — including house rules such as language or tool preferences, and tool-usage conventions — must be restated in its body.

append is the other side of that line: neither mode inherits the caller's tool list. append gets the base prompt the harness renders from the agent's own tool set (its own tools and guidelines), then the bridge and your body are appended.

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.

Model Tiers

Instead of hardcoding model IDs, you can map capability tiers to concrete models in subagents.json. The mapping feeds the subagent tool's prompt guidelines, which tell the agent which model to pass via the model parameter — there is no model_tier tool parameter.

The mapping lives in subagents.json — ~/.pi/agent/subagents.json (global) and <cwd>/.pi/subagents.json (project). The two layers merge per tier, so a project can override one tier without restating the others:

{
  "modelTiers": {
    "fast": "deepseek-flash",
    "standard": "deepseek-flash",
    "advanced": "qwen3.8-max"
  }
}

Because the agent copies the mapped value into model, it goes through the same resolver as any other model value: provider/modelId and fuzzy names (e.g. "haiku") both work. Tiers without a mapping are omitted from the guidelines — nothing is silently substituted for them. If an agent type pins model in its frontmatter, that model always wins.

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.

The viewer follows the live tail: the newest lines stay pinned to the bottom until you scroll up. Upward keys (↑/k, PgUp/shift+up, Home) unconditionally pause following — streaming can add lines between a keypress and the render, so a "was I at the bottom?" test against that stale value would snap a viewport you just left back down. A downward key that lands on the bottom (↓/j, PgDn/shift+down) resumes following, and end jumps to the bottom and force-resumes; q/Esc closes. The paused state has no visual indicator (the footer keeps showing <n> lines · <pct>% and the key hints).

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. The same files also hold the modelTiers mapping; saving other settings preserves it.

defaultMaxTurns / defaultTimeoutSeconds sit at the bottom of the precedence chain: agent frontmatter wins over the per-call parameter, which wins over these defaults.

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