pi-mainagent/README.md

pi-mainagent

A pi package that brings agent personas to your coding agent — the same idea as claude --agent <name> in Claude Code, or starting an opencode session with a pre-selected agent.

Note: pi does not ship this feature natively. Out of the box there is no way to define reusable agent personas or start pi with a pre-selected agent — this package fills that gap.

Install it, define personas as Markdown files in ~/.pi/agent/agents/, and switch between them at any time with /mainagent. Each persona sets its own model, thinking level, and tool filters, and your selection is persisted — so the next pi session starts directly with your active agent, no flags needed.

Why

As a developer

• I want to switch between agents with a single command (/mainagent <name>), so I can use the right model and prompt for each task without restarting pi.
• I want my agent choice to be remembered across sessions, so I don't have to re-select it (or pass flags) every time I start pi.
• I want to define personas as plain Markdown files, so I can create them, version them in git, and share them without learning a new config format.

As a user

• I want to deactivate the agent (/mainagent off) and get back exactly the previous settings, so I can experiment without fear of leaving my session in an altered state.

Install

pi install npm:pi-mainagent

Or try it without installing:

pi -e npm:pi-mainagent

Usage

pi                    # starts with your last selected agent (persisted selection)
/mainagent            # interactive menu (TUI)
/mainagent <name>     # activate a persona
/mainagent off        # deactivate and restore the session defaults

Like claude --agent <name>, but the choice sticks: pick an agent once and every new session starts with it, until you switch or /mainagent off.

Agent definition files

Place Markdown files in ~/.pi/agent/agents/ with optional frontmatter:

---
name: reviewer
description: Careful code reviewer
model: anthropic/claude-sonnet-4-5
thinking: high
tools:
  - read
  - "ssh-manager_*"
excludeTools:
  - edit
---

Your persona prompt here (appended to pi's system prompt).

Supported frontmatter keys: name, description, model, thinking, tools, excludeTools, prompt (path to an external Markdown prompt file).

Notes

• Persona bodies are appended to pi's system prompt; the base prompt, project context and skills are never stripped.
• Model/thinking/tools changes are session-scoped: new sessions keep pi's configured defaults.
• /mainagent (bare) also lets you edit a definition's model, effort and description directly from the menu.