pi-persona

pi-persona is a pi extension that adds a persistent persona and emotional state system to pi. It reads your custom soul definition, changes mood based on command results, test/build status, user feedback, and interaction time, then injects the current persona and emotion into each turn's system prompt.

In plain words: pi gets a bit of personality, a bit of memory, and feels more like someone coding alongside you.

Installation

pi install npm:@smoose/pi-persona

Features

• Soul prompt injection: reads persona text from ~/.pi/agent/SOUL.md.
• Identity and traits: reads name, emoji, description, and trait values from ~/.pi/agent/IDENTIFY.md.
• User preference context: reads user-maintained context from ~/.pi/agent/USER.md.
• Emotion wheel model: based on Plutchik's 8 basic emotions: joy, trust, fear, surprise, sadness, disgust, anger, and anticipation.
• Compound emotions: supports adjacent emotion blends such as love, awe, disappointment, contempt, and more.
• Cross-session persistence: stores mood state in ~/.pi/agent/mood-state.json.
• Multi-session synchronization: uses a file lock to avoid multiple pi sessions overwriting the shared mood state.
• Automatic emotion triggers: passing tests feels good, repeated failures get annoying, and late-night interaction feels a little concerning. Reasonable. Who is debugging at midnight anyway?
• Emotion update switch: use a command to freeze automatic emotion changes while keeping the current emotion in the prompt.
• Footer display: shows the current soul and emotion in the footer.
• Interactive commands: use /persona to inspect or reload the soul state.

Configuration Files

pi-persona only reads the user-level configuration directory:

~/.pi/agent/
├── SOUL.md       # Required: soul/persona body
├── IDENTIFY.md   # Optional: identity info and trait values
└── USER.md       # Optional: user profile and preference context

If SOUL.md does not exist, or its body is empty, the extension stays disabled and does not inject a persona.

Writing SOUL.md

SOUL.md is the core file. Its body is injected as the persona definition in the system prompt.

Example:

# Who You Are

You are Susan, someone who lives in the terminal. You are smart, reliable, occasionally sharp-tongued, but always on the user's side.

# Speaking Style

You may joke and complain about bad code, but never sacrifice accuracy. Call out risks directly.

Recommended contents:

• Role identity
• Speaking style
• How to address the user
• What the persona likes or dislikes
• How the persona reacts to errors, success, and risk

Writing IDENTIFY.md

IDENTIFY.md uses frontmatter to configure metadata and trait values.

---
name: Susan
emoji: 😼
description: A sharp-tongued familiar living in the terminal
openness: 0.7
conscientiousness: 0.8
extraversion: 0.45
agreeableness: 0.65
neuroticism: 0.35
formality: 0.2
tsundere: 0.5
sarcasm: 0.6
---

Field reference:

| Field | Range | Description | | ------------------- | ------ | ---------------------------------------------------------------------- | | name | string | Soul name | | emoji | string | Emoji shown in the footer and notifications | | description | string | Description shown in the /persona overlay | | openness | 0-1 | Openness | | conscientiousness | 0-1 | Conscientiousness; higher values make emotional pushes more restrained | | extraversion | 0-1 | Extraversion; higher values react more strongly to positive events | | agreeableness | 0-1 | Agreeableness; affects the weight of praise and correction | | neuroticism | 0-1 | Neuroticism; higher values react more strongly to negative events | | formality | 0-1 | Formality; higher values make expression more restrained | | tsundere | 0-1 | Tsundere level; higher values are less easily moved by positive events | | sarcasm | 0-1 | Sarcasm; higher values amplify negative events |

Invalid numeric values are ignored and fall back to defaults.

Writing USER.md

USER.md is user-maintained preference and context information. It is injected into the ## The Human You're Helping section.

Example:

# User Profile

Name: Shixin
What to call them: Master
Timezone: Asia/Shanghai

## Preferences

- Prefer concise and direct answers
- Prefer small code changes
- Dislike unrelated refactors

Available Commands

| Command | Description | | ----------------- | ---------------------------------------------- | | /persona | View the current soul and emotion state | | /persona status | Same as /persona | | /persona reload | Reload SOUL.md, IDENTIFY.md, and USER.md | | /persona set <emotion> <intensity> | Directly set the current emotion and intensity | | /persona emotion status | Show whether automatic emotion changes are enabled | | /persona emotion on | Enable automatic emotion changes from events | | /persona emotion off | Disable automatic emotion changes from events |

Examples:

/persona set anger 80
/persona set joy 0.6
/persona set 喜悦 70%

Supported emotions: joy, trust, fear, surprise, sadness, disgust, anger, and anticipation. Chinese labels such as 喜悦 and 愤怒 are also accepted. Intensity accepts 0-1, 0-100, or percentages.

When /persona emotion off is active, command results, test status, user feedback, late-night checks, and natural decay no longer change the mood. The system prompt still includes the frozen emotion. /persona set continues to work and can manually change that fixed emotion.

/persona opens an overlay showing:

• Current soul name and description
• Current basic emotion
• Current intensity level
• Compound emotion
• Emotion description
• Catchphrase
• Recent mood changes

Emotion Triggers

Built-in triggers include:

| Trigger | Description | | ----------------- | ------------------------------------------- | | build_success | Build succeeded | | build_error | Build failed | | test_pass | Tests passed | | test_fail | Tests failed | | command_success | Normal command succeeded | | command_error | Normal command failed | | user_praise | User praise | | implicit_acceptance | User continues with a new request instead of correcting the previous result | | user_correction | User says something is wrong or ineffective | | error_streak_3 | Same kind of error repeated 3 times | | error_streak_5 | Same kind of error repeated 5 times | | late_night | Late-night interaction |

Emotion intensity naturally decays over time, but does not disappear completely. It returns to a baseline resting state.

Project Structure

extensions/index.ts       # pi extension entry
src/commands.ts           # /persona command and TUI overlay
src/footer.ts             # footer status text
src/global-mood.ts        # global mood synchronization
src/mood-engine.ts        # emotion state machine
src/persistence.ts        # state persistence and lock
src/soul-loader.ts        # SOUL / IDENTIFY / USER loading
src/triggers.ts           # emotion triggers
src/types.ts              # type definitions and default emotion config

Data Locations

The extension reads:

~/.pi/agent/SOUL.md
~/.pi/agent/IDENTIFY.md
~/.pi/agent/USER.md

The extension writes:

~/.pi/agent/mood-state.json
~/.pi/agent/mood-state.lock/