pi.agents

Pi extension plugin for agent selection, switching, and multi-agent workflows.

Overview

This Pi extension enables users to visually select and switch between specialized agents (personas defined by prompt templates), and to run automated multi-agent workflows. The extension tracks the active agent in the status bar and handles lightweight same-session agent switches with full conversation history preserved.

Features

• Visual agent selection — Browse and select agents via a picker UI
• Lightweight agent switching — Switch agents within the same session, preserving full history
• Autonomous handoffs — Agents can transfer control to another agent via the switch_agent tool
• Agent discovery — Discover available agents and delegates via list_agents and list_delegates tools
• Delegates — Invoke specialized agents as scoped delegates via the delegate_agent tool and resume the caller's workflow
• Role-based capabilities — Configure agents as leaders, delegates, or both via frontmatter
• Workflows — Define multi-agent pipelines as YAML files with linear, conditional, and pause steps
• Ad-hoc chains — Run quick linear agent sequences without creating a YAML file
• Session persistence — Active agent and workflow state are restored across sessions

Prerequisites

• Pi coding agent installed
• Node.js 18 or higher

Quick Start

1. Install the extension

# Project-local (recommended)
git clone https://github.com/andrewhowdencom/pi.agents.git .pi/extensions/pi-agents
cd .pi/extensions/pi-agents
npm install

# Or reload Pi to auto-discover

2. Create your first agent

mkdir -p .pi/agents
cat > .pi/agents/helper.md << 'EOF'
---
description: "A helpful general-purpose assistant"
---

You are a helpful assistant focused on answering questions and providing guidance.
EOF

3. Select the agent

In Pi, run:

/agent

Select helper from the picker. The agent name appears in the status bar.

Documentation

Full documentation is available at https://andrewhowdencom.github.io/pi.agents/.

Resource	Description
Getting Started Tutorial	Step-by-step first-time setup
Installation Guide	Detailed installation options
Switching Agents	Manual, autonomous, and subagent patterns
Creating Workflows	How to write workflow YAML files
Command Reference	All commands and tools
Workflow YAML Reference	Complete workflow schema
Agent Frontmatter	Agent frontmatter and role configuration
Architecture	How the extension works internally

License

See LICENSE for details.