pi-prompt-profiles

Model-aware system prompt profiles for Pi, written in Markdown and switched without restarting Pi.

Version 0.11.1, verified offline against Pi 0.85.1 and 1.4.0.

Website · Install · Command reference · Releases · Contributing

pi-prompt-profiles keeps your system prompts as plain Markdown files, lets you switch the active one per session, and binds a profile to a model so it is chosen automatically. The active profile is prepended to the prompt Pi would send anyway, so tools, AGENTS.md, skills and every other instruction Pi loaded stay in place.

Why

Pi already composes a system prompt from its own instructions, project context and skills. This extension adds one layer above that composition, without rewriting it: a profile you can version, keep per project, and attach to a model family. It does not choose the model, change the provider, or route execution.

Status

• Version 0.11.1. First public release 0.1.0.
• Published on npm as pi-prompt-profiles.
• Verified offline against Pi 0.85.1 and 1.4.0, with the cache and coexistence limits described below. See docs/compatibility.md for the exact contracts.

Requirements

• Pi 0.85.1 or another version you have verified yourself.
• Node.js 22.19 or newer for development and tests.

Install

pi install npm:pi-prompt-profiles@0.11.1

Load it for a single run without changing your settings:

pi -e npm:pi-prompt-profiles@0.11.1

From a local checkout instead:

git clone https://github.com/Yivas/pi-prompt-profiles
cd pi-prompt-profiles
npm install
pi install /path/to/pi-prompt-profiles

Installing writes to your Pi settings; it does not copy or touch your profiles.

Your first profile

Create a profile body and, optionally, a default in config.json:

<agentDir>/system-prompts/
├── config.json
└── profiles/
    └── base.md

<agentDir> is what Pi resolves through getAgentDir(). config.json:

{
	"version": 1,
	"selection": { "mode": "auto" },
	"defaultProfile": "global:base"
}

profiles/base.md is just Markdown. Everything in it becomes part of the system prompt when the profile is active:

Work in small, verifiable steps. State your assumptions when a request is
ambiguous, and ask before changing scope.

Reload with /sp reload. A project can add its own profiles under <projectDir>/.pi/system-prompts/; those are read only when the project is trusted.

A complete fictional example lives in examples/.

Commands

Run /sp with no arguments for a guided menu. The everyday commands:

The full command and flag reference lives in the wiki. /sp use and /sp auto change only this session; they do not modify config.json.

Profile and model pickers filter as you type and keep the list within the screen, so a large model catalog never pushes the dialog off the screen.

Flags

Non-interactive runs can start with a selection:

pi --sp-profile review
pi --sp-profile project:local
pi --sp-auto
pi --sp-off

Combining two of them is rejected and reported; the extension then follows your normal configuration.

Precedence

Selection: session (flag or /sp use) > trusted project config > global config

auto.

In auto mode: project bindings, then global bindings (unless the project sets inheritGlobalBindings: false), then the project defaultProfile, then the global one, then nothing (Pi keeps its native prompt). Explicit rules come before defaults. Higher priority wins, then the most specific rule; * matches any characters including /.

Inside a subagent, subagents decides what may apply: bindings (the default) only an explicit binding for the child's model, inherit the normal resolution and off nothing. Only processes that mark themselves as subagents are affected.

The full resolution and composition rules are documented in the wiki.

Trust and privacy

Project profiles and bindings are ignored unless ctx.isProjectTrusted() is true. The extension reads files only from the Pi agent directory and, when trusted, the project's .pi/system-prompts. It opens no network connections, runs no commands from profile text, and sends no telemetry. /sp preview and /sp edit show profile text on purpose; treat them as private.

Coexistence

• SYSTEM.md / APPEND_SYSTEM.md and Pi's built-in prompt are preserved. The extension never sets customPrompt, so native tool and documentation instructions are not dropped.
• AGENTS.md context and skills are preserved and stay below the managed block.
• The profile is delivered by returning the complete prompt from before_agent_start, composed from whatever Pi and earlier extensions produced. A managed block already present is removed before exactly one is prepended, so another extension that appends to event.systemPrompt keeps the block in either load order. An extension that returns its own prompt after this one replaces the chained value and can still drop the block; the warning reports it.
• While a profile is active, the request carries a complete prompt, so Pi cannot apply its native system-section deltas to it: adding a tool during a run rebuilds the system header, and prompt snippets and guidelines of a tool activated mid-run are absent until the next run. A structured section contributed by an extension that runs later is not part of that run's prompt either. With no profile selected, Pi keeps its own prompt and deltas. Cache hits are a provider concern either way.
• Delivery is observed, not assumed: a recognized payload without the block produces a warning and not in payload in the footer, and an unrecognized format reports payload unverified.

Errors and degraded mode

If the configuration is invalid, the version is unknown, a profile is missing or an inheritance chain is broken, the extension reports the problem and lets Pi use its native prompt. Selection and payload observation are reported separately; a selected profile is not proof of delivery. A failed selection change keeps the previous valid state.

Uninstall

pi remove /path/to/pi-prompt-profiles

or remove the entry from Pi's settings. Uninstalling does not delete system-prompts/ in your agent directory or your project. Delete those folders yourself if you want to remove the data.

Documentation

• Wiki — guides, command reference and troubleshooting.
• docs/architecture.md — design, data flow, resolution.
• docs/compatibility.md — verified Pi contracts and limits.
• examples/ — a fictional global setup.
• schema/config.schema.json — config JSON Schema.

Development

npm install
npm run typecheck
npm run lint
npm test
npm run bench   # local resolution benchmark

The test suite uses the installed Pi packages and a simulated provider payload. It needs no API key and sends nothing over the network.

Contributing, support and license

Issues and pull requests are welcome; see CONTRIBUTING.md. Security reports follow SECURITY.md.

Released under the MIT License.