pi-persona

Give Pi a supervised team. pi-persona adds supervised multi-agent orchestration to Pi: async workers, live steering, cross-session collaboration, and switchable personas. It builds on Pi's native SDK and tool hooks; the extension adds worker supervision and coordination. Describe the outcome. A supervisor delegates work, gathers results, and checks the outcome; you can inspect workers, redirect them, or stop a run while it is in progress.

Install · Team workflow · Cross-session collaboration · Personas · Documentation

Install

Requires Pi ≥ 1.0.0, Node.js ≥ 22.19, and Git. Configure a model provider in Pi first.

Run in your terminal:

pi install npm:@aeondave/pi-persona
pi

Then run these commands inside Pi to install the bundled personas and start using one:

/persona seed
/persona dev

Bundled personas are not installed automatically. /persona seed adds missing files and preserves your customizations.

Restart Pi after updating. For a pinned install, install the new version or tag explicitly. If switching from a Git install, remove that source first with pi remove git:github.com/AeonDave/pi-persona (use your exact pinned source if applicable), then install the npm package. Keep only one source configured to avoid loading the extension twice.

What it does

Work with your team

Once seeded, you can start directly with pi --persona dev. Describe the work in plain language:

Fix the cancellation bug. Delegate independent investigations, preserve the public API, implement the fix, and run the relevant checks.

For example, specialists can investigate code paths, tests, and the API contract in parallel. Their findings return to the same supervisor, which integrates them, verifies the fix, and reports the outcome. This is one possible workflow, not a fixed pipeline; dependent steps run in order.

Interactive delegation runs in the background by default. Results return automatically when the supervisor is free; you can inspect or redirect a worker at any point.

Periodic async status appears as a durable, expandable operator-only card (five minutes by default); it does not start a model turn or enter model context. Completions, blocking asks, unread worker messages, and newly stalled workers still use their actionable notification paths.

Launch and control cards show the worker's name. Steering receipts preview the message sent; expand with Ctrl+O (the default binding) to read it in full. A queued message is not proof that the worker has acted on it.

For time-based work, ask “remind me in ten minutes.” For an event, ask “let me know when this build finishes.” Keep Pi open while timers and monitors are running; they are not restored after a restart. See timers and monitors for examples.

Collaborate with another Pi

Use Intercom to message workers managed by the current supervisor. Use Exocom to share findings or coordinate work between independent Pi sessions.

To enable Exocom, open two terminals in the same workspace and start each with:

pi --exocom --persona dev

Then ask one session to consult the other or agree who handles which files. Use /exocom to inspect the connection and workspace code.

A session in another workspace can join using that exact, case-sensitive code:

pi --exocom=Ab0T --persona researcher

Replace Ab0T with the code shown by /exocom. Both sessions must run on the same machine and share a Pi agent directory. A peer joining from another workspace can advise and exchange results; it cannot claim files in the joined workspace.

See the collaboration guide for day-to-day use.

Choose a persona

Personas configure the supervisor's approach and orchestration defaults. Start with dev for everyday coding, or choose one for the work ahead.

These are editable starting points. Browse the bundled personas and worker agents, or read the practical guide for help choosing a workflow.

Strategies are not restricted to the similarly named persona: council can select judge, magi, debate, critic-loop, or another installed shape when it adds value. Temporary members allow custom role-based groups without team files. Model selection includes external arbiters. In councils and flows, a provider failure or unavailable model can recover once on the supervisor's model, with the switch visible and both attempts accounted; ordinary delegates keep explicit provider pins strict. See the reference for an inline council example and recovery limits.

Make it yours

Edit installed personas and agents in ~/.pi/agent/persona/agents/, or add project-specific overrides in .pi/agents/. Run /persona reload after editing.

/persona seed preserves existing files. /persona restore replaces bundled defaults, so use it only when you intend to discard customizations to those files.

For optional long-term memory, add pi-persona-mind.

Documentation

Develop

From a checkout:

npm ci
npm run typecheck
npm test

Pi loads the TypeScript extension directly; there is no build step. The CI workflow runs strict typechecking, dependency auditing and the test suite on Linux and Windows. The OpenSSF badge links to the project's scored supply-chain checks; it is not a certification that the code is free of vulnerabilities.

See AGENTS.md for contribution conventions and the security policy for private vulnerability reporting. Licensed under MIT.