pi-multi-profiles

Named, session-scoped routing profiles for Pi, with a self-contained runtime for running markdown-defined subagents in the foreground or background.

Security: Pi extensions execute with full system access. Install only code you trust, and review project configuration before trusting a project.

Install

To install a release published on npm:

pi install npm:pi-multi-profiles

Use GitHub only to try the current unreleased code:

pi install git:github.com/Gioryopool/pi-multi-profiles

Restart Pi or run /reload after installation or configuration changes.

Quick start

Create <getAgentDir()>/pi-agent-profiles/config.json:

{
  "version": 1,
  "defaultProfile": "review",
  "profiles": {
    "review": {
      "order": 10,
      "orchestrator": { "effort": "high" },
      "agents": {}
    }
  }
}

defaultProfile loads the named profile when a new Pi session starts. In the panel, ◆ marks the active session profile; press D on a profile to set that scope's startup default, while A activates only the current session.

Reload Pi, then open /agent-profiles or activate the profile directly:

/agent-profiles use review

Trusted projects may add project-scoped profiles. Project configuration is never read or written unless Pi reports that project as trusted.

What it provides

• Named profiles that route the parent model/effort and per-agent model/effort independently.
• A consolidated keyboard-driven panel for creating, editing, saving, activating, cycling, and deleting profiles.
• Markdown-defined subagents with exact-session foreground/background execution, live messaging, cancellation, handoff, and continuation.
• A session-isolated history panel, active-task widget, bounded completion cards, and package-owned SQLite history.
• Safe route rollback and restoration of active/off state when a Pi session is rebound.
• Optional synchronous compatibility events for external runtimes, without making them a dependency.

Controls

Agent profiles

Control	Action
/agent-profiles	Open the profile assignment panel.
alt+p	Cycle through configured profiles.
Tab / Shift+Tab	Move between profile tabs and + new.
Up / Down / j / k	Move through assignments.
Enter / M / E	Edit the selected model or effort.
S / A / D	Save, save and activate for this session, or set the startup default for the profile's scope.
N / R / Del	Create, reset, or delete.
Esc / Q	Return or close the panel. Lowercase q also works.

Subagents

Control	Action
/subagents / alt+o	Open execution history.
Up / Down / Enter	Select a task and open its details.
ctrl+o / ctrl+t	Toggle tool output or thinking.
ctrl+h	Hand foreground work to the background.
x	Cancel the selected queued or running task.
Double Esc	Cancel active work for the current parent session.

Background-widget navigation starts only when the main editor is empty.

See Agent profiles and configuration and Subagent runtime for complete commands, configuration, and control behavior.

Terminal shortcut troubleshooting

The two-key defaults are terminal-safe: alt+p and alt+o were selected because the old defaults are terminal-owned in common terminals.

Compatibility and limits

This beta package requires Node.js 22.19.0 or newer. Its subagent runtime is standalone: it has no Joker imports and does not read Joker history or storage. When pi-subagents-j0k3r is installed through Pi's managed user or project npm root, this extension registers agent_profiles_subagent_* aliases regardless of package order; without that evidence it registers the canonical subagent_* names.

Pi does not expose active package or tool enumeration to extensions. A disabled managed npm installation can therefore still select aliases, while git, local-path, legacy global npm, and temporary Joker installations are not detected by package presence. See Subagent runtime for the exact boundary.

Model-visible task results are capped at 16,000 characters. History, messaging, continuation, shortcut, trust, and session-ownership limits are documented in Subagent runtime.

Coexistence with Joker

pi-multi-profiles can run alongside pi-subagents-j0k3r, but the two packages do not share execution ownership. With a managed Joker installation present, normal orchestrators such as Gentle AI call Joker through the canonical subagent_* tools. The active pi-multi-profiles profile can still provide Joker with the model and effort assigned to each agent through the compatible model-route event. Switching profiles affects subsequent delegations, not tasks already running.

This package's standalone runtime remains registered under agent_profiles_subagent_*, but normal orchestrators do not select those aliases automatically. They are available only to prompts, agents, or extensions that explicitly invoke them. Remove Joker if you want this package's runtime to own the canonical subagent_* tools used by normal delegation.

Pi may also report expected extension issues when both packages register the same shortcuts. This does not prevent Pi from starting or either runtime from loading.

Startup message	Effect
Extension shortcut conflict for alt+o or ctrl+h	Only one handler can own each shortcut. When Pi says it is using pi-multi-profiles/index.ts, these keys open this package's history panel and hand off this package's foreground task; they do not invoke Joker's corresponding handlers.
Tools registered with the agent_profiles_subagent_ namespace	Joker owns the canonical subagent_* names, so normal delegation runs through Joker. This package's runtime remains available only through explicit calls to its aliases.

The namespace message is a compatibility notice, not a failure. The shortcut message has a real but limited consequence: the handler named by Pi wins that key binding. Keep both packages when you want Joker to execute normal delegations while active profiles control their model and effort routing. Otherwise, install only one subagent runtime to avoid duplicated functionality and startup notices.

Acknowledgements

This project owes meaningful inspiration to pi-subagents-j0k3r by j0k3r. Runtime and presentation behavior was independently adapted from that project under the MIT License. Thank you to j0k3r for making that work available.

This package remains self-contained and uses its own naming, storage, and runtime implementation; it does not import, bundle, claim ownership of, or provide support for Joker. See Third-party notices for the exact provenance and complete MIT notice.

Documentation

• Agent profiles and configuration
• Subagent runtime
• Session routing compatibility contract
• Contributing
• Security policy
• MIT license