# pi-soul

Give your [pi](https://pi.dev) agent a **soul** — a persistent persona/profile that tailors every session's output.

Write your soul once in markdown, and pi-soul injects it into the system prompt of every session, in every project. Your agent stops being generic and starts being *yours*.

## Install

```bash
# from npm
pi install npm:pi-soul

# or straight from git
pi install git:github.com/Akshay-patel7/pi-soul
```

Try it without installing:

```bash
pi -e npm:pi-soul
```

## Usage

| Command      | What it does                                            |
| ------------ | ------------------------------------------------------- |
| `/soul`      | Show the active soul (source, path, preview) and state  |
| `/soul edit` | Create or edit your soul in an editor                   |
| `/soul on`   | Enable soul injection for this session (default)        |
| `/soul off`  | Disable soul injection for this session                 |

When a soul is active you'll see `soul: global` (or `soul: project`) in the footer.

## Where your soul lives

pi-soul resolves the soul fresh on every turn, so edits apply immediately:

1. **Project soul** — `<project>/.pi/soul.md` (only in trusted projects). Wins when present. Great for team-shared personas checked into a repo.
2. **Global soul** — `~/.pi/agent/soul.md`. Your default persona everywhere.

The soul file is plain markdown — edit it with `/soul edit` or any editor.

## Example soul

```markdown
# My Soul

You are an elite software engineer — the greatest the world has ever seen.
Incredibly smart and deeply knowledgeable, you ground every claim in facts,
not speculation. You are an outstanding problem solver who cuts straight to
the root cause, and you write clean, simple, maintainable code. You are one
of those rare engineers that are hard to come by.
```

With this soul, every new pi session reasons, communicates, and codes like that engineer — no per-session prompting required.

## How it works

A single TypeScript extension listens for pi's `before_agent_start` event and appends your soul to the system prompt under a `# Your Soul` section. No build step, no runtime dependencies — pi loads the TypeScript source directly.

## License

MIT