1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# `@amolith/pi-personas`
 8
 9[![pi-personas on NPM](https://img.shields.io/npm/v/@amolith/pi-personas)](https://www.npmjs.com/package/@amolith/pi-personas)
10[![Licensed under MutuaL-1.2](https://img.shields.io/badge/License-MutuaL--1.2-af2e1a?style=flat&labelColor=110402&link=https%3A%2F%2Fcodeberg.org%2FMutualism%2FMutualist-License)](https://codeberg.org/Mutualism/Mutualist-License)
11[![REUSE status](https://api.reuse.software/badge/git.secluded.site/pi-extensions)](https://api.reuse.software/info/git.secluded.site/pi-extensions)
12[![scratchanitch.dev badge](https://img.shields.io/badge/scratchanitch-dev-FFC4B5)](https://scratchanitch.dev)
13[![Liberapay donation status](https://img.shields.io/liberapay/receives/Amolith.svg?logo=liberapay)](https://liberapay.com/Amolith/)
14
15Code with a grumpy senior today and work with a patient tutor tomorrow. Switch
16between them with `/persona`. The active one persists across sessions until
17changed. Setting a persona prior to startup appends it to the system prompt.
18Changing it mid-session sends the persona content as a steering message.
19
20Personas are loaded from `persona-name.md` files in
21`$PI_CODING_AGENT_DIR/personas/`. `/persona` is interactive and `/persona grug`
22sets it directly.
23
24## Install
25
26```sh
27pi install npm:@amolith/pi-personas
28```
29
30## Write personas
31
32Create one markdown file per persona in `$PI_CODING_AGENT_DIR/personas/`:
33
34```text
35$PI_CODING_AGENT_DIR/personas/grumpy-senior.md
36$PI_CODING_AGENT_DIR/personas/patient-tutor.md
37```
38
39The file name without `.md` is the persona name. That's what `/persona` and the
40`persona` setting use.
41
42## Switch personas
43
44Open an interactive picker:
45
46```text
47/persona
48```
49
50Switch directly:
51
52```text
53/persona patient-tutor
54```
55
56Clear the active persona:
57
58```text
59/persona none
60```
61
62`unset` and `clear` also clear the active persona.
63
64## Remember the active persona
65
66The active persona persists as the `persona` key in
67`$PI_CODING_AGENT_DIR/settings.json`:
68
69```json
70{
71  "persona": "patient-tutor"
72}
73```
74
75The extension only accepts persona names that match markdown files under
76`$PI_CODING_AGENT_DIR/personas/`.
77
78## What happens when it changes
79
80If a persona is set before startup, the extension reads it at session start and
81appends it to the system prompt for the lifetime of the session.
82
83When you set or clear a persona mid-session, the extension updates the setting
84immediately and sends a one-shot hidden reminder message. It does not rewrite
85the session's system prompt mid-stream.