# Po

**An agent harness that loads only the skills and tools you name.**

> It begins with one useful MCP server. Then another. Soon the agent fixing a heading
> wakes up with database tools, browser controls, and their small novel of schemas. This
> is our config.

Po is an opinionated, composable agent harness built on
[Pi](https://github.com/earendil-works/pi). It is tailored for people whose agent has one MCP
server too many. It turns extensions, skills, MCP servers, and system prompts into explicit
session configuration instead of background noise.

![Po panda, an agent harness that loads only the skills and tools you name](https://cdn.jsdelivr.net/npm/@agimon-ai/po@latest/assets/banner.png)

Plugin systems scope what an agent knows. They do less to scope which configured plugins and MCP
servers a particular session can load. Claude Code's `enableAllProjectMcpServers` and static
denylist are repository-wide. Po draws that loading boundary around the session. Pick a major
mode and some domains; add a profile if you want one. Four YAML files decide what loads;
`po --explain` tells you what got in, why, and what it costs before launch.

It borrows its shape from [Po Emacs Core](https://github.com/poemacs/core): quick to
start, close to Pi, opinionated where defaults help, and easy to pull apart when they do
not. Use it as-is, build your own config on top, or raid it for parts.

## Contents

[Install](#install) · [Try Po](#try-po-without-replacing-your-pi-setup) ·
[Philosophy](#philosophy) · [What this buys you](#what-this-buys-you) · [Features](#features) ·
[Configuration](#configuration) · [Trust and data boundaries](#trust-and-data-boundaries) ·
[CLI reference](#cli-reference) · [Troubleshooting](#troubleshooting-and-direct-use) ·
[Architecture](#architecture) · [Development](#development)

## Install

```bash
npm install -g @agimon-ai/po @agimon-ai/po-web
```

The package owns the CLI and the [`po-server` executable and server API](docs/server/index.md) used
by the web and desktop clients. Bare `po` starts the `po-web` console from `@agimon-ai/po-web`, which
depends on `po`, so `po` finds it at run time and prints install guidance when it is missing.

The root package contains the fixed host foundation only. Feature packages are selected by
`.po/modes.yaml` and installed into the consumer repository when they are first needed.

## Status and requirements

Po is alpha software. Configuration and package boundaries may still change between alpha
releases.

- Node.js 24 or newer
- Release targets: macOS arm64, Linux x64, and Linux arm64
- Pi 1.0.0 for packages that declare it as a peer requirement

## Pi 1.0 sessions and Codex Fast

Headless sessions use fresh `durable-v1` storage. Earlier headless sessions cannot be resumed or
converted. Their files remain untouched, without migration or backups.

Use `/fast on|off` in CLI or server sessions, or the **Fast** switch in the web model picker.
Fast requests Codex priority service, which may increase cost, independently of thinking effort.
Fresh top-level sessions default to off. New subagents and child sessions inherit the parent's
current setting, then persist their own setting across resumes. Other providers never receive
Po's priority flag.

## Quick start

```bash
po init                                  # seed ~/.po
po sync                                  # install configured packages and ensure the global builds
po                                       # start po-web and po-server, then open the printed URL
```

`po init` creates `config.yaml`, `modes.yaml`, `domains.yaml`, and `profiles.yaml` under
`~/.po`. It preserves existing files unless you pass `--force`, and it removes the Po entries
and theme that earlier versions wrote to Pi user settings.

`po sync` installs the packages every declared layer names, so switching modes does not depend on the
root package's dependency closure. It then ensures the one global web build and the MCP app build exist.
It does not change either normal Pi settings file.

### No generated per-repository state

Po writes nothing per repository or worktree. po-server composes every session live from configuration
and installed packages, importing each package's built `dist` directly, so a rebuilt or added package
reaches the next session without a sync or a restart. The cockpit web build is shared: it lives under
`~/.po/build/web/<key>`, where the key covers every web plugin package the global root and the
admitted workspaces use, so two repositories with the same plugins share one build.

Export the HTTP and socket contracts with `po api-export --out ./api-schema --strict`. It reads each
installed server package's built contract. See [API export](docs/server/api-export.md) for artifact
formats, CI checks, and package declarations.

Run `po sync --check` to report missing packages or a missing global web build without writing anything.
Inside a repository, `po sync` installs for that repository. Outside every repository, it installs for the
global configuration in `~/.po`.

Bare `po` passes every argument to `po-web`. Use `--explain` to resolve a selection without
starting a session:

```bash
po --major-mode copilot --no-domains --explain
po --major-mode minimal --no-domains --explain
```

## Philosophy

An agent does not need every tool for every job. Po separates the base session from
the things you switch on for a while: modes choose behavior, domains choose subject
matter, and profiles choose a point of view.

### Major and minor modes

A major mode is the base config. It names the extension layers for development, marketing,
or whatever else you do. Define as many as you like; only one is active at a time. Synchronized
sessions can reload compatible changes; launcher-owned composition changes require a relaunch.

Minor modes are batteries-included switches inside that base. They start off, stack freely,
and keep their model tools and skills out of context until turned on. Po ships six:

- **Help mode:** expose package-owned guidance only while you need it.
- **Plan mode:** remove Pi's file-editing tools while you agree on an approach.
- **Calendar layer:** schedule durable prompts, workflows and plugin actions while the server is up.
- **Goal mode:** keep one objective in view until it is done or dismissed.
- **Voice mode:** replace typing with local speech.

### Domains

A domain is a named group of agent plugins. It carries the skills and MCP servers for one
kind of work, and `/domains` switches it while the session is running.

Plugins are cataloged once and domains refer to their names. A configured root may be a
Codex-compatible marketplace or a folder whose direct children are plugins, so a repository
with many plugins does not need one entry per directory:

```yaml
plugins:
  roots: [plugins]
  entries:
    remote-review:
      source: url
      url: '<REVIEW_PLUGIN_GIT_URL>'
      ref: v1.2.0

domains:
  development:
    description: Implementation and code-review tools.
    plugins: [pi-development, remote-review]
```

Po also checks personal and repository Codex marketplace layouts. Marketplace IDs use
`plugin@marketplace`. Remote Git and npm sources are downloaded once into the persistent
`~/.po/plugin-cache` directory. Cache entries are reused until their source descriptor
changes; use a Git SHA or exact npm version for reproducible installs. Home and repository
catalogs merge, and repository names replace matching home names.

A blog is not one task. Research it, draft it, make the assets, then review it. Turn on the
`visual` domain while making assets; the other three steps have no reason to carry it.

### Profile

An LLM has no house style until you give it one. A profile can supply a narrative, brand
rules, or a different voice. It is optional; no profile is a perfectly good profile.

Profile roots remove the need to list every persona folder. A root may itself contain the
persona files, or its direct-child folders become profiles named after those folders. Po
recognizes `profile.md`, `SOUL.md`, and `AGENTS.md` and never searches deeper directories.

```yaml
profiles:
  roots: [agents/acme]
  entries:
    editor:
      persona: agents/special/editor
      env:
        EDITOR_MODE: strict
```

Roots from the home and repository files accumulate relative to their declaring config.
Repository discoveries replace same-named home discoveries. Explicit entries override
discovery and can add string environment defaults; repository entries replace matching home
entries. Select one at launch with `--profile editor` or switch with `/profile`.

## What this buys you

Every tool schema and skill name competes for the same context. Loading less has two
immediate effects:

1. You spend fewer tokens before the work begins.
2. The model has fewer plausible-but-wrong tools and skills to choose from.

The savings get larger when each workflow job starts with its own config instead of
inheriting the last job's toolbox.

### Copilot

Po's web console exposes package-owned tools, commands, settings, and panels.
Po no longer ships terminal leader menus, shortcuts, overlays, or widgets.

When the keyboard is the wrong tool, autonomous Voice mode keeps the conversation going.
You can talk to the agent while doing the chores instead of carrying a laptop around the
house, and the primary agent can speak its own opening, milestone, and final updates.

### Autopilot

Copilot helps while you are present. Calendar and Workflow keep work moving when you are not.
Together they can dispatch structured jobs from one live session.

#### Workflows

Po's native Workflow runtime starts each step as a configured child session.
Jobs select their major mode, domains, and system prompt through `runConfig`.
The tracked examples below contain complete definitions.

#### Native plugin and workflow examples

This source repository includes a complete, deliberately small example stack:

```text
plugins/
  development/   implementation skill and developer agent
  testing/       testing and review skills, tester and reviewer agents
  blog-writing/  research, outline, drafting, and editorial skills and agents
automations/workflows/
  dev-feature.workflow.yml
  dev-fix.workflow.yml
  blog-writing.workflow.yml
```

Each plugin has both `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json`, while its
`skills/` and `agents/` content is shared. `.po/domains.yaml` exposes the `development`,
`testing`, and `blog` domains plus the `engineering` alias. `.po/modes.yaml` mirrors the
standalone package set with workspace-local paths, keeps its canonical modes, and adds an
`examples` base mode with the `workflow` layer for the tracked workflows. Inspect the exact session before launch:

```bash
po --major-mode examples --domains engineering --explain
po --major-mode examples --domains blog --explain
```

The same bundles can be installed directly through either native marketplace:

```bash
# Codex
codex plugin marketplace add .
codex plugin add development@po-examples

# Claude Code
claude plugin marketplace add ./ --scope user
claude plugin install development@po-examples --scope user
```

Substitute `testing` or `blog-writing` to install another bundle. No Po-specific plugin
schema is involved.

List and dry-run the tracked workflows before spending a model call:

```bash
pnpm exec workflow-mcp list-workflows automations/workflows
pnpm exec workflow-mcp run-workflow automations/workflows/dev-feature.workflow.yml \
  --dry-run --skip-launch --prompt "Add a health check"
pnpm exec workflow-mcp run-workflow automations/workflows/blog-writing.workflow.yml \
  --dry-run --skip-launch --prompt "Write a practical guide to scoped agent tooling"
```

Real runs delegate to tmux by default and accept `WORKFLOW_LAUNCHER=cmux`. Development runs do
not create branches, commits, or pushes. Blog runs leave review-ready Markdown, sources, and a
publication checklist in the workflow run directory without writing into a site or calling a CMS.
These examples live in the source repository and are not part of the published npm tarball.

#### Calendar

Workflow definitions are exposed like skills, so the agent can choose one for the job. A
Calendar event can send a subagent to fetch the next task, then dispatch the workflow that matches
it. One session becomes the dispatcher instead of the place every job has to fit.

## Features

Po is a modular agent harness, not one giant extension. Each package owns one job; shared UI,
Cordis services, and session contracts make them behave like one. Use the generated
`default.packages` list together, remove packages you do not want, or replace its entries one
at a time. Selectable packages are not runtime dependencies of the root package or of one another.

### Foundation and interface

#### Configuration and composition

[`@agimon-ai/po`][pkg-po] is the command-line config compiler and the `po-server` runtime.
`po init` creates the personal config, and bare `po` starts the `po-web` console. Sync resolves every major
mode and domain into native server, web, MCP, and resource contributions.

#### Supporting packages

[`@agimon-ai/po-config`][pkg-po-config] resolves the four YAML files and exposes the
configuration API. [`@agimon-ai/po-domain`][pkg-po-domain] owns domain selection, plugin
materialization, resource staging, and MCP scoping.
[`@agimon-ai/po-core`][pkg-po-core] contains the shared
Cordis service and event contracts used by extension authors.
[`@agimon-ai/po-hashline`][pkg-po-hashline] provides the shared snapshot tags and line-anchor
protocol. [`@agimon-ai/po-read`][pkg-po-read] and [`@agimon-ai/po-grep`][pkg-po-grep]
produce editable anchors for writable files while preserving native output for non-writable files.
[`@agimon-ai/po-edit`][pkg-po-edit] replaces Pi's search-and-replace `edit` tool with
stale-safe ranges anchored to the file content the model read or searched.
[`@agimon-ai/po-file-edit`][pkg-po-file-edit] keeps the edit timeline and file snapshots.
The fixed `@agimon-ai/po-artifact` package gives each session a durable artifact folder,
names it in the system prompt, and shows recent artifacts in web and native Activity.
The Artifacts heading opens all files in that session's folder as a grid.
[`@agimon-ai/po-log`][pkg-po-log] collects session events, while
`@agimon-ai/po-core/telemetry` is the library-level telemetry adapter. Po Log's `logsink` code-mode namespace reads session evidence and explicitly selected cross-session history.

Runner selects matching RMUX and RTK native artifacts automatically. Do not install them directly.
The packages cover macOS and Linux on arm64 and x64 for both [RMUX][pkg-rmux-darwin-arm64] and
[RTK][pkg-rtk-darwin-arm64].

#### Shared UI

[`@agimon-ai/po-ui`][pkg-po-ui] supplies shared web presentation and theme utilities.
Terminal leader bindings and overlays have been retired.

### Coordinated work

#### Agent team

[`@agimon-ai/po-team`][pkg-po-team] runs named subagents asynchronously. It owns agents,
runs, membership, intercom, and model policy; Task owns the persistent task graph used for
delegation. Agents can work in parallel and message one another through native Team tools.

#### Tasks

[`@agimon-ai/po-task`][pkg-po-task] keeps a task graph on disk, not a disposable checklist in the
transcript. Dependencies persist independently of transcript compaction, and work can be handed to
a subagent, including a smaller model when the job does not need the expensive one. Seeded
`minimal` and `copilot` modes select its `task` layer; omit that layer when a major mode
should not expose the task tool.

#### Runner

[`@agimon-ai/po-runner`][pkg-po-runner] replaces Pi's blocking `bash` tool with
supervised command execution. `po init` includes Runner in `default.packages`, so every
generated mode gets it. Short commands still return inline; commands that pass the configurable
threshold of 60 seconds by default move into the background with durable logs. Use
`background: true` for an immediate detached run or `interactive: true` when the command needs
terminal input. Runner IDs and complete raw logs remain available to the current session through
the `po-runner` CLI. Runner tries bundled RMUX, then `rmux` on PATH,
then `tmux` on PATH. If no pane backend accepts the run, non-interactive commands use a supervised
subprocess; interactive commands require RMUX or tmux. Conservatively recognized single commands
use the matching RTK stdin filter after completion. Compound commands, pipelines, incompatible
formats, and unsupported commands keep bounded raw output. Remove Runner from `default.packages` to keep Pi's
`bash`, or add it to a named layer when only selected modes should replace `bash`.

#### Auto-compact

Ordinary compaction waits for one summary to save an overgrown session.
[`@agimon-ai/po-autocompact`][pkg-po-autocompact] leaves checkpoints instead:

1. At 50%, it writes the first compact summary.
2. Later, it combines that summary with the messages since; the model decides whether the
   result is ready to use.
3. On the third pass, it combines them again and forces compaction.

The work runs off-thread and can make up to three additional summarization calls. The standard
adapter preserves staged conversation checkpoints; Task and Team keep their own state rather than
being embedded as special snapshots in the compact summary.

### Context and access

#### Help mode

[`@agimon-ai/po-help`][pkg-po-help] keeps package guidance out of the default prompt. A
fresh parent session performs no Help retrieval and exposes no Help skills. Activate Help with the
native `minor_mode` tool, then deactivate it before the next interaction.
Help names state their intent: authoring
guides use `po-author-*`, while operational guides use `po-use-*`. Core authoring guidance
covers extensions, runtime config, major modes, domains, profiles, hooks, workflows, and skills.
Parent and detached-child sessions both include the Help runtime, while root and axis authoring
guides remain parent-owned and all guidance stays withdrawn until Help mode is activated.

#### MCP

[`@agimon-ai/po-mcp`][pkg-po-mcp] is the gate between a session and its servers. It reads
repository and legacy plugin `.mcp.json` plus Agent Plugins v1 `mcp.json`, then exposes only the
servers and proxy upstreams allowed by the selected domains. A domain switch persists an immutable
projection; Config publishes it through the native session Cordis registry and MCP starts a fresh
in-memory `mcp-proxy` container. No Hono server or localhost proxy sits in this path.

#### Ask user question

[`@agimon-ai/po-user-feedback`][pkg-po-user-feedback] gives the agent a structured question
that actually waits for an answer. In autonomous Voice mode it skips the modal, narrates the
choices, and accepts the next spoken response as an ordinary user message.

#### Logging and telemetry

Po logging records operational metadata such as counters, spans, session IDs, tool names, and
errors. Callers remain responsible for values they attach to telemetry. Native diagnostics expose
current-session metrics, and [`@agimon-ai/po-logsink`][pkg-po-logsink] provides historical lookup
when a sink is configured.

#### Plan mode

A promise to "only plan" is not a permission boundary. [`@agimon-ai/po-plan`][pkg-po-plan]
removes `edit` and `write` tools while the agent explores, persists the plan, and hands it back
for approval. It does not sandbox Bash, external tools, or the operating system. Use the native
planning tools and web review surface; terminal planning menus are no longer available.
Turn it on when the approach should be settled before the files move.

#### Calendar layer

[`@agimon-ai/po-calendar`][pkg-po-calendar] schedules durable prompts, workflows and plugin actions.
Keep the calendar layer in the home default major mode for the scheduler. Workflow success means launched,
not finished. Plugin-managed events cannot be edited, but pause, resume, run now and cancel remain available.
Busy runs and downtime are skipped, never replayed. Back up before upgrading: older Calendar versions
cannot read events saved with workflow, action or assignment fields.

#### Goal mode

[`@agimon-ai/po-goal`][pkg-po-goal] pins one objective to the session until it completes or
you end it. Native goal tools manage the active objective and repository history. Finished goals
stop contributing active instructions and tools but remain in history when you want to restart one.

#### Workflow layer

[`@agimon-ai/po-workflow`][pkg-po-workflow] runs GitHub Actions-style job graphs with
dependencies, timeouts, artifacts, and a separate Po session for each step. Native workflow tools
and the web workflow dock expose launch, status, and recovery. It is for work that needs hard job
boundaries and explicit handoffs rather than one long conversation.

#### Voice mode

[`@agimon-ai/po-voice`][pkg-po-voice] captures PCM audio through the local platform helper
and can transcribe it locally. Transcript text, session state, and model requests may still cross
process or provider boundaries according to the configured engines. Native `voice` controls manual
dictation, while `voice-auto` controls autonomous capture. The active native session receives the
Voice capabilities and `narrate` tool.

While `narrate` is available, the primary agent calls it before every user-facing final
response. Final narration contains the complete answer, including every user-relevant
conclusion, question, warning, result, and next action in the written response, rather than
leaving essential information only in text. Short turns need one complete spoken answer;
longer work also gets an opening and meaningful milestone calls. Each ready-to-speak
utterance is limited to 4,096 characters, waits for physical playback, and returns
`completed`, `interrupted`, `superseded`, or `failed`.

If the agent never attempts `narrate` during a run, active Voice speaks one sanitized
turn-end fallback rather than leaving the final response silent. Finals of at most 320
characters use deterministic speech; longer finals use the configured
`voice.autoCapture.model` for one bounded summary, with deterministic degradation on
failure or timeout. Any `narrate` attempt suppresses this safety net, so it cannot duplicate
or retry direct speech. Voice does not generate automatic intent, plan, milestone, or tool
progress narration. Native workflow and user-feedback narration remain available, and the same
model continues to provide bounded command correction.

## Configuration

Po reads four configuration files:

- `config.yaml` defines runtime settings such as trust, editor, planning, and voice behavior.
- `modes.yaml` defines default packages, extension layers, and major modes.
- `domains.yaml` catalogs plugins and sets session access.
- `profiles.yaml` supplies persona files and environment defaults.

Each matrix file has two optional layers: personal defaults in `~/.po/` and repository
overrides in `<repository>/.po/`. Po loads both. Unique named entries from either layer
remain available; a same-named repository entry replaces the complete personal entry. Plugin
and profile roots from both layers are retained. Relative paths in personal config resolve
from `~/.po/`; relative paths in repository config resolve from the repository root.

### `modes.yaml`: choose behavior

A layer is an ordered bundle of extension packages and hook groups. A major mode names the
layers that should run together. The top-level `default.packages` list is the ordered package
baseline for every major mode. `po init` writes the distribution's current
feature packages there so the baseline is visible and replaceable. If `default` is absent,
Po adds no default feature packages. Use `default.packages: []` for an explicit empty
baseline. The fixed host core remains active independently of this setting, and named layers
keep their existing behavior.

Launch installs missing required packages from the defaults and selected layers. `po sync`
installs missing required packages from the defaults and every declared layer, moves every
package in Po's shared `~/.po/runtime` to its newest published version, then builds the
synchronized matrix. A package whose published version cannot be read, because the machine is
offline or the registry refuses the request, keeps its installed version and is named in the
sync output. `po sync --check` reports missing packages without modifying the repository. Optional packages and local paths are not installed automatically. Removing an
entry stops activating it but leaves Pi's package cache available for later reuse.

Packages in `default` and named layers may be bare strings, or mappings when the package accepts
configuration:

```yaml
default:
  packages:
    - '@agimon-ai/po-help'
    - '@agimon-ai/po-goal'
    - '@agimon-ai/po-voice'
    - '@agimon-ai/po-runner'
    - '@agimon-ai/po-read'
    - '@agimon-ai/po-grep'
    - '@agimon-ai/po-edit'
    - '@agimon-ai/po-file-edit'
    - '@agimon-ai/po-autocompact'
    - '@agimon-ai/po-plan'
    - '@agimon-ai/po-log'
    - '@agimon-ai/po-mcp'

layers:
  calendar:
    packages:
      - '@agimon-ai/po-calendar'
  workflow:
    packages:
      - '@agimon-ai/po-workflow'
  team:
    packages:
      - name: '@agimon-ai/po-team'
        config:
          models:
            - model: provider/model-id
              thinking: high
  review:
    packages:
      - '@scope/review-extension'

defaultMajorMode: copilot
majorMode:
  minimal:
    description: Lean sessions with delegation and little else.
    layers: [team, workflow, calendar]
  copilot:
    description: General coding with delegation and review tools.
    layers: [team, review, workflow, calendar]
```

Order matters: Po assembles `default.packages` first, then the selected layers and their
packages from left to right. Put settings under the package that consumes them; a layer is
composition, not a mystery bag of shared configuration. Home and repository `layers` and
`majorMode` records merge by name, with the repository definition winning a collision. If both
sources declare `default`, the repository block replaces the personal block as one whole package
list.

Workflow is selected through the `workflow` layer, not a minor-mode switch. New seeds
include it in `minimal`, `copilot` and `examples`; remove the layer from a mode to omit it.
Existing `default.packages` entries still work and deduplicate with the layer. No config
migration runs, and persisted `minorModes: [workflow]` has no effect.

Configurations created before the hashline tools were split may contain only `po-edit`.
Replace that entry with the ordered `po-read`, `po-grep`, and `po-edit` trio. Init
preserves existing configuration unless it is run with `--force`.

Choose a mode with `--major-mode copilot`, switch it with `/mode`, or change
`defaultMajorMode` when one mode should be the ordinary starting point.

### `domains.yaml`: choose content and access

Plugins are cataloged once, then domains refer to their names. A root can be a marketplace,
a single plugin, or a container whose direct-child folders are plugins. Discovery is
intentionally nonrecursive: a tool buried five directories down should not load by accident.

```yaml
defaultDomains: [development]

plugins:
  roots: [plugins]
  entries:
    remote-review:
      source: url
      url: '<REVIEW_PLUGIN_GIT_URL>'
      ref: v1.2.0
    published-research:
      source: npm
      package: '@acme/research-plugin'
      version: 1.4.0

domains:
  development:
    description: Repository implementation tools.
    plugins: [coding-tools]
  review:
    description: Focused review skills with a narrow MCP boundary.
    plugins:
      - name: remote-review
        skills: [typescript]
        agents: [reviewer]
        hooks: false
        mcp: true
    mcp:
      servers: [filesystem]
      proxy: [github]

aliases:
  work: [development, review]
```

Here, `coding-tools` is discovered from `plugins/coding-tools`; its manifest name, or its
folder name when no manifest name exists, becomes the catalog ID. Local roots and entries
resolve beside the declaring file. Git and npm entries are cached in
`~/.po/plugin-cache`; pin a Git SHA or exact package version when reproducibility
matters. Domains may load an entire plugin or select only its skills, agents, hooks, and MCP
configuration. The optional `mcp` mapping is an allowlist, not a request to start every server
in the repository.

Select one or more domains with `--domains development,review`, use an alias such as
`--domains work`, or switch them with `/domains`. `--no-domains` is useful when the right
amount of repository context is none.

### `profiles.yaml`: choose a point of view

A profile directory becomes discoverable when it directly contains `profile.md`, `SOUL.md`,
or `AGENTS.md`. A root may be one profile or a container of direct-child profiles. The folder
name becomes the profile name; Po concatenates those three files in that order.

```yaml
profiles:
  roots: [personas]
  entries:
    release-writer:
      persona: personas/release-writer
      env:
        BRAND: acme
        TONE: concise
```

With that config, `personas/release-writer/profile.md` is enough to discover
`release-writer`. The explicit entry is optional; use one when the profile needs another name,
an exact persona path, or string environment defaults. Explicit entries override discovered
folders. Already exported environment values win, so selecting a profile never quietly
replaces a value supplied by the caller.

Discovery never recurses. Persona paths must remain under `agents/` or a root declared in the
same file, and symlinks may not escape the persona boundary. Legacy profiles written directly
under `profiles` still load, but new configuration should use `roots` and `entries`.

Select a profile with `--profile release-writer` or switch it with `/profile`. Leaving the
catalog empty is valid; no profile remains a first-class choice.

### Check the matrix before launch

The fastest configuration debugger is the one that does not start a model:

```bash
po --major-mode copilot --domains work --profile release-writer --explain
po sync
po sync --check
```

`--explain` prints the resolved mode, domains, profile, plugins, skills, agents, MCP boundary,
and estimated prompt cost. `po sync` resolves the repository configuration and publishes
synchronized state. `po sync --check` turns drift into a
non-zero exit code for CI. If the explanation is surprising, fix the YAML before paying a model
to be surprised with you.

## Trust and data boundaries

Po executes the extensions, remote Git/npm plugins, hooks, MCP stdio commands, workflows, and
shell commands you configure. Treat them as trusted executable code. Runner commands inherit the
process environment and operating-system privileges; their logs may contain command output and
secrets. MCP credentials may live in the system keyring or private configuration files.

Voice can keep PCM capture and transcription local when local engines are selected, but transcript
text and model requests follow the configured providers. Calendar, Workflow, Plan, Autocompact, Team,
and autonomous Voice can make additional model calls. Telemetry is disabled or redirected through
its owning package's controls; values supplied by callers are not automatically scrubbed.

## CLI reference

| Command or option              | What it does                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `po`                           | Starts the `po-web` console and its headless `po-server`; arguments go to po-web   |
| `po init`                      | Seeds personal config and removes Po entries earlier versions wrote to Pi settings |
| `po sync`                      | Publishes the current repository, or the global composition outside repositories   |
| `po sync --check`              | Exits non-zero when the applicable registered generation is missing or stale       |
| `po-runner`                    | Inspects and controls supervised Runner processes and logs                         |
| `--explain`                    | Prints the resolved matrix and estimated prompt cost without launching Pi          |
| `--emit-mcp <dir>`, `--no-mcp` | Writes the resolved MCP config or disables MCP for one run                         |
| `--` and remaining arguments   | Forwards provider or Pi arguments unchanged where the selected command allows it   |

## Troubleshooting and direct use

- Run `po sync --check` to detect drift or missing configured packages, and `po sync`
  to install them and rebuild synchronized state.
- If neither RMUX nor tmux is available, non-interactive Runner calls report the supervised subprocess
  fallback. Interactive calls require RMUX or tmux. Linux native artifacts require a compatible loader and libc.
- Po-owned packages expose native server, web, and MCP contributions, not Pi entry points. Install
  them with `npm install` or select them in `modes.yaml`. Third-party Pi settings packages still load
  through the upstream SDK extension host, including provider registration before model selection.
- Terminal leader menus, shortcuts, overlays, and widgets are no longer shipped. Native commands,
  tools, and web panels remain where the owning package provides them. RMUX and RTK artifacts are
  selected by Runner and should not be installed directly.
- The root `po-runner` command delegates to Runner from the active repository and asks you to add
  Runner to `modes.yaml` when it is absent. The distribution remains the supported way to get the
  coordinated defaults.
- The Ollama preset and launcher `--mute` and `--auto-stop` flags are retired. They do not have
  replacement terminal extensions.

## Architecture

See [Architecture](https://github.com/AgiFlow/po/blob/main/docs/architecture.md) for native
server/web/MCP contributions, canonical fingerprints, transition classification, shared-host
Cordis lifecycle ownership, and parent/child isolation. Po no longer composes its own Pi factories;
third-party Pi packages remain supported through the SDK host.

## Development

```bash
pnpm install
pnpm build
pnpm examples:check
pnpm nx build @agimon-ai/po
pnpm nx test @agimon-ai/po
pnpm nx typecheck @agimon-ai/po
pnpm nx lint @agimon-ai/po
```

Po is maintained by [Agimon](https://agimon.ai/about).

## License

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

## Maintainer release order

Publish [`@agimon-ai/po-core`][pkg-po-core] and
[`@agimon-ai/po-hashline`][pkg-po-hashline] first, then
[`@agimon-ai/po-help`][pkg-po-help], and only then the
[`@agimon-ai/po`][pkg-po] runtime that consumes them. Generated changelogs remain owned
by the release tooling.

The deploy workflow blocks publishing unless the deterministic Po architecture sweep and the
packed-install system tests both pass. This keeps the shared Cordis host contract and independently
loaded extension graph inside the same release boundary as the packages that consume them.

[pkg-po]: https://www.npmjs.com/package/@agimon-ai/po
[pkg-po-ui]: https://www.npmjs.com/package/@agimon-ai/po-ui
[pkg-po-config]: https://www.npmjs.com/package/@agimon-ai/po-config
[pkg-po-domain]: https://www.npmjs.com/package/@agimon-ai/po-domain
[pkg-po-hashline]: https://www.npmjs.com/package/@agimon-ai/po-hashline
[pkg-po-read]: https://www.npmjs.com/package/@agimon-ai/po-read
[pkg-po-grep]: https://www.npmjs.com/package/@agimon-ai/po-grep
[pkg-po-edit]: https://www.npmjs.com/package/@agimon-ai/po-edit
[pkg-po-file-edit]: https://www.npmjs.com/package/@agimon-ai/po-file-edit
[pkg-po-log]: https://www.npmjs.com/package/@agimon-ai/po-log
[pkg-rmux-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-darwin-arm64
[pkg-rmux-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-darwin-x64
[pkg-rmux-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-linux-arm64
[pkg-rmux-linux-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-linux-x64
[pkg-rtk-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-darwin-arm64
[pkg-rtk-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-darwin-x64
[pkg-rtk-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-linux-arm64
[pkg-rtk-linux-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-linux-x64
[pkg-po-team]: https://www.npmjs.com/package/@agimon-ai/po-team
[pkg-po-task]: https://www.npmjs.com/package/@agimon-ai/po-task
[pkg-po-runner]: https://www.npmjs.com/package/@agimon-ai/po-runner
[pkg-po-autocompact]: https://www.npmjs.com/package/@agimon-ai/po-autocompact
[pkg-po-help]: https://www.npmjs.com/package/@agimon-ai/po-help
[pkg-po-mcp]: https://www.npmjs.com/package/@agimon-ai/po-mcp
[pkg-po-user-feedback]: https://www.npmjs.com/package/@agimon-ai/po-user-feedback
[pkg-po-logsink]: ../../tooling/po-logsink/README.md
[pkg-po-plan]: https://www.npmjs.com/package/@agimon-ai/po-plan
[pkg-po-calendar]: https://www.npmjs.com/package/@agimon-ai/po-calendar
[pkg-po-goal]: https://www.npmjs.com/package/@agimon-ai/po-goal
[pkg-po-workflow]: https://www.npmjs.com/package/@agimon-ai/po-workflow
[pkg-po-voice]: https://www.npmjs.com/package/@agimon-ai/po-voice
[pkg-po-core]: https://www.npmjs.com/package/@agimon-ai/po-core