# Commands and settings

## Commands

Arguments support tab completion. Names are case-sensitive paths relative to the prompt directory, such as `review/backend.md`. Names with spaces need no quotes.

| Command | Behavior |
| --- | --- |
| `/system-prompt` | Opens the picker and enables the selected file. |
| `/system-prompt use <name>` | Selects and enables a file. `.md` is optional when unambiguous. |
| `/system-prompt mode [mode]` | Opens the mode picker or sets `prepend`, `append`, or `replace`. Keeps the enabled state. |
| `/system-prompt list` | Lists files. An asterisk marks the selection, even when disabled. |
| `/system-prompt status` | Shows the enabled state, selection, mode, paths, and errors. |
| `/system-prompt toggle` | Toggles the selected file. Checks the file before enabling it; requires a selection. |
| `/system-prompt view [name]` | Previews the selected prompt and mode, or reads a named file without selecting it. |
| `/system-prompt help` | Shows usage. |

Pickers require dialog support. Explicit commands also work with RPC clients, except the viewer, which requires terminal mode.

## Full-screen viewer

The viewer displays wrapped plain text and removes terminal control sequences. It does not edit files or start a model request.

| Key | Action |
| --- | --- |
| Up, Down, `k`, `j` | Scroll one line. |
| Page Up, Page Down, Space | Scroll by page. Space moves down. |
| Home, End, `g`, `G` | Jump to the start or end. |
| Esc, `q`, Ctrl+C | Close. |

Pi's selection keys also apply. Mouse wheel scrolling works when Pi forwards mouse events.

With no name, `view` rereads the selected file, expands placeholders, and applies the current mode. Selection, toggle, mode, and file changes appear immediately, before another message is sent. Viewing does not save settings. With a name, `view` shows the file's source, including unexpanded placeholders.

The preview uses the incoming prompt and placeholder values captured at the start of the most recent run. Before the first run in a session, it uses Pi's current prompt and context. Disabling the extension previews that incoming prompt. Earlier extensions' changes appear after a run; later extensions and provider-specific changes are outside this preview. If the selected file cannot be read or expanded, the viewer reports an error.

## Prompt directory

Prompts live in `~/.pi/agent/system-prompts/`. `PI_CODING_AGENT_DIR` moves both the prompt directory and settings file.

Discovery includes regular Markdown files in subdirectories, including hidden files, with a case-insensitive `.md` extension. It excludes symlinks. Reads reject paths outside the prompt directory. A missing directory is an empty library.

Each entire UTF-8 file is one prompt, including headings, frontmatter, and whitespace. Known placeholders expand as described below. Empty or whitespace-only files are rejected. Selecting a file does not load other files.

## Placeholders

The extension expands these case-sensitive placeholders before each run, before applying the selected mode. Spaces or tabs inside the braces are optional, so `{{ cwd }}` also works.

| Placeholder | Value |
| --- | --- |
| `{{system_prompt}}` | The complete incoming system prompt, including earlier extensions' changes. |
| `{{cwd}}` | Pi's current working directory. |
| `{{skills}}` | Pi's available skill list and loading instructions. Respects disabled skills and available reader tools. |
| `{{project_context}}` | Pi's loaded project instructions, including `AGENTS.md`, with their file paths. |
| `{{docs}}` | The contents of the incoming prompt's `<docs>` section, including Pi documentation paths and instructions. |
| `{{rules}}` | The contents of the incoming prompt's `<rules>` section, including tool guidelines and extension additions. |

Section values omit their outer section tags. Project instructions retain their `<project_instructions>` tags. Skills use Pi's formatter, which includes skill names, descriptions, and file locations. The placeholder does not read full skill files.

Dynamic sections use Pi 1.4's prompt format and context API. Without that API, `{{skills}}` and `{{project_context}}` report an error. Missing docs or rules sections and empty skill or context lists expand to empty strings. Earlier extensions' explicit skill and project context section overrides also apply.

Unknown placeholders remain literal text. Expansion makes one pass over the prompt file. Inserted values are not expanded again. Placeholders do not execute shell commands or JavaScript.

All three modes retain their usual behavior. In append or prepend mode, `{{system_prompt}}` duplicates the incoming prompt. Replace mode includes only the file's expanded content. An expansion that leaves the whole file empty or whitespace-only reports an error and keeps the incoming prompt.

## Prompt behavior

The extension starts disabled with no selection and `append` mode. Selecting a file enables it.

It changes `event.systemPrompt` during `before_agent_start`. Given an incoming prompt `base` and expanded file content `custom`:

| Mode | Result |
| --- | --- |
| `prepend` | `custom + "\n\n" + base` |
| `append` | `base + "\n\n" + custom` |
| `replace` | `custom` |

If `base` is empty, every mode returns `custom` without a separator.

The incoming prompt includes earlier extensions' changes. Later extensions can modify this result. Replace includes incoming instructions only through placeholders in the file. Without placeholders, it removes Pi context, `AGENTS.md`, skills, and command-line prompt additions. It does not remove tool definitions or history. Text position does not guarantee instruction priority.

The file is read before each run, without accumulating copies. File edits and command changes during a run apply to the next run.

If the file is missing, unreadable, empty, outside the directory, or cannot be expanded, the extension keeps the incoming prompt and reports an error. It retries next run. The TUI footer shows `system-prompt: error`; identical errors do not repeat notifications. Print and JSON modes report errors to standard error.

The `system-prompt` status line is only set in Pi's TUI. RPC clients (which report `hasUI: true` but run with mode `rpc`) do not receive it, because there `setStatus` is delivered as a popup notification.

## Saved settings

Settings live in `~/.pi/agent/system-prompts/system-prompt.json`, alongside the prompt files.

To keep existing settings, move `~/.pi/agent/system-prompt.json` into `~/.pi/agent/system-prompts/` before reloading the extension.

```json
{
	"enabled": true,
	"prompt": "reviewer.md",
	"mode": "append"
}
```

`enabled` is a boolean, `prompt` is a relative Markdown path or `null`, and `mode` is `prepend`, `append`, or `replace`.

Settings commands save all fields through a temporary file and rename. In-memory state changes after saving succeeds. New settings files have owner-only permissions where supported. Commands do not edit prompt files.

Settings supply defaults for future processes. Other running Pi processes keep their state. Session switches and forks keep the current selection; resumed conversations use current settings.

Invalid settings disable the extension and appear in `status`. Commands refuse to overwrite them. After repairing or removing the settings file, `/reload` reads it again.

## Startup flags

| Flag | Behavior |
| --- | --- |
| `--system-prompt-name <name>` | Selects and enables a prompt for this process. |
| `--system-prompt-mode <mode>` | Overrides the mode without enabling the prompt. |

Pi reserves `--system-prompt` for its built-in option. Startup flags do not save settings. A later settings command saves the current state, including overrides.

An invalid flag disables the custom prompt for the process without changing saved settings. A successful settings command clears the flag error.