pi-your-subagents

A pi extension that provides configurable, user-extensible subagents using agent definitions from the Awesome Agents Library.

Agent Sources

Agents are defined as .yml files in two locations:

Location	Path	Purpose
Global	~/.pi/agents/	Default agents sync here on first run, user can customize
Local	.pi/agents/	Project-specific overrides (takes precedence)

Local agents take precedence over global agents with the same name. Each .yml file contains the full agent definition: name, label, tools, system prompt, parameters, etc.

Agent definitions are loaded from the Awesome Agents Library. To add agents, copy .yml files from the library into ~/.pi/agents/ (global) or .pi/agents/ (per-project).

Features

• Background execution — Subagents run as pi child processes with live TUI progress widgets
• Local precedence — .pi/agents/agent.yml overrides ~/.pi/agents/agent.yml
• Agent control panel — Ctrl+Shift+1 to stop, cancel, or view running agents
• Activity timeout — Detects stuck processes (10 min) and marks as failed

Agent YAML Format

name: my-agent
label: My Agent
promptSnippet: One-line description for the parent LLM
promptGuidelines:
  - "When to use this agent..."
tools:
  - read
  - grep
model: ""            # empty = use parent model
extensions: []       # empty = no extensions
taskTemplate: "Do X: {param1}"
parameters:
  - name: param1
    description: "What param1 means"
    required: true
systemPrompt: >
  System prompt for the agent when spawned.

Installation

pi install npm:pi-your-subagents

Configuration

Extension settings live in ~/.pi/config/pi-your-subagents/settings.json:

{
  "keybinding": 1
}

Setting	Default	Description
keybinding	1	Number key for control panel (Ctrl+Shift+N)

License

Apache-2.0