# pi-mainagent

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/D5G722BFYK)

A [pi](https://pi.dev) package that brings **agent personas** to your coding agent — the same idea as `claude --agent <name>` in Claude Code, or starting an [opencode](https://opencode.ai) 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

```bash
pi install npm:pi-mainagent
```

Or try it without installing:

```bash
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:

```markdown
---
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.