@agimon-ai/po-profile

Persona and environment profile switching for Po sessions.

A profile is one of the four axes of a Po selection, alongside domains, the major mode, and the minor modes. It names a persona directory and a set of environment defaults:

# .po/profiles.yaml
profiles:
  roots: [agents]
  entries:
    reviewer:
      persona: agents/reviewer
      env:
        REVIEW_STRICTNESS: high

The persona is profile.md, SOUL.md, and AGENTS.md concatenated from the named directory. The harness assembles them into one file in the run directory and records its path; the persona entry appends that file to the system prompt on every agent start, so the repository's own AGENTS.md keeps applying underneath it.

Persona identity

A persona can say who it is in YAML front-matter at the top of its profile.md:

---
name: Rhea
icon: avatar.png
voice:
  voice: Karen
  rate: 175
---

You are Rhea, a blunt systems architect.

The cockpit shows name and icon beside each assistant message, and voice shadows the spoken voice from config.yaml for this persona only. Every field is optional, front-matter is stripped from the prompt, and a persona that declares none behaves exactly as before. Identity lives in the persona folder rather than in profiles.yaml, so discovered profiles get it too.

Because a message keeps the identity it was written under, switching profiles mid-conversation leaves earlier replies attributed to the persona that produced them.

See the profiles contract for the icon rules and the exact precedence.

Configuration

Personal profiles load from ~/.po/profiles.yaml, then repository profiles load from .po/profiles.yaml. Roots discover either one persona folder or direct-child persona folders. Explicit entries provide a persona path, optional nonsecret string environment defaults, and optional integration metadata binding a mailbox, existing credential aliases, and a browser profile. The session-owned po/profile-runtime service initializes concrete providers and invalidates old secret operations on profile change or shutdown. Resolved secret values never enter profile configuration or prompts. See the integration contract. defaultProfile names the persona a run starts on when nothing else does, mirroring defaultMajorMode in modes.yaml and defaultDomains in domains.yaml; --profile and an inherited PO_PROFILE both override it. Resolution runs from personal discovery to repository discovery, then personal explicit entries to repository explicit entries. A later profile replaces an earlier profile with the same name.

Persona paths must stay inside the declaring config's agents/ directory or a profile root from that same file. Directory and persona-file symlinks cannot escape those boundaries. See the shipped profiles contract for the full configuration model and verification steps.

Help

The package registers help-how-to-profile with the session's po/help Cordis service. Its package guidance becomes visible to the AI only while the parent Help minor mode is active. The registration follows the Help provider lifecycle and is withdrawn when this package or the provider is disposed.

Installation

Po depends on this package and activates it as fixed host core, so a Po install already has it. It is not selectable from .po/modes.yaml.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Plugin entries live in src/extensions. Controllers connect host events and commands to services, while src/exports contains public helpers and types.