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