pi-mainagent

pi extension providing agent personas: /mainagent command to switch between Markdown-defined personas (model, thinking level, tool filters), with persisted selection across sessions.

Tech Stack

TypeScript (pi extension, no build step — loaded as source by pi)
Runtime APIs: @earendil-works/pi-coding-agent (ExtensionAPI, ExtensionContext), pi-tui dialogs, pi-ai model catalog
No dependencies bundled: core pi packages are peerDependencies

Architecture

Single extension file: extensions/pi-mainagent.ts (entry point: export default function piMainagentExtension)
State: ~/.pi/agent/agents/*.md (persona definitions) + ~/.pi/agent/agent-state.json (active persona name)
Flow: registerCommand("mainagent") → picker dialog → applySelection() mutates session (model, thinking, tool policy, appended prompt) and updates the main-agent-status widget
Events used: session_start (re-apply persisted selection), before_agent_start (persona prompt), session_shutdown

Commands

No build/test/lint configured. Verify changes by loading the extension: pi -e D:/source/pi-mainagent

Code Style

ES modules, 2-space indent, double quotes
Constants in SCREAMING_SNAKE_CASE at top of file; helpers as plain functions
UI strings via pi TUI components (showSelectDialog, theme-aware)

Coding Rules

Do NOT replace the minimal frontmatter parser with a YAML library — see @specs/persona-frontmatter.md for the exact supported grammar
Persona prompts are APPENDED to pi's system prompt; never strip base prompt or skills
/mainagent off must restore previous session settings exactly (saved in memory, not re-derived)
Prompt files > 64 KB (MAX_PROMPT_FILE_BYTES) are rejected
Publish hygiene: only extensions/ ships to npm ("files" in package.json); docs and drafts stay out

Constraints / What to avoid

No new runtime dependencies (keep peerDependencies only)
Do not persist tool/model changes globally — they are session-scoped; only the persona name is persisted
Never write outside ~/.pi/agent/ (agents dir, state file, prompt files referenced by definitions)

Workflow

Edit extensions/pi-mainagent.ts
Verify: pi -e D:/source/pi-mainagent → run /mainagent in the TUI
Commit; to release: bump version in package.json, npm publish

Self-maintenance rule:

When you modify code, update the relevant file in specs/

References

@specs/module-index.md — modules and criticality tiers
@specs/persona-frontmatter.md — persona file grammar and editing rules

AGENTS.md 2.5 KB History Raw