Give Pi a small set of task-based model roles so it can select the right configured model and reasoning effort for a new prompt. You define the boundaries; Pi keeps your explicit model choices in control.
Requirements: Pi, Node.js 22.19+, npm, Git, and provider access already configured in Pi.
pi install git:github.com/spksoft/pi-model-rolesRestart Pi or run /reload.
-
In Pi, open settings:
/model-roles settings -
Choose Auto Setup, the automatic role-configuration mode and first Settings item. Select one to eight available models to consider, then confirm the research disclosure.
-
After research settles, Auto Setup opens the review automatically. Review evidence, model/effort trade-offs, and before/after role settings. Use Discuss/refine to state your workload and priorities—for example, “Favor reliability for cross-file debugging; keep routine edits inexpensive.” Confirm the exact configuration diff to save it.
Auto Setup generates proposed roles by considering combinations of each selected model and its supported reasoning efforts against your existing roles and settings. One model can serve several distinct roles at different efforts—even if it is the only candidate. It chooses justified pairs for distinct task types, not one role per possible pair or a fixed role count; ambiguous tasks fall back to default. Without stated priorities, its guidance balances reliability, latency, and cost; recommendations are not measured guarantees. See how recommendations are designed.
Auto Setup uses the current Pi agent and any tools you already enabled; it does not switch your active model or apply changes without confirmation. With only the inherited default role, Pi makes no extra selection request. When custom roles exist, the default model (or your optional independent selector profile) classifies eligible new prompts: one clear match uses that role; no match or overlapping matches use default.
Run these inside Pi:
| Command | Use |
|---|---|
/model-roles |
Open the main menu to reach every command below. |
/model-roles settings |
Add, edit, delete, or review roles; Auto Setup is the first item. |
/model-roles use <role> |
Choose a role for the current session without classification. |
/model-roles disable |
Pin the current model and effort by pausing automatic selection. |
/model-roles enable |
Allow the next eligible prompt to be selected automatically. |
/model-roles run /command [arguments] |
Select a model, then invoke a registered command while idle; respects manual/disabled routing. |
/model-roles context [prompt|conversation|full] |
Choose prompt-only, bounded conversation, or separately consented newest tool-output context. |
/model-roles selector |
Choose/reset an independent selector model and optional effort, with provider/cost disclosure. |
/model-roles why |
Explain the last selection without displaying private task/history text. |
Manual model or reasoning-effort changes also pause automatic selection. Your Pi defaults are never rewritten. Disable pauses this session even if saving fails; enable resumes only after the global toggle is saved successfully.
Routing scope: selection runs before a new idle TUI submission, including registered prompt templates such as /plan <description> and /skill:name <task>. It classifies the command and arguments as submitted, before expansion—not the template/skill body. Extension-owned commands (as opposed to prompt templates), tool-loop turns, and headless/child sessions are not automatically routed. See supported contexts and limitations.
New installations default to bounded conversation context, so selection can interpret follow-ups such as “implement that” using recent retained dialogue and summaries. Existing config files without selectorContext stay prompt-only; to enable it there, run:
/model-roles context conversation
Review the privacy disclosure before confirming. A clear same-task continuation can retain the existing eligible role; changed scope is reclassified, and ambiguity still falls back. Need recent raw tool calls/results too? /model-roles context full is a separate opt-in that sends up to 100,000 UTF-8 bytes of newest retained context; it excludes raw thinking, image bytes, custom entries/messages, and !! shell commands. Use /model-roles context prompt to opt out and /model-roles why to inspect the decision. See context policy and limits.
For extension-owned commands that skip automatic routing, use the explicit wrapper:
/model-roles run /execute-plan docs/plan/feature.html
The target command must already be installed. The wrapper routes from its name and arguments, then invokes the original command unchanged—no changes to Pi or the command's package are needed. It selects the parent session model, not any subagent models. Run /model-roles enable first if selection is paused. See command routing, privacy, and recovery.
The optional native subagent example and its integration test require a normal parent process, not a subagent child. See native verification context; never clear inherited safety flags to run it.
You can also add roles yourself in /model-roles settings. Add a custom role only for a clearly different task type, then choose its model and a supported reasoning effort. A useful description says when the role applies, for example:
Use when the task is a localized, low-risk edit with an explicit outcome and no design decision.
Keep role descriptions distinct. If multiple roles match, Pi uses default instead of depending on role order.
The initial file keeps Pi's existing defaults:
version: 1
enabled: true
selectorTimeoutMs: 8000
selectorContext: conversation
roles:
default:
model: inherit
effort: inheritUse Settings instead of editing YAML unless you need the detailed options in the configuration guide.
Custom roles can add one selector request before an eligible idle TUI submission, including /model-roles run. New installations default to conversation: the selector receives submitted task text and role descriptions plus bounded recent dialogue and existing summaries. Existing config files omitting selectorContext remain prompt-only (task text and role descriptions only); full requires a separate opt-in and sends up to 100,000 UTF-8 bytes of newest retained dialogue, summaries, and raw tool calls/results to the configured selector provider (default-role provider unless overridden), which may differ from execution. Full mode excludes raw thinking, image bytes, custom entries/messages, and !! shell commands. Neither mode secret-filters text, and retained skill text may be included in full mode. No extra summarizer or repository scan is added. The selected model receives Pi's normal task context. Auto Setup uses the current agent and any tools you have enabled. See cost and privacy safeguards.
Selector improvements and their remaining limits are tracked in selector evidence and evaluation. The credential-free demo is a harness check, not evidence of semantic superiority.
- Configuration and role design — settings, YAML, Auto Setup, limits, and recovery.
- Architecture and routing flow — how selection, persistence, Pi lifecycle integration, and Auto Setup fit together.
- Integration API — use selection from another extension or SDK host.
- Compatibility and troubleshooting — requirements, supported contexts, known limits, and contributor checks.
- Manual terminal checklist — maintainer-only visual acceptance checks.
- Changelog — user-visible changes.
Run these in your shell, then restart Pi or run /reload:
pi update git:github.com/spksoft/pi-model-roles
pi remove git:github.com/spksoft/pi-model-rolesRemoval keeps your role YAML so you can reinstall later. The package is currently UNLICENSED; no public npm release is assumed.