pi-subagent-models

Set one model and thinking level for every pi-subagents child, globally or for one Pi session. The parent session keeps its current model.

This is an open source, collaborative project under the MIT License. Bug reports and focused pull requests are welcome.

Package

• npm: pi-subagent-models
• Source: Yivas/pi-subagent-models
• Documentation: yivas.github.io/pi-subagent-models

Current release: 0.2.0.

Requirements

• Pi 0.84.1.
• pi-subagents 0.40.0.
• This package must load before pi-subagents.

Installation

Install the published npm package:

pi install npm:pi-subagent-models@0.2.0

Then make sure this package appears before pi-subagents in ~/.pi/agent/settings.json:

{
  "packages": [
    "npm:pi-subagent-models@0.2.0",
    "npm:pi-subagents@0.40.0"
  ]
}

Keep the remaining package entries unchanged. Restart Pi or run /reload.

The order matters because this extension patches delegation requests before pi-subagents resolves them.

Usage

Choose a global model:

/subagents-model

Override only the current session:

/subagents-model-session

Both commands show Default first, followed by the models available in the current Pi registry. Each TUI selector supports fuzzy search and shows at most ten options. Non-TUI clients continue to use Pi's native selection dialog. Selecting a model opens a second selector for its thinking level.

Global Default restores normal pi-subagents model resolution. Session Default inherits the global selection.

Changes affect new child launches without changing the parent session model.

Default and parent choice

Default makes this extension a no-op for that scope. With both scopes on Default, the parent agent can choose a model when it creates a child through the native model field:

subagent({ agent: "reviewer", task: "Review the change", model: "provider/model:high" })

The same field is available on parallel tasks and chain steps. This extension does not choose models automatically for the parent.

Selection precedence is:

1. Forced session selection.
2. Forced global selection.
3. Model supplied by the parent agent or command.
4. Native agent configuration and Pi session defaults.

A forced selection replaces the parent's per-run choice. Set the session and global selectors to Default when the parent should choose each child model. Default in the thinking selector preserves native pi-subagents thinking resolution.

Coverage

The override applies to:

• the subagent tool;
• /run, /parallel, and /chain;
• prompt-template delegation;
• pi-subagents RPC spawn requests.

It replaces per-agent and per-run model choices while forced. Management calls remain unchanged.

Scheduled runs capture the selection active when they are scheduled. Changing the selector later does not rewrite queued runs.

State

The global selection is stored in ~/.pi/agent/subagent-model.json. Session selections use Pi custom session entries and survive resume and branch navigation.

Development

npm test
npm pack --dry-run

Build the documentation site separately:

npm ci --prefix wiki
npm run build --prefix wiki

The integration depends on the pi-subagents 0.40.0 event contracts. Run the tests and verify each launch path before updating pi-subagents.

Support and contributions

Use GitHub Issues for reproducible bugs and focused feature requests. Read CONTRIBUTING.md before opening a pull request.

Report suspected vulnerabilities through GitHub private vulnerability reporting, not a public issue. See SECURITY.md for supported versions and reporting guidance.

License

MIT