pi-agent-mode

OpenCode-style default agent system for PI coding agent.

Define agents as markdown files with YAML frontmatter, select a default agent, and have all prompts processed through that agent inline — with full real-time streaming visibility. No subprocess subagents.

Features

• Markdown agent definitions — Simple YAML frontmatter + body
• Default agent at startup — Set in .pi/settings.json
• Keyboard shortcuts — Ctrl+Shift+M to cycle, Alt+S to search agents
• Visual indicator — Widget banner above editor shows active agent
• Model & tool restriction — Per-agent model and tool sets
• Agent search — /agent-search <query> or Alt+S to find agents by name, description, or body content
• Autonomous switching — set_agent tool for LLM-driven switches
• Session persistence — Active agent survives session resume

Install

pi install npm:pi-agent-mode

Or for project-local:

pi install npm:pi-agent-mode -l

Agent Definition Format

Create .md files in ~/.pi/agent/agents/ (global) or .pi/agents/ (project-local):

---
name: planner
description: Planning specialist - create detailed plans before implementation
model: anthropic/claude-sonnet-4
tools: read, bash, grep, find, ls
---
You are a PLANNING SPECIALIST. Your job is to deeply understand the problem and create a detailed implementation plan.

Rules:
- DO NOT make any changes. You cannot edit or write files.
- Read files IN FULL (no offset/limit) to get complete context.
- Explore thoroughly: grep for related code, find similar patterns.
- Ask clarifying questions if requirements are ambiguous.

Output:
- Create a structured plan with numbered steps.
- For each step: what to change, why, and potential risks.
- List files that will be modified.

Frontmatter Fields

Field	Required	Description
name	Yes	Agent identifier (used with /agent name)
description	No	Shown in selector and widget
model	No	provider/model-id format (e.g. anthropic/claude-sonnet-4)
tools	No	Comma-separated tool names to restrict to

The markdown body after frontmatter becomes the agent's system prompt instructions.

Usage

Commands

• /agent — Show selector to pick an agent
• /agent <name> — Switch directly to an agent
• /agent clear — Clear active agent, restore defaults
• /agents — List all available agents
• /agent-search <query> — Search agents by name, description, or body content

Keyboard

• Ctrl+Shift+M — Cycle through available agents
• Alt+S — Search agents (opens query prompt, then shows ranked results)

CLI

pi --agent planner

Settings

Set default agent in .pi/settings.json:

{
  "defaultAgent": "planner"
}

Autonomous Switching

The LLM can call the set_agent tool to switch agents programmatically:

{
  "agent": "implementer",
  "reason": "Planning complete, switching to implementation"
}

Searching Agents

The LLM can search for agents by content using the search_agents tool:

{
  "query": "planning",
  "limit": 5
}

This searches agent names, descriptions, models, tools, and body content, returning ranked results with relevance scores.

How It Works vs Subagents

Feature	pi-agent-mode	Subagents
Process	Inline (same process)	Separate subprocess
Visibility	Full streaming	Results after completion
Invocation	Default for all prompts	Explicit tool call
Switching	/agent or Ctrl+Shift+M	Must specify agent each time

License

MIT