pi-agent-mode

Activates a configured Pi agent as a persistent mode in the current session. It switches the session to the agent's model, thinking level, and tool set, appends the agent's prompt to Pi's base instructions, and restores the pre-activation baseline when cleared. It does not spawn children and provides no delegated subagents.

Install

pi install npm:@pi-kaush/pi-agent-mode

Restart Pi or run /reload.

Usage

/agent               open an agent selector
/agent <name>        activate the named user or project agent
/agent none          restore the pre-activation model, thinking level, and tools
/agent off           same as /agent none

Agent definitions come from Markdown files in Pi's user agent directory (~/.pi/agent/agents/*.md) or the nearest project agents/ directory (project agents take precedence by name and are confirmed before activation unless the agent sets confirmProjectAgents: false).

Supported frontmatter:

---
name: reviewer # required
description: ... # required
emoji: 🔍 # optional, shown in the footer status
tools: read, grep # optional allowlist; unavailable tools are reported and omitted
model: provider/model:high # optional; thinking suffix may be :off/:low/:medium/:high/:max
profile: coder # optional; named model candidates from ~/.pi/agent/profiles.yaml
confirmProjectAgents: false # project agents default to requiring confirmation
---
Prompt body appended to Pi's base instructions while the agent is active.

Model selection precedence

Agent frontmatter may declare a model (exact model, optional thinking suffix) or a profile — a named entry in the shared machine-local ~/.pi/agent/profiles.yaml maintained by @pi-kaush/pi-model-profiles. An agent must not declare both. Before selecting a model, /agent refreshes Pi's local model catalog so models added during a long-lived session can be used; the parent session's enabledModels / --models cycling scope does not limit profile candidates. Profile candidates are walked in order at activation and the first model that exists and is authenticated wins; once the session is running, models never switch mid-request. Agents without either keep the current session model.

pi-agent-mode loads @pi-kaush/pi-model-profiles lazily: if the library is missing, only agents that declare profile: fail (with an install hint) and every other /agent capability is unencumbered.

Behavior

• The first activation captures the current model, thinking level, and active tools as one baseline. Switching agents keeps that original baseline, so clearing always returns to the pre-/agent session state.
• Missing models or failed authentication abort activation without corrupting the previous state.
• The active agent survives session resume and reload; the footer status shows the active agent, including its emoji when configured.
• Durable state is written as a namespaced pi-agent-mode/state session entry. Legacy active-agent-state entries from earlier local implementations are still read on resume; the newest recognized entry on the active branch wins.

Development

npm run check
npm pack --workspace @pi-kaush/pi-agent-mode --dry-run

Load the live source in isolation:

pi --no-extensions -e ~/dev/oss/pi-kaush/extensions/pi-agent-mode/src/index.ts